> ## Documentation Index
> Fetch the complete documentation index at: https://agentmall.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

> [!NOTE]
>
> Session tools need a test key. In keyless [test mode](https://agentmall.mintlify.site/connect-your-agent.md) 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.

```json theme={null}
{
  "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.

```json theme={null}
{
  "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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.