Sessions

How AgentMall records one agent’s shopping run, from first search to order.

A session records one agent shopping for one shopper at one merchant. It holds every tool call the agent made, and ends with an outcome, whether the agent bought something or left after a few searches.

Create the session before the agent starts shopping with create_session, passing a shopper_id and a merchant_id. You pass its ID again when you open checkout with create_checkout, which ties the order back to the run that produced it.

Session tools need a test key. In keyless test mode they return needs_test_key.

Outcomes

Every session has one outcome. A new session starts as browsing.

Outcome	Meaning
browsing	The agent searched or viewed products but never added anything to a cart.
carted	The agent ended the run after saving a cart for later.
checked-out	The cart was submitted and an order was created.
abandoned	Checkout started, but approval or execution did not complete.
expired	The session reached its inactivity limit before checkout started.

A session that ends without an order is still recorded. A run where the agent searches and leaves tells you as much as one that buys.

The session record

get_session returns the session with its cart and order, if any, plus how long it ran and how many tool calls it made.

{
  "id": "ses_01K8V6R9MH7ZP4W2X3C5TQ8NFA",
  "shopperId": "cus_maya_chen",
  "merchantId": "mrc_walmart",
  "outcome": "checked-out",
  "cartId": "crt_01K8V6S2...",
  "orderId": "ord_01K8V6T7...",
  "startedAt": "2026-10-24T09:00:00Z",
  "endedAt": "2026-10-24T09:06:40Z",
  "durationMs": 400000,
  "toolCallCount": 9
}

endedAt and durationMs are null while the session is still open.

Events

Every tool call the agent makes in a session is stored as an event. Events are append-only: they are never edited or deleted. get_session_events returns them in order.

{
  "id": "evt_01K8V7N5QM3X2R6T4C9Z0AFHGB",
  "sessionId": "ses_01K8V6R9MH7ZP4W2X3C5TQ8NFA",
  "tool": "search_catalog",
  "durationMs": 1200,
  "resultSummary": "AA batteries → 10 products",
  "failed": false,
  "timestamp": "2026-10-24T09:00:00Z"
}

Each event has the tool name, how long the call took, a one-line summary of the result, whether it failed, and when it happened.

Debugging with sessions

Use a session’s events to see what an agent did, step by step, and where it stopped. Use list_sessions with outcome or shopper_id to find patterns across runs. For example, many abandoned sessions can point to friction at approval or checkout.

Session events record what the agent did. Order events, from get_order_events, record what happened to the order afterwards.