Amazon Agent Flow Documentation

Amazon Agent Flow is Kuudo's AI-native data layer for Amazon operators. It uses proven data-lake patterns - durable ingestion, artifacts, Iceberg tables, scan-budgeted queries, scheduled refreshes, and lineage - but it is designed around agents as the primary users, not dashboards.

Traditional analytics tools can still read the lake. Snowflake, Athena, DuckDB, Databricks, Power BI, Tableau, and similar tools can be useful downstream consumers. They are not the center of the system. The center is an agent that needs fresh, governed, account-specific data it can retrieve, reason over, and act on without copying private business data into chat.

Use this page when you want to know what to ask, what must be connected first, which tools are involved, and how to tell whether a run actually finished.

The Bigger Picture

Agent Flow is not only a job runner or report exporter. It is the agent-facing data layer between Amazon systems, private lake storage, governed query tools, and the AI clients that need to do work.

The foundation is familiar data-lake architecture:

• Amazon SP-API (Selling Partner API) and Ads operations ingest source data.
• Large outputs land as artifacts instead of chat messages.
• Eligible outputs are delivered into open lake tables.
• Queries run with filters, result limits, and scan budgets.
• Run ids, artifacts, schedules, and delivery records preserve lineage.

The product difference is the primary user. A traditional analytics stack usually assumes a human analyst will open Tableau, Power BI, or a warehouse console. Agent Flow assumes an agent will discover operations, inspect contracts, launch durable runs, poll status, read bounded previews, pass result handles into analysis tools, and explain the next action.

The practical result is lower interactive latency. Some Amazon reports, exports, and data pulls take minutes or hours to generate. Agent Flow moves that wait into scheduled background work. The agent can refresh orders, listings, inventory, finance, and Ads datasets on a window, land them in the local/private lake, and answer from data already local to the agent's data layer. The user waits for a bounded local query, not for Amazon to generate the report during the chat turn.

The data is also available beyond the agent that created it. Because Agent Flow exposes an MCP-native interface, any authorized MCP-native client can schedule flows, inspect deliveries, query lake datasets, or run its own downstream data process against result handles. ChatGPT, Claude, Cursor, workflow tools, or internal agent clients can all work from the same governed agent lake instead of each one pulling from Amazon separately.

Two Parts: Pipelines and Queries

Agent Flow has two connected surfaces. The first creates the data layer. The second lets agents use it.

Those surfaces can be used by the same agent or by different authorized clients. One MCP-native client might schedule the daily Amazon reports, another might query the lake for an ads diagnosis, and a third might run a sandboxed analysis over the latest result handle. The shared contract is the Agent Flow MCP surface and the governed lake underneath it.

What Agent Flow Does

Agent Flow turns Amazon work and Amazon data into a layer agents can use repeatedly. The named operations create or refresh the data, schedules keep slow Amazon outputs warm, the lake keeps it cost-effective and scalable, and the query and analysis tools expose only the slices an agent needs for the next decision.

Instead of asking an assistant to improvise against Amazon APIs, you ask it to build or use the data layer:

1. Find the right operation.
2. Inspect the operation's required input.
3. Bind the run to a registered Amazon account.
4. Start the durable run.
5. Schedule it if the data should be warm before an agent needs it.
6. Watch status until it completes or needs attention.
7. Deliver or read the result, artifact, or lake table.

The runtime is built for work that may take longer than a single chat turn: paginated order pulls, asynchronous Amazon reports, scheduled jobs, report downloads, retries after throttling, and data delivery into Iceberg tables.

When to Use It

Use Agent Flow for Amazon workflows that need durability, auditability, or repeatable data delivery.

If your first consumer is a dashboard, the lake can still be useful. If your first consumer is an agent that needs to do work, Agent Flow is the primary interface.

What You Need First

Agent Flow needs at least one connected Amazon capability. The exact requirement depends on the operation.

For Kuudo Cloud, Kuudo helps provision the runtime and connector MCP servers in your cloud. For self-hosted deployments, the Agent Flow server expects external MCP servers for Amazon SP and Ads.

The source runtime uses these default local MCP targets:

Those connectors still require the underlying Amazon permissions, profiles, marketplaces, and API access. Agent Flow does not create Amazon approvals or bypass Amazon limits.

How Activation Works

Activation means giving Agent Flow enough context to run one durable operation against one registered account.

1. Connect the Agent Flow MCP server

In Kuudo Cloud, your AI client connects to the Agent Flow MCP endpoint Kuudo provides.

