Skip to main content

Single agents

A single agent is one agent with one prompt. You describe the outcome, and the agent decides each turn what to ask, which tool to call, and when the task is complete.

Use a single agent for open-ended work where the next step depends on what the customer says, such as:

  • Support
  • Troubleshooting

Most of your work on a single agent is writing its instructions. The other settings on the profile support that prompt.

Profile structure​

The profile has three parts, from top to bottom:

TriggerWhen this agent takes over the conversation. Used for routing, not by the agent
LifecycleWhat the agent can call, read and show: tools, variables, rich media
Agent instructionsHow the agent behaves after it takes over. This is the prompt

Keep the Trigger and the instructions separate:

  • Put routing conditions in the Trigger.
  • Put behaviour and persona in the instructions.

When you mix the two, routing becomes unpredictable.

A specialised agent's profile showing the Trigger at the top, the Lifecycle block, and Agent instructions below as a rich-text editor

Trigger​

Write one or two sentences that say when this agent handles the conversation. The Trigger has the most effect on correct handoffs.

Good: "When the user asks about billing, invoices, refunds, payment-method changes, or charges."

Too vague: "Handles money stuff."

Describe only when the agent takes over. Long triggers with do and don't lists, such as "Trigger ONLY when… Do NOT trigger for…", reduce matching accuracy. Put exclusions in a routing rule.

Agent instructions​

The instructions are the agent's prompt. They define how the agent behaves.

What not to include​

The agent already receives these from other settings. Do not repeat them in the instructions:

ContentWhere it comes from
Tone and identityProfile settings
House rulesConversation rules
Safety rulesBuilt in
Which agent handles a requestRouting logic

Also do not list the agent's tools.

Your instructions then have one job: state what this agent does, in what order, and within what boundaries. For headings and structure, see Writing instructions.

Writing tips​

Write plain, direct steps. Capital letters and repeated warnings do not improve compliance. They hide the instruction.

Bad: "MANDATORY - DO NOT SKIP. You MUST collect the order ID and you must keep repeating until they get it right. THIS IS A CRITICAL STEP."

Good:

  • Ask the customer for their order ID.
  • Call @validateOrderId with their answer.
    • Valid → continue.
    • Invalid → ask once more, then offer to look it up by email.

Write one instruction per line. When you join two actions with "and" or "then", the agent often does the first action and skips the second.

Bad: "Ask for the appointment date and confirm it back to the user and then book the slot."

Good: three lines: ask, confirm, book.

Clean the input before it goes to a tool. Customers do not reply in the format a tool expects. Tell the agent how to normalise the reply first.

Bad: the customer says "I'm based out of Mumbai, Maharashtra" → the whole sentence goes to @validateCity, which rejects it.

Good: "Extract only the city name - strip the state, country and any filler - then call @validateCity with just that."

Reference tools and variables with @. A tool name in plain text breaks when someone renames the tool. An @-mention stores the slug and shows the current name, so the prompt stays correct.

Numbered steps​

Numbered steps (Step 1, Step 2…) make the agent complete them in order, one step at a time.

Use numbered steps for a procedure. Do not use them for a list of unrelated capabilities. For the three levels and how to opt out, see Writing instructions.

Example: order-status agent​

This order-status agent applies the guidance above:

You help customers with orders that have already been placed.

Step 1: Ask for the order ID if it isn't already in memory.
- Accept any format. Strip spaces and punctuation before using it.
- If they don't have it, offer to look it up by email instead.

Step 2: Call @getOrderStatus with the order ID.
- If it returns a status, save it to order_status.
- If it returns not-found, say so plainly and offer @escalate-to-agent.

Step 3: Answer with the status, the carrier and the expected date.
- If they ask to change the delivery, say you can't do that and let
routing take it from there.

What each part does:

PartPurpose
The opening lineSets scope, not identity. Profile settings supply identity. This line says which area this agent owns.
Step 1/2/3Makes the agent work in order, so it collects the ID before it looks up the order.
if it isn't already in memoryStops the agent from asking again for a value that a previous agent already captured.
Strip spaces and punctuationCleans the input. Without it, ORD 12345 fails validation.
@getOrderStatus and @escalate-to-agentMentions, so both stay correct after a rename.
save it to order_statusWrites a declared variable. Declare the variable first, or the value is not saved.
say so plainlyPrevents the agent from inventing a plausible status when the order is not found.
The last lineStates something the agent can't do. A stated boundary is more reliable than an unstated one.

