Skip to main content
Agents are the core AI units in Agent Platform. An agent reasons toward a goal, calls tools, and composes replies in the persona you define. This guide shows how to create an agent in Studio and write its ABL definition. The same agent serves chat and voice, in one or more languages, and you build it the same way for each. A voice agent adds a voice channel and a few voice settings. A multilingual agent adds language settings.
Before you write instructions, read Agent design guidelines.

How an agent is built

You build every agent in the same order. The channel comes last.

Reasoning and FLOW

Every agent reasons by default. Add a FLOW section when parts of the conversation need fixed, deterministic steps. A FLOW section doesn’t create a different agent type. The agent still reasons and calls tools outside the flow steps.

Chat, voice, and language

Most of an agent is the same on every channel and in every language. Only a few parts change. Build the agent with this guide. Then complete Voice agents for voice, and Multi-language support for more than one language. For design advice, see Design voice conversations and Build multilingual agents.

Create an agent in Studio

You need developer permissions on the project.
  1. Open your project and select Agents in the sidebar. The page lists each agent with its name, flow indicator, deployment status, and last change.
Agents page
  1. Select Create Agent and complete the fields.
  1. Select Create Agent. The agent editor opens.

Choose an editor

Configure the agent in either editor. They stay in sync.
  • Visual Editor: a form with sections for identity, tools, memory, flow, and more.
  • ABL Editor: a code editor for the agent’s ABL definition. To open it, select the < > ABL icon in the agent’s top bar.
ABL Editor The ABL Editor has syntax highlighting, inline error markers, and slash commands. Type / to insert a snippet, such as a tool, a gather field, or a handoff.
Select Save to save and validate the definition. Studio flags syntax issues inline. The status bar shows No issues when the definition is valid.Select Compile to run a full structural check without saving.
The Outline panel shows the agent’s structure as a tree, such as PERSONA, MEMORY, HANDOFFS, and steps. Use Filter symbols to jump to a section.ABL Editor outline panel
The Diagnostics panel at the bottom lists validation issues by type.ABL Editor diagnostics panel
Select Insert Tool Signature to search the project’s tools and insert a signature into the TOOLS block at the cursor.Insert Tool Signature dialog

Define identity and persona

Identity and persona set how the agent communicates: its tone, expertise, and boundaries. Agent identity, goals, and persona Define the identity at the top of the agent definition.
Keep GOAL and PERSONA short and specific. Vague text leads to inconsistent behavior.

Configure execution

The EXECUTION block sets the model, token limits, reasoning depth, and timeouts. Model settings apply in this order, from lowest to highest precedence: the model card, the project model override, agent runtime overrides, and EXECUTION. If the selected model doesn’t support a setting, the platform leaves it out of the request. For example, it doesn’t send sampling parameters to reasoning models. Agent execution details
Set max_reasoning_iterations to stop runaway tool loops. Raise it only when a trace shows a turn that needs more rounds.

Add tools

Tools let an agent call APIs, retrieve data, or trigger actions. Create the tool at the project level, then attach it to the agent in Studio or in the TOOLS block.
The model reads each tool’s description to choose a tool, so write descriptions that are clear and accurate. When the agent must use tools in a fixed order, list the steps in INSTRUCTIONS.
For tool types and settings, see Tools.

Collect and remember data

Gather: define the fields the agent collects from users, with types and required flags. GATHER works in the agent and in flow steps. See Gather data from users. Memory: configure session variables for one conversation, persistent values across sessions, and remember and recall triggers that store and inject context.
See Memory and state.

Add a FLOW section

Add a FLOW section for fixed, step-by-step control, such as bookings, identity checks, or data collection. Each step can respond, add model context, call a tool, and name the next step. In Studio, configure each step with these fields:
  • Step name: a name that says what the step does.
  • Execution mode: Deterministic steps follow the defined sequence without a model decision.
  • Respond: what the agent says at this step.
  • Model context: what the model remembers for later turns. It doesn’t change the reply.
  • Call: the tool to call.
  • Then: the next step.
Sample agent:
Steps with REASONING: false follow the defined path. THEN names the next step. ON_INPUT branches on the user’s reply. For entry points, tool-call branching, SET, and MAX_ATTEMPTS, see the FLOW reference.

Mix reasoning and deterministic steps

