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

# iCommerce Agent

> The pattern for an agent that operates the commerce engine — gather, propose, act, record.

# iCommerce Agent

An iCommerce agent combines three things: the [embedded
engine](/stateset-icommerce/stateset-icommerce-embedded) for state, the
[MCP server](/stateset-icommerce/stateset-icommerce-mcp) for tools, and the
[CLI safety model](/stateset-icommerce/stateset-icommerce-cli-safety) so writes stay explicit.

The result is an agent that resolves work rather than describing it — and leaves a record of what
it did.

## The loop

```
gather context ──▶ propose an action ──▶ execute with explicit intent ──▶ record
      │                    │                        │
  reads only          no side effects          --apply / write tool
```

**1. Gather.** Orders, inventory, customer history — all reads, no side effects.

```js theme={null}
const order   = await commerce.orders.get(orderId);
const rmas    = await commerce.returns.listForOrder(orderId);
const stock   = await commerce.inventory.getStock(sku);
```

**2. Propose.** Decide the action and state it, before doing it. For consequential actions this is
where the [decision gate](/next-temporal/policy-engine) belongs — the agent proposes, the policy
engine authorises.

**3. Execute** with explicit write intent.

```js theme={null}
await commerce.returns.approve(rma.id);
await commerce.returns.markReceived(rma.id);
```

**4. Record.** The outcome, and what authorised it.

## What an agent can do

| Area       | Operations                                     |
| ---------- | ---------------------------------------------- |
| Orders     | Look up, fulfil, ship, cancel, refund          |
| Inventory  | Check stock, reserve, adjust                   |
| Returns    | Full RMA workflow — approve, receive, complete |
| Warranties | Claims and actions                             |

The MCP surface exposes 719 tools across 63 domains, of which **287 write, 47 admin, and 21
delete**.

<Warning>
  Scope the agent to the domains it needs. A support agent resolving refunds does not need the
  manufacturing or general-ledger tools, and giving it the full catalogue means a
  mis-planned action can reach places you never intended.
</Warning>

## Making it safe

Four layers, from coarse to fine:

| Layer                                             | What it stops                                                       |
| ------------------------------------------------- | ------------------------------------------------------------------- |
| **Read-only default**                             | An exploring agent cannot mutate as a side effect                   |
| **Explicit `--apply` / write tools**              | A write is a decision, not an inference                             |
| **Tool scoping**                                  | The agent cannot reach domains outside its job                      |
| **[Decision gate](/next-temporal/policy-engine)** | An unauthorised or ungrounded action escalates instead of executing |

<Note>
  These compose rather than substitute. `--apply` grants permission to *attempt* a write; the engine's
  idempotency keys, terminal-state guards, and High-Value Action threshold still apply underneath.
</Note>

## Running it sandboxed

For untrusted or long-running work, run the agent inside a
[sandbox](/stateset-icommerce/stateset-icommerce-agent-sandbox) — isolated execution with a bounded
timeout and its own resource profile.

## Deterministic beats fluent

Use `stateset-direct` rather than the natural-language binary for anything an agent runs
unattended. Interpretation is useful at a terminal and a liability in a loop: the same instruction
can resolve differently as the model changes.

## Related

* [Agent Sandbox](/stateset-icommerce/stateset-icommerce-agent-sandbox)
* [CLI Safety Model](/stateset-icommerce/stateset-icommerce-cli-safety)
* [Scenarios](/stateset-icommerce/stateset-icommerce-scenarios)
* [MCP Server](/stateset-icommerce/stateset-icommerce-mcp)