Agent Runs

Agent runs

A run sends an AI model into a real store, as the agent, to do a task for a buyer. You give it the task; the agent makes the calls. Every run is recorded whole.

Starting a run

Runs start on Runs (you need to be signed in):

  1. The store: the first time, Runs asks Where should the agent shop? Type a domain or pick a test store: flowers.ucpsandbox.com (Retail), stays.ucpsandbox.com (Stays) or food.ucpsandbox.com (Food). Runs reads the store's UCP profile on the spot (see Endpoint discovery). The store is remembered for your workspace; switch it from the store in the header.
  2. The task: Runs asks What should the agent do at the store. Click an example, Pick (choose something), Buy (go all the way to payment) or Rely (ask about an order or a policy), or type your own. Be specific: "find me a blue t-shirt size M under $30" gives the agent criteria to act on.
  3. The settings: the pills under the message box:
    • Model: your pinned models first, then every model by lab. See Choosing models.
    • How the agent reaches the store: UCP (the store's APIs, over the MCP or REST endpoint its profile declares) or Website (the store's website, in a browser; signed in only). See WebMCP: the store page. On a store that offers a store agent or its own checkout, the UCP choices are grouped under UCP · how checkout goes: MCP, REST, Store agent · A2A 0.3 (and A2A 1.0 when its agent card offers it) and Store's checkout · Embedded. MCP stays the default. See A2A: the store's agent and Embedded: the store's checkout.
    • Who it shops for: the buyer details searches carry (country, region, postal code, currency, language). Change them from the pill or the Info pane; Settings › Agent holds the lasting copy.
    • Who the agent is: UCP platform identity (the default: the agent sends its UCP-Agent profile and signs every state-changing request) or Unsigned (no signatures at all, to see what a store does with unsigned traffic).
    • Where it runs: Playground's agent in our cloud (the default), or a personal agent, Goose or Hermes on its own machine (signed in, personal accounts, our test stores). See Personal agents.
  4. Send: press Send or Enter. The run opens on its own page, /runs/{id}, when the agent first replies.

Until you send, the Info pane shows This run will use: your choices, the store (what its profile declares) and the agent.

What happens during a run

Over UCP, the agent connects to the store's endpoint. Over MCP it uses the store's tools directly; over REST (the default for REST-only stores) it gets tool definitions from the profile's capabilities and its calls go through the REST transport. The agent decides which tools to call, in what order and with what arguments.

When the store declares shopping permalinks (dev.ucp.shopping.permalink), the agent also has open_permalink: it makes a link that opens the store with the chosen items ready, for the buyer to finish themselves. The call is in the trace with the store's redirect; nothing is ordered or paid by it.

When checkout goes to the store agent (A2A), search and product lookup still go over MCP or REST, and the checkout tools become messages to the store agent. When it goes to the store's checkout (Embedded), the agent builds the checkout over MCP or REST and stops before paying; the store's own checkout page opens beside the chat and you finish there.

A typical run follows the funnel: search the catalog, view product details, build a cart, and go to checkout. At a Stays store the same run searches stays, holds a room and books it. Text written by the merchant or third parties inside tool replies (descriptions, reviews, store notices) is treated as information, not instructions; a tool's own guidance on which tool to call next is followed. If the model provider cuts an answer off part-way, that turn is retried once.

The agent pays only at test stores; elsewhere it stops before payment.

The run page

The chat on the left shows only what the buyer would see: the messages, product cards, the cart and the checkout. Click a card to find its call in the trace. The pane on the right holds the detail, in four tabs:

  • Trace: every call and answer, kept whole, with secrets shown as prefixes. Its header counts steps, store time, model time, tokens, cost and errors. A failed line says whose fault it was; if it was ours, you can report it from the line.
  • Discovery and negotiation: how the agent found the store's UCP profile, what the two agreed to use (UCP version, active capabilities, extensions), and what passed between them during the run.
  • Timeline: the calls laid out by stage, by tool, or by tool within each stage.
  • Info: how the run ended and why, the task, the setup, the UCP profile, the tools used, what it was recorded with, errors by whose fault, when it started, duration, cost and tokens.

A website run adds a third pane, The agent's browser, with a screenshot per step. An Embedded run uses the same third pane for the store's own checkout page. Hide the right-hand pane to give the chat the width.

While the agent works, the bar under the header says Running. When it asks the buyer something, the bar says Your turn: reply in the box under the chat, and the same run carries on. A website run is one task with no replies; start a new run to ask something else. When the run is done, the bar becomes the replay bar; see History and replays.

How it ends

Every run ends as Searched only, Built a cart, Reached checkout, Tried to place the order, Order placed, or Failed, and any failed call is put down to the store, the agent, or ours. See Understanding results.

Placing orders

UCP's Complete Checkout places the order. Signed in, the agent sends it when your task asks for an order. Signed out, the agent gets the checkout ready and stops: the call is held back, shown in the Trace as held back, and the run ends at "Reached checkout".

WhereSigned inSigned out
Our test storesPlaces the order (test card)Places the order (test card)
Any other storePlaces the orderStops before the order

An order placed at a store that isn't one of our test stores is a real order to that store, paid with what its checkout offers. Many stores hand the buyer to their own page for payment, and the run then ends at a buyer handoff. A run from an API key counts as signed in, and so does a personal agent.

An agent that completes purchases for real buyers should carry the buyer's authorization; UCP's AP2 mandates extension is the spec's route for that, and Playground doesn't send mandates yet.

The store in the header

The header shows the store in scope and its environment (Production, Pre-production or Test store). Open it to switch stores, to see the buyer account linked there (UCP identity linking), and to see what the store is holding for the buyer: carts, checkouts and booking holds, as the store last reported them. To test your own pre-production endpoints, add them in Settings › Stores & endpoints.

Tip

Keep tasks specific. "Find me Nike Air Max size 10 in white" gives the agent clear criteria to search and filter on. "Show me shoes" leads to vague choices and runs that end earlier.

Note

If a run stalls or ends earlier than you expected, open its Trace. Common causes are a store returning an unexpected response shape, or the agent struggling to pick a variant. See Troubleshooting.

Something wrong on this page?