# How to write an agent

Read this page once you know [which pieces a job needs](/how-it-fits). That
page says what goes where; this one says how the words in a node are written
once the pieces are chosen. It is one text, held to one wording wherever it
appears: the platform's own Architect reads it in the phase where it writes
your agent, the API's description and the MCP server's instructions carry it
for any outside model, and this page carries it for you. Every rule below is
stated with its reason in the same sentence, so that it can be applied to the
case the rule did not foresee.

## The account

An agent is a graph of nodes because one prompt that covers several situations, or more than a handful of tools, drifts: the model answers the wrong situation with the right words. One situation per node. A node holds only the tools that situation needs, so the model chooses among three, not thirty. A conversation that is one situation is one node; a conversation that greets, then books, then confirms is three.

A node's instructions are short and sectioned, in this order: what this step is for, in one line; what the agent says or asks here, one question per turn; where its facts come from; which tools it calls and when, by the tool's exact name; how it leaves. Then one or two example exchanges, two lines each. Nothing else. A node that needs more than this is two situations and should be two nodes.

A business fact is never written into a node. Opening hours, prices, addresses, policies and names of products live in a collection or a document and are read by a tool, so the text says "look up today's hours" and never the hours themselves. A fact written into a prompt is right on the day it is written and wrong thereafter, with nobody told; a fact in a collection is edited once, where it lives, and every node reads the new value.

Instructions say what to do, not what to avoid. "Answer in one sentence" works; a list of twelve things never to say puts those twelve things in front of the model on every turn. When something must be refused, name the refusal and what to offer instead: "If asked for legal advice, say that a lawyer will answer that, and offer to book the consultation."

On a voice line the agent speaks in one or two sentences, asks one thing at a time, says numbers, dates and phone numbers the way a person says them aloud, and repeats back only the detail that matters before acting on it: a name, an address, an amount, anything sent on the caller's behalf. Before a tool that may take a while it says one line so the line is not silent. This is one fixed block written the same way into every node of a voice agent, not something to compose per agent.

Every agent has a node for when it cannot help: after the caller has not been understood twice, or a tool has failed twice, or the caller asks for a person, the agent hands over or takes a message, and says which. An agent without this node keeps a caller in a loop, which is the one thing worse than an agent that says it cannot help.

Edges leave a node under a condition written the way the model reads the conversation: "the caller wants to book" and "the caller is asking about prices" are two edges; "next" is not an edge. Two edges out of the same node never describe the same case.

When one node changes, the greeting, the edges into it and out of it, and the nodes beside it are read again against the change, so the agent does not promise in its greeting what a node no longer does.

## Reading it against the pieces

The first two paragraphs are the shape of the graph and of a node, which
[How it fits together](/how-it-fits) describes from the outside. The third is
the ladder's first two rungs stated where the writing happens: a fact belongs
in custom data or a document and reaches the node through a tool, never
through the text. The node for when the agent cannot help uses the built-in
call-control tools (transfer, hang up) and the platform's own messaging tools,
which are the same tools a person attaches by hand. The voice block is the one
part of an agent that is written the same way every time; nothing on this page
is a template to fill in beyond it.

A draft written this way can be proved before it is published: open a
conversation against the draft over the text channel, play the caller, and
read the records the agent wrote rather than the transcript. The Architect
does exactly that once it has built a whole agent, or whenever it is asked,
and the operations it uses are the public ones listed in the reference.