For self-hosted local work, start the server from the Agent Flow repo:

uv run agent-flow

Then connect your MCP client to that server. If you are using the REST control plane instead of MCP tools, the same concepts are available through /v1/* endpoints.

2. Register an Amazon account

Each run uses an account_ref. The account stores the Amazon identity fields that should not be retyped into every prompt.

For an SP-API account, the important fields are usually:

• connector_id: amazon_sp
• account_ref: your stable name, such as seller-us-main
• identity_id: the Openbridge or connector identity id
• marketplace_id: the Amazon marketplace id, such as ATVPDKIKX0DER

For an Ads account, the important fields are usually:

• connector_id: amazon_ads
• account_ref: your stable name, such as ads-brand-us
• profile_id: the Amazon Ads profile id
• region: the Ads region, such as na

Prompt

Register seller-us-main as an Amazon SP account for marketplace ATVPDKIKX0DER using identity id 3438. Then show me the account record and confirm which fields will be bound automatically on future runs.

MCP tools the assistant may use

• upsert_account
• get_account
• list_accounts

If the credential store is enabled, the assistant may also use create_account_credential. Credentials are accepted as plaintext input to the tool and stored encrypted at rest; the tool returns redacted metadata, not the secret.

3. Find the operation

Operations are the stable units of work Agent Flow can run. They are grouped by connector, resource, lifecycle, and risk.

Useful filters:

• resource: examples include orders, reports, campaigns
• lifecycle: transactional_query, paginated_query, async_report, mutation
• risk_level: read, export, mutation, financial

Prompt

I need orders data for seller-us-main. Before you run anything, show me the safe options Agent Flow can use.

MCP tools the assistant may use

• list_amazon_sp_operations
• list_amazon_ads_operations

4. Inspect the operation schema

Before running an operation, inspect its input schema. Some fields are account-bound and should come from account_ref; other fields must be supplied in the run payload.

Prompt

For the orders option you recommend, tell me what information you need from me and what will be filled in from seller-us-main.

MCP tools the assistant may use

• get_amazon_sp_operation
• get_amazon_ads_operation

5. Start the run

For normal use, start the asynchronous durable run and poll it. Use sync tools only for short smoke tests or local demos.

Prompt

Show me orders from the last 24 hours for my seller-us-main seller account. Use Agent Flow if the data needs to be refreshed.

The assistant should translate that plain request into a durable run, return the run_id when available, and poll until the run completes or needs attention.

MCP tools the assistant may use

• run_amazon_sp_operation
• run_amazon_ads_operation
• get_flow_run

The REST equivalent is:

curl -X POST http://127.0.0.1:8080/v1/operation-runs \
  -H 'X-Agent-Flow-Tenant: tenant-a' \
  -H 'content-type: application/json' \
  -d '{
    "connector_id": "amazon_sp",
    "operation_id": "<operation-id>",
    "account_ref": "seller-us-main",
    "payload": {}
  }'

Then fetch status:

curl http://127.0.0.1:8080/v1/operation-runs/<run-id> \
  -H 'X-Agent-Flow-Tenant: tenant-a'

Operation Mechanics

Agent Flow operations are not generic prompts. Each operation has a contract.

Lifecycles

Durability

Agent Flow uses DBOS-backed workflows for operation execution. That means a run can be inspected by run_id, resumed after runtime recovery, retried where allowed, and audited through its recorded state.

For Amazon reports, equivalent active report requests attach to the same scheduler job instead of creating duplicate Amazon reports. The scheduler owns create, poll, terminal status, and download state.

Artifacts

Large outputs are written as artifacts instead of being pasted into chat. A typical artifact path includes:

{artifact_root}/{source}/{flow_id}/{run_id}/{step_name}/{artifact_kind}/{filename}

For example, an SP orders run can write raw orders under an amazon_sp flow path, while a listings report can write the downloaded Amazon report document as a raw report artifact.

Lake delivery

Lake delivery is the cost and scale layer behind the agent experience. Operations can write local lake-shaped artifacts first, then optionally deliver them to an Iceberg destination.

The zero-config floor uses iceberg_local. Production deployments can use destinations such as Cloudflare R2 or AWS Glue Iceberg when configured. Open table formats make the data usable by warehouses and BI tools, but the default access path is agent-native: result handles, bounded previews, scan budgets, lineage, and server-side analysis.

This is also where Agent Flow changes latency. A scheduled report may still take Amazon minutes or hours to produce, but that wait happens before the agent needs the answer. Once delivered, the data is local to the agent's operating layer, so the next question can use a bounded lake query instead of starting a fresh Amazon report and waiting for it to finish.

Client SQL addresses tables uniformly as:

lake.<namespace>.<table>

Agents should query with scan budgets and bounded result sizes, not unbounded raw SQL. For larger analysis, they should keep intermediate data server-side with read_analysis_result and run_sandbox_python instead of copying raw tables into chat context.

Tool Map

These are the Agent Flow tools users most often need in chat.

The tool surface covers both sides of the system: pipeline tools that create or schedule Amazon-to-lake data, and consumption tools that let agents query or process the delivered data.

Different deployments may expose a subset depending on enabled stores, credentials, lake providers, and admin policy.

Example Prompts

Use these as starting points in Claude, ChatGPT, Cursor, or another MCP-capable client connected to Agent Flow. The quoted prompts are written the way an end user can ask. The expected behavior explains the technical work the agent should perform behind the scenes.

Discover the right SP-API operation

I need last week's Amazon orders for seller-us-main. Before you pull anything, tell me what information you need and what data source you will use.

Expected behavior:

• The assistant filters operations instead of dumping the entire catalog.
• It calls get_amazon_sp_operation for the likely operation.
• It tells you which fields are required and which fields are account-bound.
• It waits before starting the run.

Run a read-only order pull

Show me orders for seller-us-main from July 1 through July 7, 2026. Refresh from Amazon if needed and summarize where the data was saved.

Expected behavior:

• The assistant uses run_amazon_sp_operation, not a direct Amazon call.
• It tracks the run with get_flow_run.
• It can return the run_id for audit or troubleshooting.
• It does not paste a large order payload into chat.
• It summarizes artifact metadata and record counts when available.

Create an Amazon Ads report

Pull Sponsored Products campaign daily performance for ads-brand-us from July 1 to July 7, 2026. Include spend, sales, clicks, impressions, and campaign id if available.

Expected behavior:

• The assistant uses list_amazon_ads_operations and get_amazon_ads_operation.
• It starts run_amazon_ads_operation.
• It understands that report operations can be asynchronous.
• It may use list_report_scheduler_jobs when the run attaches to a scheduler job.

Keep the run read-only

Diagnose campaign performance for ads-brand-us, but do not make any changes to campaigns, budgets, or account settings.

Expected behavior:

• The assistant filters operation discovery by risk.
• It refuses or asks for explicit approval if a requested operation is a mutation.
• It explains any limitation created by the read-only constraint.

Register a recurring schedule

Schedule the Amazon SP listings report to pull from Amazon every day at 2 AM America/New_York for my seller-us-main seller account. Show me when the next refresh will run.

Expected behavior:

• The assistant inspects the relevant report operation first.
• It creates or updates an operation schedule.
• It can call the trigger tool after the schedule exists.
• It returns the next due time and schedule name.

Query delivered lake data

What were order counts by purchase date for seller-us-main over the last 7 days? Use the latest delivered orders data and keep the answer short.

Expected behavior:

• The assistant checks lake destinations and deliveries.
• It uses query_lake_dataset or query_lake_sql with max_scan_bytes.
• It returns a small table or result handle, not unbounded raw data.

Check a record count

Show me the record count for the latest delivered orders data for seller-us-main.

Expected behavior:

• The assistant finds the latest delivered orders dataset for the account.
• It runs a bounded count query against the lake, not a fresh Amazon pull unless the data is missing or stale.
• It returns the count, dataset name, delivery timestamp, and any freshness caveat.

Run a SQL query on delivered data

Run this SQL query on the latest delivered orders data:

select count(*) as order_count from orders where purchase_date >= date '2026-07-01'

Expected behavior:

• The assistant maps the user's logical data name to the governed lake table.
• It validates that the query is read-only before running it.
• It applies a scan budget and bounded preview size.
• It returns a small result, result handle, and lineage instead of dumping raw rows.

Analyze a result in a sandbox

Which SKUs drove the most revenue for seller-us-main in the last 30 days? Use the latest orders data and keep any intermediate data out of chat.

Expected behavior:

• The assistant runs a governed query first.
• It passes the result handle to run_sandbox_python.
• It returns a bounded table and describes the lineage.

Retry a failed read/report run

Some Amazon data refreshes failed after throttling. Retry the read-only ones and do not retry anything that changes Amazon data.

Expected behavior:

• The assistant lists operation runs or relevant scheduler jobs.
• It retries only allowed read/report runs.
• It does not retry mutation runs.
• It includes the new run id and audit reason.

Activation Checklist

Before you ask Agent Flow to run production work, confirm:

• The Agent Flow MCP server or REST API is reachable from your AI client.
• The relevant connector is installed: Amazon SP MCP for SP-API work, Amazon Ads MCP for Ads work.
• The connector has valid credentials and required Amazon permissions.
• The account is registered with a stable account_ref.
• The operation exists and is enabled.
• The operation input schema has been inspected.
• The operation risk level is acceptable for the task.
• Large outputs have an artifact or lake plan.
• Mutations and financial-risk operations are covered by your approval policy.

Common Workflows

Agent-native data refresh

Start here when the agent needs fresh Amazon data before answering an operating question, especially when the underlying Amazon report or export is too slow for an interactive chat turn.

Prompt

What changed since yesterday for seller-us-main and ads-brand-us? Refresh the Amazon data if needed, then tell me which datasets are ready to query.

Use:

• Amazon Selling Partner MCP
• Amazon Ads MCP
• relevant SP and Ads operations
• artifact storage
• lake delivery
• query_lake_dataset or query_lake_sql

Scheduled low-latency agent data

Start here when the agent repeatedly needs the same Amazon data and should not wait for Amazon report generation during each conversation.

Prompt

Schedule the orders, listings, and Ads performance reports to pull from Amazon every day at 2 AM America/New_York for my seller-us-main seller account and ads-brand-us Ads account. Keep the latest data ready in the agent lake.

Use:

• Amazon Selling Partner MCP
• Amazon Ads MCP
• upsert_schedule
• report or paginated operations
• artifact storage
• lake delivery
• list_lake_deliveries

Orders and sales operations

Start here when the task depends on Seller Central orders or selling activity.

Prompt

Show me orders for seller-us-main from the last 48 hours. Refresh from Amazon if needed and summarize order count, earliest purchase date, and latest purchase date.

Use:

• Amazon Selling Partner MCP
• list_amazon_sp_operations
• get_amazon_sp_operation
• run_amazon_sp_operation
• get_flow_run

Listings report

Start here when you need listing state as a report, not a one-off catalog lookup.

Prompt

Get the current merchant listings report for seller-us-main. Tell me when it is ready and where the report data was saved.

Use:

• Amazon Selling Partner MCP
• SP reports operation
• report scheduler
• artifact storage

Sponsored Products reporting

Start here when you need Ads performance over a date range.

Prompt

Get Sponsored Products campaign daily performance for ads-brand-us from July 1 to July 7, 2026. Include spend, sales, clicks, impressions, and campaign id if available.

Use:

• Amazon Ads MCP
• Ads reporting operation
• async report scheduler
• artifact storage or lake delivery

Data-lake query

Start here after data has been delivered to an Iceberg destination.

Prompt

Show daily order count and estimated revenue after July 1, 2026 from the latest delivered orders data. Keep the answer short.

SQL prompt

Run this SQL query on the latest delivered orders data for seller-us-main:

select count(*) as order_count from orders

Use:

• list_lake_destinations
• list_lake_deliveries
• query_lake_sql or query_lake_dataset
• read_analysis_result when the result is larger than the preview

What Good Output Looks Like

A good Agent Flow answer includes:

• The operation id it chose.
• The connector and account ref.
• The risk level and lifecycle.
• The payload it submitted, with secrets omitted.
• The run id.
• Current status or terminal status.
• The data source it used: operation output, artifact, lake table, or analysis result.
• Artifact or lake delivery details when applicable.
• A bounded preview or result handle instead of a raw data dump.
• Scan budget, filters, and row limits when it queried the lake.
• Any Amazon throttling, pending report, missing permission, or retry state.
• The next action you should take.

It should not:

• Call a mutation when you asked for read-only work.
• Paste secrets into the response.
• Dump hundreds of operation summaries into chat.
• Claim a report is complete without checking the run or scheduler status.
• Query a lake without a scan budget.
• Treat an Amazon API failure as a finished business answer.

Troubleshooting

Related Material

• Amazon Agent Flow feature page explains the product surface and private lake model.
• Kuudo MCP Servers maps the broader Kuudo MCP tool model.
• Amazon Selling Partner MCP covers the SP-API connector.
• Amazon Ads MCP covers the Ads connector.
• Amazon Agent Atlas covers grounded Amazon operating knowledge for tasks that need policy, table, or playbook context.