One flow can combine deterministic steps (REASONING: false) with reasoning steps (REASONING: true). Use deterministic steps for data collection and confirmations. Use reasoning steps for open-ended research or analysis.
Key properties for reasoning steps:

Customize responses

Every RESPOND supports variables, templates, rich content, interactive actions, and channel-specific formats. The platform renders the right format for the active channel.
On voice, the runtime speaks the VOICE: block if there is one. Otherwise it speaks the RESPOND: text with markdown removed. Rich content isn’t used. Write replies that work as plain speech. See Channel selection.

RESPOND

Use RESPOND for text replies. Insert values from variables, memory, and tool results with {{ }}.
For multi-line text, use |:
For a reusable or channel-specific reply, reference a template:

Multiple responses in one turn

An agent can send several messages in one turn, in any mix of text and templates. Each message streams to the client separately, in order, and isn’t merged with the next one. This flow sends a template, then plain text, then another template:
The client receives three messages in order: first_template, the plain text, and second_template.

Templates

Use the TEMPLATES block to define named replies once and reuse them with TEMPLATE(name) in RESPOND, ON_START, and COMPLETE. Templates support:
  • Variable interpolation using {{ }} to insert dynamic values.
  • Conditional blocks and loops for rendering dynamic content.
  • Multiple channel-specific variants, allowing the same response to be rendered differently on web, voice, Slack, WhatsApp, Teams, and other supported channels.
  • Interactive actions for building rich, interactive experiences.
The platform automatically selects the appropriate template variant for the active channel. DEFAULT is required and serves as the fallback when no channel-specific variant is available. See Templates.

Interactive responses

Add interactive elements to any reply with ACTIONS:
  • Buttons for set choices.
  • Select menus for choosing from a list.
  • Input fields for free text.
  • Forms that group several inputs with a submit action.
See Interactive actions.

Carousels

A carousel shows a row of cards that users scroll, each with a title, subtitle, image, and buttons. Use it for several options, such as hotels, products, or flights. Define it in RICH_CONTENT with the CAROUSEL key.
For all card properties, see Carousels.

System messages

Use MESSAGES to set the text of system-generated replies so they match the agent’s tone.

Lifecycle

Define what happens when a session starts, when an error occurs, and when the task is complete.

On start

ON_START runs once when the agent starts a session, either as the session entry point or after a handoff. Use it for a greeting, tool calls, and variable setup. In Studio, configure these fields: Interactive Actions Types In ABL, add an ON_START block:
You can call a tool and set variables before the greeting, for example to check for a returning user:
On voice, the greeting is the first thing the caller hears. Keep it to one short sentence. On a pipeline voice channel, a channel Welcome Message replaces the ON_START greeting, and Allow caller to interrupt the welcome decides whether callers can talk over it. See Design channel-specific welcome experiences.
Directives you can use in ON_START:

Error handling

Define how the agent recovers from tool failures, timeouts, and unexpected input, so conversations don’t dead-end. In Studio, add a handler on the Error Handling page. For example, when a tool call fails, the agent can say “An error occurred. Please try again.” and then retry the step, continue, or hand off to another agent.

Completion

Completion conditions decide when the task is done. Each condition is an expression on the conversation state, such as whether all required information is collected. When it’s true, the agent marks the task complete and can send a final message. In Studio, configure each condition:
  • When expression: the condition to meet.
  • Response message: an optional message to the customer.
  • Later model context: what the model knows about that message in later turns.
Select + Add Condition to add more.

Coordinate with other agents

Configure how the agent hands off work to other agents or to people.
  • Handoffs: rules that pass the conversation to another agent when a condition is met, with context such as session variables.
  • Delegates: sub-agents that complete a subtask and return the result. The calling agent keeps control.
  • Escalation: triggers and routing to a human agent, with context and queue assignment.
See Multi-agent orchestration.

Supervisor agents

In a multi-agent project, use the SUPERVISOR block to define the agent that routes to the others.

Behavior and safety

Control how the agent enforces rules, filters content, and adapts to context.
  • Constraints: rules enforced at runtime. Unlike LIMITATIONS, a constraint with REQUIRE and ON_FAIL is hard enforcement. The agent can’t proceed until the condition is met.
  • Guardrails: content safety policies on inputs and outputs. They can block, redact, or flag content with built-in checks or external moderation providers.
  • Behavior profiles: settings that apply in a given context, such as a user role, a session flag, or a channel.
