Free-form procedures

Overview

A free-form procedure describes one task in plain, natural language. The agent interprets the instructions and adapts the wording and order to the situation. A free-form procedure can call tools (including system tools like ending a call), look up knowledge base documents, and chain to other procedures.

When to use a free-form procedure

Use a free-form procedure when the agent can adapt wording and order to fit the situation, and you want to author it quickly in plain language. For how it compares to structured procedures, workflows, and the system prompt, see When to use procedures.

Anatomy of a procedure

Here is a refund procedure in the editor:

A procedure has two main parts: a trigger and content. Both can contain inline references to other resources, shown in the screenshot above as tags with wrench icons. Each procedure also has a name shown in the dashboard.

Name

A short label that identifies the procedure in the dashboard. The name is never sent to the LLM, so it does not affect agent behavior.

Trigger

A description of when the agent should use this procedure, for example When the user asks to refund an order.

Leave the trigger empty only when creating a sub-procedure.

Content

The body of the procedure, written in markdown. Content describes what the agent should do: ask a question, look up an order, call a tool, or end the call. It can be a numbered sequence of steps to follow, or general guidance for the situation. Each step or guideline can be a single sentence (Ask the user for their order ID) or a short paragraph that explains what to do and why.

Use numbered steps for sequential actions and bullet points for requirements or sub-items within a step.

Inline references

Procedures can reference different kinds of resources inline:

• Tools (e.g. look up an order, charge a card, end the call, transfer to a human)
• Knowledge base documents
• Other procedures

Use inline references whenever a step needs the agent to use a tool, knowledge base document, or another procedure. References auto-attach the resource to the procedure so the agent can use it. Plain prose mentions (like use the calculator tool here) also work, but only if the resource is already attached to the agent.

Insert a reference by typing / in the trigger or content and choosing the resource from the slash menu. References appear as clickable tags in the editor. Click a tag to open the underlying resource and confirm its configuration.

When writing free-form content through the API, insert references with the following syntax:

[tool id="tool_abc123"]
[kb id="kb_abc123"]
[procedure id="agtprc_abc123"]
[system_tool id="end_call"]
{{customer_id}}

An inline procedure reference must use a procedure from the same agent. See Limitations for agent scope and duplication behavior.

A reference in the trigger lets the procedure fire based on a resource’s output, for example When get_user returns tier ‘gold’. A reference in content tells the agent to invoke or consult the resource at that step.

If a referenced resource is deleted later, or your account loses access to it, the tag shows as broken. The Errors badge at the top of the editor lists these references: invalid if the resource no longer exists, or unavailable if it exists but your account does not have access. Open the badge to see which step is affected and fix or remove the reference.

Sub-procedures

A sub-procedure has an empty trigger. The agent can run it only from another procedure that references it.

Use sub-procedures to share steps within one agent and reduce the number of procedures available at once. Give the entry procedure a trigger, reference related sub-procedures from its content, and leave their triggers empty.

An escalation sub-procedure can hold the steps for handing the conversation to a human. Reference it from the refund and cancellation procedures and leave its trigger empty. The agent can escalate as a step of either procedure, but outside them the sub-procedure stays unavailable.

Importing from a document

You can bootstrap from an existing standard operating procedure (SOP). Choose From SOP in the procedure list + menu, then upload a file.

Supported formats: PDF, DOCX, TXT, MD, HTML, EPUB. Files must be 20 MB or smaller.

The importer analyzes the document, identifies up to 10 distinct procedures, and creates a draft for each one with a generated name, trigger, and content. Open each draft to refine it. If your document contains more than 10 SOPs, split it into smaller files before uploading.

Manage a free-form procedure

Best practices

Writing procedures well means writing two parts well: a trigger that runs the procedure when it should, and content the agent can follow.

Iterating on a procedure

We recommend starting small and using agent tests to check each change before you make the next one.

When a test or a live conversation fails, look for the class of mistake behind it. If the agent said something wrong, adding Don’t say that fixes one conversation. Search past conversations for similar failures and write one instruction that covers all of them. The cause can also be in the knowledge base or the agent configuration. Architect can do this search: open the failed conversation, select Architect, and ask it to find similar failures and propose a fix. Architect can also turn the conversation into a test.

Writing triggers

Writing content

Composing procedures