Writing Procedures

Authoring Rules

• A procedure has a name, a trigger, and content. The agent uses the trigger for routing and reads the content when the procedure starts.
• Use free_form for natural-language guidance that the agent can adapt. Only free-form procedures can reference knowledge base documents.
• Use deterministic for ordered, typed steps that must run consistently, such as identity verification or payment collection.
• Preserve the procedure type during routine updates unless the user explicitly requests a conversion.
• Write concrete, non-overlapping triggers from the user’s perspective. Cover likely phrasing: When the user asks to refund, return, or get money back for an order routes better than When the user requests a refund.
• An empty trigger marks a sub-procedure that runs only when another procedure references it. Omit trigger entirely to derive one from the content.
• Content is capped at 50,000 characters for both types.
• Keep each procedure focused on one task. Put tone and refusal policy in the system prompt.
• Extract steps shared across procedures into a separate procedure.

Free-Form Content

Write content as markdown. Use numbered steps for sequences and bullets for requirements within a step. Use the imperative. Explain a step’s rationale only when it helps the agent handle cases the procedure does not enumerate.

Reference a tool, knowledge base document, or another procedure inline. The id binds the resource; name provides a readable label.

An inline reference attaches the resource automatically. Naming a tool in prose works only when it is already attached to the agent, so prefer the markup.

A trigger can reference a resource’s output, for example When get_user returns tier 'gold'.

Structured Content

Set content to a serialized JSON object containing a trigger and a non-empty steps array. Each step is an object discriminated by type. The step type defines its behavior, so its instruction rarely needs to restate that behavior.

Each entry in branches pairs a condition with its own steps. A condition is either an LLM condition such as {"type": "llm", "condition": "the caller has no order ID"} or an expression over dynamic variables such as {"type": "expression", "expression": ...}.

Use the structured procedures documentation for current step types, fields, and valid combinations. To validate against a live agent, save the draft and compile it. Fix every reported error before publishing; Using the Procedure API describes the loop.

Building the Content String

Serialize the object before assigning it to content; do not hand-escape quotes.

Python

JavaScript

CLI