To keep one agent for chat and voice, put the spoken style in a phone behavior profile. See Keep one agent with a phone behavior profile.
See Safety and guardrails and Behavior profiles.

NLU intent classification

Use the NLU block to define intents, entities, and categories that classify user messages. It supports:
  • Intent classification with keyword patterns and example utterances.
  • Entity extraction with typed extractors: enum, pattern, location, date, number, and free text.
  • Synonyms that map variants to one value.
  • Embeddings-based matching when keyword patterns aren’t enough.
  • Multi-intent handling for several intents in one message.
  • Lookup tables to validate input, match fuzzily, and suggest corrections.
  • Per-language models and a glossary. See Multi-language support.
See NLU configuration.

Multi-language support

Build agents that detect the user’s language and reply in it. These settings apply to chat and voice. On voice, also check that the speech settings support each language. For a language policy and test plan, see Build multilingual agents.

Set up language detection

Route by language

Provide language-specific models

Route to different LLM models based on detected language.

Add a glossary

Add domain terms so the agent uses the right terminology in every language.

Set the language per environment

For a deployment that serves one market:
Configure DEFAULT_LANGUAGE=es for your Spanish market deployment and DEFAULT_LANGUAGE=en for English.

Use localized messages

Keep translated text in locale assets at Project > Settings > Localization. Reference a message with {{locale.<key>}}. The same key returns the text for the resolved language.
See Localization.

Voice agents

Deploy an agent to a voice channel for phone or SIP calls. Build the agent as described in this guide, tune it for speech, then connect it to the channel.
For voice scripts, recovery, and transfers, see Design voice conversations. For test plans, see Test voice agents.

Build a voice agent

  1. Build the agent. Define the identity, tools, and flow as for any agent.
  2. Write for the ear. Callers hear your replies, so keep them short and plain. Set EXECUTION.voice.instructions to give spoken-style rules. The runtime strips markdown from RESPOND: text before speech. Add a VOICE: block only when you need SSML or a different spoken version. Your instructions replace the default spoken-style rules, so restate rules such as “plain speech, no lists”. To keep one agent for chat and voice, use a phone behavior profile.
  3. Set how the agent listens. Use CONVERSATION.listening to decide what happens when the caller stays silent (on_no_input) or talks over the agent (barge-in). Use DTMF: on a GATHER field for keypad entry, and SECURE_INPUT for card numbers and other sensitive values.
  4. Plan hold, hang-up, and transfer. Use COMPLETE to end the call, on_caller_hold_limit to handle a long hold, and ESCALATE to transfer the call to a human.
  5. Connect a voice channel. Follow Enable voice interactions to add credentials, create the channel, and test with the Soft Phone.
  6. Check the traces. After a test call, open the traces to confirm what the agent heard and said. See Check each test call.

Choose a voice architecture

Pick the architecture when you create the channel. Each voice setting in the voice reference states where it applies.

Example

This agent greets the caller, speaks in short sentences, and hangs up politely after two silent prompts.
For every voice setting, with values, defaults, and where each applies, see Voice in ABL.

Test your agent

Test the agent in Studio’s chat. Test chats run on the working copy.
  1. Open the agent from the Agents list.
  2. Open the Chat tab.
  3. Send messages. The agent’s replies appear in real time.
To test a voice agent, call it with the Soft Phone. See Enable voice interactions.

Debug panel

The chat view has a debug panel.
Use trace events to see why the agent made a decision. They show each reasoning step, tool call, and reply.

Debug context

The Debug context dialog sets context for new chats and Studio voice test calls in the project. These settings apply to new chats and Studio voice test calls in the current project. They’re stored in the browser and cleared when you sign out.

Sessions

Each test conversation creates a session. You can start a new session, view past sessions on the Sessions page, and copy a session ID for debugging.

Use the AI Architect

The AI Architect is an AI assistant built into Studio. Open it from the Architect icon in the Studio header. It adapts to what you’re editing. In a section such as Identity or Tools, it suggests changes as a diff that you can accept, reject, or refine.
The AI Architect needs an LLM provider configured at Admin > Arch. Without one, the panel shows a warning.

Troubleshooting

For NLU accuracy issues, see NLU configuration.
Related articles: