The four parts
Goal
What the agent has to achieve. It decides which toolkits switch on, so it is the one part you cannot change casually.
Prompt sections
What the business contributes: who it is, what it does not do, when it hands over, its example conversations.
Channels
Where it answers. The mechanics of each medium come from the platform, not from your text.
Tools
HTTPS webhooks the agent can call mid-conversation. They belong to the company; an agent uses one by holding its id.
The catalogue is the source of truth
The valid values ofsection, goal.type and channels come from GET /v1/agents/prompt-types, not from a list published in this documentation.
That is deliberate. A section added to the platform appears in the catalogue immediately, and a list you copied into your code goes stale the day it happens. Read the catalogue at build time or at run time; do not hardcode it.
Each section row also carries a tip — the platform’s own guidance on what belongs in that section. If you generate section text with a model, that tip is the instruction to give it.
The read path
Two calls, and the second one already includes the text:Writing sections
One section at a time withPUT /v1/agents/{id}/prompts/{section}, which leaves the rest of the agent alone. Sending prompts to the update endpoint instead replaces all of them — useful when you own the whole prompt, dangerous when you do not.
- Send the whole section. The text is replaced, not appended to.
- Serialise your writes per agent. A section is written by reading the agent, replacing that entry and saving it back, so two simultaneous writes to different sections of the same agent lose one.
Sections have history
Every save that changes the text leaves a version behind. Saving identical text does not, so the history records changes rather than calls.- List the versions of a section — newest first; the first one is what the agent is reading.
- Read one version to diff it against the current text.
- Restore one — which writes a new version copying the old one and records
restored_from, so a rollback is itself reversible.
The funnel
An agent moves tickets between the stages of a CRM pipeline — but it never creates stages by itself: itsstages field is a whitelist of ones that already exist, and a stage that is not in the CRM enables nothing.
That is why creating an agent accepts stages as names, in order:
stages out and no pipeline is created and the agent does not move tickets — which is the right answer for one that only informs.
Testing an agent
POST /v1/agents/{id}/query writes to the agent as if you were a customer and returns what it answers.
It always runs in test mode, and that is not configurable. The tools that write — booking, charging, opening a ticket — are simulated, and the response tells you which ones were called and which were simulated. A public endpoint that ran them for real would give any PAT the ability to create appointments and charges on behalf of the business, without the token’s scopes having any say: what a tool does is governed by the agent, not by the token.
Real customer conversations go through the channels, not through this.
Tools
A tool is an HTTPS webhook with a name, a description and typed parameters. The description is what the model reads to decide when to call it, so it is configuration that matters, not a label. Tools live at the company level: list them once, and give an agent the ids it should be allowed to use. The URL rules and the masking of secret values are in webhook security.Migrating from the block API
The previous version of this surface modelled a prompt as an ordered list of blocks living in a project catalogue, each with its own versions. That model is gone.
Three differences that change how you integrate, not just what you call:
- A section is not shared. Blocks lived in a catalogue and several agents could reference the same one; a section belongs to its agent. Reuse across agents is now your templating, not a shared object.
- There is no attach and detach. Writing a section creates it; deleting it removes it.
- Content and metadata are no longer separate calls. Reading the agent gives you the text.
assistants surface any more. The /v1/assistants alias is gone, responses carry agent and nothing else, and the not-found code is AGENT_NOT_FOUND. agents-list, agents-get, agents-create, agents-update and agents-delete keep their URLs even though their shape changed.