agent-building

# Building an agent An `ai-agent` component is one contract and one implementation of it: - **`specs/design/components/<name>/agent.afm.md`** — the agent itself. Its markdown body becomes the system prompt verbatim; its allow-list becomes the only operations the model can reach. - **A TypeScript service** running a Vercel AI SDK loop, which implements that document the way a service implements its `openapi.yaml`. Both halves are here on purpose. They used to be two skills, and the facts below — which each half states from its own side — drifted apart in ways that only showed up in a deployed agent. ## Read one of these next **Writing or editing `agent.afm.md`** → read `references/designing.md`, and stop. **Implementing the component** → read `references/building.md`, and stop. It carries the code to copy, and an agent built without it will be missing its conversation store or its identity gate. The rest of this page is what BOTH halves must agree on. Read it either way. ## The contract **`POST /chat`** — `{ conversationId?, message }` in, `{ conversationId, text, toolCalls }` out. History lives in the agent's own store and never crosses the wire. `GET /healthz` is the other route; there are no more. **`conversationId` is the caller's only piece of state.** ABSENT means "new conversation": create one and return its id. An id that is present but does not resolve **for this user** is **404, never a new conversation** — adopting a caller-chosen id lets one caller pick another's and write under it. **Memory is server-held.** The agent keeps the conversation; the caller holds an identifier. `x-aep.memory.type: "server"` is the default and what the store implements. `client` remains valid only where the caller genuinely owns the transcript — rare, and the design says why. **Identity is the gateway's, not the caller's.** Every turn arrives with a gateway-injected `x-user-id`. The agent 401s without it, and scopes every conversation row by it. The agent never derives identity from the request body or from the conversation itself. **The allow-list is the security boundary.** `x-aep.tools.openapi[].allow` names operations by `operationId` from the dependency's committed contract. An operation left out is never generated as a tool, so no phrasing can reach it. A prohibition written in the prompt is a hint; omission from `allow` is a guarantee. This is why neither half may "helpfully" add an operation the design did not list. **Nothing is a literal.** Addresses and credentials are `${env:NAME}`, injected from the component's dependencies at deploy. `specs/` is committed to git. `MODEL_*` needs no dependency — an `ai-agent` gets model access from its component type, either on the organisation's own key or through the platform's AI gateway. Which one is not the agent's business: it reads the same `MODEL_*` variables either way, whatever host or API format the organisation's connection names. See `references/building.md`, "Model access", for the switch on the format and the one header override that differs. ## Where each fact is enforced A design that declares something the implementation ignores is not a design. | The contract says | The design declares | The implementation does | |---|---|---| | one turn per request | `interfaces: webchat`, path `/chat` | serves `POST /chat`, that shape | | the agent owns history | `x-aep.memory.type: "server"` | the conversation store, scoped by user | | only these operations | `allow: [...]` | generates a tool per entry, and no others | | the caller is whoever signed in | `x-aep.identity.mode: "on-behalf-of"` | gates on `x-user-id`, forwards the caller's token | | the agent takes files | `x-aep.attachments: { types, maxFiles, maxFileSizeMB }` | `/chat` accepts base64 `attachments` within them; 413 past 24 MiB; files ride one turn; 422 when the model can't read them | | a Product Decision asks for a guardrail | `x-aep.guardrails: [{ policy, params, why }]` | the AI gateway applies it to the agent's model traffic at deploy; each outcome is on the deployment | | behaviour is graded before the PR | `specs/validation/agent-scenarios.json`, from the requirements alone | runs the scenarios, may revise only the prompt body, reports the score — **unless evaluation is disabled** (`AEP_AGENT_EVAL` unset or not `on`), in which case it is skipped and the PR says so. See `references/building.md`, "Evaluate before you open the PR" | | no secrets in git | `${env:NAME}` | reads them from config, never hardcodes |