wso2/labs-agentic-engineer/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.