> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stella-commerce.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent Capability Token

> Scoped, budget-capped, audit-logged tokens an AI agent uses to act on a customer's behalf.

An **Agent Capability Token** (`agt_…`) lets an AI agent shop on a
specific customer's behalf — within boundaries the customer chose. It
is the differentiator slice of Stella: every merchant gets agent
traffic for free because `/api/agent/*` is just a different token type
on the same backend.

## What makes an agent token different

| Aspect                 | Storefront token      | Customer token             | **Agent token**                                              |
| ---------------------- | --------------------- | -------------------------- | ------------------------------------------------------------ |
| Identifies             | A merchant            | A logged-in customer       | An agent + a customer + a budget                             |
| Lifetime               | Indefinite            | \~24h, renewable           | Bounded by `expires_at`                                      |
| Spending limit         | None (merchant trust) | None (customer's own card) | **Hard `budget_cents` cap**                                  |
| Per-call audit         | Mutations only        | Mutations only             | **Every call, every endpoint**                               |
| Auto-completes payment | n/a                   | If buyer confirms          | **Never** — always returns a checkout URL the human must tap |

## Consent flow (RFC 8628 Device Authorization)

Modeled on OAuth's device flow because LLMs can't open embedded
browsers.

```mermaid theme={null}
sequenceDiagram
    participant Agent
    participant Stella
    participant Customer

    Agent->>Stella: POST /api/agent/consent/request<br/>(scopes, budget, expiry, agent_name)
    Stella-->>Agent: { user_code, verification_uri_complete,<br/>device_code, expires_in, interval }

    Agent->>Customer: "Visit {verification_uri_complete}<br/>to approve me."
    Customer->>Stella: GET /agent-consent (loads SPA)
    Customer->>Stella: POST /customer/me/agent-consent/{user_code}/approve

    loop Polling (interval seconds)
        Agent->>Stella: POST /api/agent/consent/poll<br/>(device_code)
        Stella-->>Agent: 400 {"error": "authorization_pending"}
    end

    Customer->>Stella: Approves
    Agent->>Stella: POST /api/agent/consent/poll
    Stella-->>Agent: 200 {"access_token": "agt_...",<br/>"expires_in": ...}
```

The customer never sees the agent's screen, and the agent never sees
the customer's password. Tokens never travel through the agent's
process before the customer has explicitly approved.

## What an agent can do

`/api/agent/*` is a separate API surface optimized for LLM tool-use:

| Endpoint                          | Effect                                                                                                     |
| --------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| `GET /agent/catalog/search`       | LLM-shape product search                                                                                   |
| `POST /agent/intent/find`         | NL query → ranked candidates                                                                               |
| `POST /agent/intent/find-and-add` | One-shot: find + create cart + add                                                                         |
| `POST /agent/intent/find-and-buy` | One-shot: find + cart + checkout. **Returns `checkout_url` for the human to tap.** Stella never auto-pays. |
| `GET /agent/customer/me`          | Customer profile (capability-token-aware)                                                                  |
| `GET /agent/audit/me`             | Agent's own action history                                                                                 |

## Budget enforcement

Every mutation that allocates spend (`find-and-buy`, `find-and-add` if
followed by checkout completion) checks:

```
if budget_used_cents + line_total_cents > budget_cents:
    return 402 PAYMENT_REQUIRED { "error": "budget_exceeded" }
```

`budget_used_cents` is incremented in the same transaction that
finalizes the order (`CheckoutFinalizer.consume_budget`), so partial
failures can't double-spend.

## Per-customer agent cap

A customer can have at most **10 active agent tokens at any time**. The
11th `consent/poll` returns:

```http theme={null}
HTTP/1.1 400 Bad Request
Content-Type: application/json

{ "error": "agent_cap_exceeded" }
```

The consent code stays `approved` — the customer can revoke an
existing token and the next poll will succeed without re-issuing.

## Audit trail

Every agent call writes to `audit_events` with:

* `actor_type = "agent"`
* `actor_id = <agent_token_id>`
* `action = <endpoint>`
* `payload_hash`
* IP, UA, correlation ID

Customers see their full agent history at:

```
GET /api/storefront/customer/me/agents/{token_id}/audit
```

Merchants see aggregate per-agent activity in the dashboard's **My
agents** panel.

## Revocation

Three paths, all instant:

* Customer revokes from the dashboard's customer-side **My agents**
  panel.
* Customer revokes via API: `DELETE /api/storefront/customer/me/agents/{id}`.
* Merchant revokes from the dashboard's merchant-side panel
  (compliance / abuse cases).

The next agent call fails with `401`.

## Try it from the CLI

The reference smoke harness lives at `examples/agent-cli/` in the
[agenticom repo](https://github.com/Zunkireelabs/agenticom). Seven
subcommands cover the full flow:

```bash theme={null}
agent-cli mint --scopes catalog:read,cart:write --budget 5000 --expires-in 1h
agent-cli poll
agent-cli search "black M tee"
agent-cli buy --product-id ...
agent-cli audit
agent-cli me
agent-cli revoke
```