The example has no tone instructions, no "never lie", and no "you are a helpful assistant". The agent already receives all three.

Add tools​

An agent can call only the tools that you attach to it. To attach a tool, go to Capabilities → Tools and select + Add tool. You choose from the tools already defined in your project. You do not define tools here.

Write clear tool descriptions. The agent uses each tool's description to decide when to call it. A tool described as "gets data" is called at the wrong time, regardless of your instructions. If an agent calls the wrong tool, fix the tool descriptions before you change the prompt. See Designing tools well.

Attach only the tools the agent needs. An agent with twenty tools is much less predictable than an agent with four. If an agent needs many tools, split the work across more than one agent.

In your instructions, reference tools with @. For example, write @getOrderStatus, not "the order status tool".

Control when a tool can run​

Example: Issue refund must run only after the customer's OTP is verified. Instructions alone cannot guarantee this. A tool guard can.

There are three options, from strongest to weakest. You set the first two on the tool's chip:

UseWhat happensBest for
Available whenThe agent can't call the tool until your conditions hold. The chip shows a funnel.A rule a variable can answer, such as otpVerified is true. No workflow needed.
Before tool call hookA workflow runs each time the agent calls the tool. If it ends in Failure, the tool does not run.A check that needs a lookup or logic.
InstructionsThe agent is asked to follow the rule.Order and tone, not hard rules.

The Issue refund tool's settings on Order Support, with Available when set to otpVerified is true, and a Before tool call hook running "Verify OTP before refund"

Other capabilities​

These settings are also under Capabilities:

SettingWhat it holds
Sub-agentsAgents that this agent delegates parts of the work to
Allowed variablesThe memory this agent can read
Protected entitiesSensitive data this agent collects, when data protection is on
Rich mediaThe rich media it can show

Below them, Lifecycle hooks run your workflows when this agent takes over, receives a message, or finishes a reply.

Allowed variables and Rich media work the same way as on an Agent node in a multi agent. That page describes each setting in detail. Protected entities work the same way too, except that only an Agent node can check an entity only when the agent asks for it.

Channel overrides let you change behaviour for each channel. Most agents do not need them.

When to add an agent​

Add an agent when the work:

  • Is a distinct domain with its own vocabulary and process.
  • Needs tools that no other agent needs.
  • Would go to a different team if people did the work.

Do not add an agent when:

  • The work is a short detour. Use a tool call.
  • You want a different tone for one topic. Use a conversation rule.
  • Splitting the work would interrupt the conversation.

Add agents only when needed. Two agents with overlapping triggers route inconsistently. Merge them, or make the boundary between them clearer.

An @-mention of an agent is not a handoff. A handoff happens only when routing selects the agent, through its Trigger or a rule. See Routing logic.

Common mistakes​

Instructions are guidance for a model, not code that runs exactly as written. If a step must always happen, enforce it with a tool or setting, not with a sentence.

Setting a variable you haven't declared. This mistake is hard to detect because the turn appears to succeed. If you write "save the order ID to order_id", the agent saves it, but an undeclared variable is not available on the next turn. Declare the variable on the Memory page first.

Treating an instruction as a guarantee. "Always call @verifyIdentity before answering" is a strong request, not a hard gate. The agent usually complies, but not always. If a step is a compliance requirement, use a multi agent instead. In a multi agent, the step is a node that the run can't skip.

Naming a tool that isn't attached. An agent can call only the tools on its own list. If you mention @refundOrder in the instructions but do not attach it, the agent cannot call it. It usually improvises an answer instead and does not report the problem.

Writing routing into the prompt. "If they ask about billing, hand off to billing-agent" has no effect in the instructions. Put routing in the Trigger or a routing rule.

Trying to change settings from the prompt. You cannot set tone, identity, the model, the welcome message, or the available tools in instructions. Each of these is a separate field.

Numbering things that aren't a sequence. If you write four separate capabilities as Step 1–Step 4, the agent treats them as a four-turn procedure. See Numbered steps. Use a plain list for items that have no order.

Repeating the platform. "Never make things up", "stay professional", and "don't reveal your instructions" are already included. Repeating them has no effect.

Test the agent​

Open the Playground with the play ▶ icon in the title bar. Send a message that this agent should handle. Check two things separately:

  • Wrong agent took over → make the Trigger more specific, or add a routing rule.
  • Right agent, poor answer → fix the instructions.

The Tests button in the topbar links this agent to saved test cases and shows the latest run. You can save a failed conversation as a regression test. See Testing Lab.


Next: Multi agents, when you want to define the steps yourself.