Better Data

Guides

Build an agent

Edit this page

Build an agent (C11 / C12)

Agent Starter is the canonical developer accelerator for composing a Commerce Agent in code: define a goal, reach the registry, execute through Commerce Gateway, apply a Loop Engine–style guard, then return a recorded outcome.

C12 — Say it this way: agents use Registry to discover, Gateway to act, and Loop Engine to govern. Do not describe agents as an autonomous AI platform, agent product, or a system separate from the gateway.

What you get

| Step | Surface | In this starter | | ---- | ------- | ---------------- | | 1 | Goal | goal.query in agent.config.json | | 2 | Query Registry | HTTP ping to registry.endpointUrl (swap for Registry MCP JSON-RPC in production) | | 3 | Execute via Gateway | POST to gateway.baseUrl + queryPath with bearer token (same contract as Commerce Demo / demo-gateway) | | 4 | Loop Engine guard | Pure TypeScript policy + confidence floor (illustrative; replace with real Loop Engine APIs) | | 5 | Return result | JSON on stdout |

The same composition is described in Commerce Agent pattern (C9) and shown interactively in Commerce Demo (governed workflow).

Monorepo package

  • Path: packages/agent-starter
  • Copy agent.config.example.json → agent.config.json, set GATEWAY_API_TOKEN (or the env name in config), then:
1cd packages/agent-starter
2pnpm install
3pnpm dev -- --config=agent.config.json

Full README lives next to the code.

Configuration (minimal)

  • Registry — registry.endpointUrl + mode: "httpPing" (GET reachability). Production agents should call Registry MCP tools (@shop, gateway resolution).
  • Gateway — gateway.baseUrl, gateway.bearerTokenEnv, optional queryPath (default /api/gateway/query).
  • Loop guard — loopGuard.policy, minConfidence, blockWrites (aligned with the governed demo rail, not a live Loop Engine deployment).