Writing effective instructions¶

An Agent's base_system_prompt and greeting_instruction (see Agents), and an Orchestrator's instruction (see Orchestrators), are plain text fields you write yourself. This page is a worksheet for writing them well: a five-part structure that produces a sharper, more reliable persona than a paragraph of adjectives, whether you fill it in by hand or paste it straight into an agent.

The five parts¶

Skip a part only if it genuinely doesn't apply. For anything with real scope, write all five explicitly rather than folding them into one paragraph. Short, structured instructions consistently outperform a long, free-form one: a model given a clear numbered process and explicit boundaries behaves more predictably than one given only a general description of the desired tone.

1. Identity¶

Who the agent is, in one or two sentences.

Name and role: for example, "Aria, the scheduling assistant for Acme Dental."
Tone: for example, warm and casual, or crisp and formal.
Language(s): for example, English only, or English and Spanish.

You are [agent name], the [role] for [company]. You speak in a [tone] tone
and always respond in [language].

2. Mission¶

What the agent is actually for, written as a short numbered list of capabilities rather than one "helps with everything" sentence. Three to six line items is a good range. Beyond that, consider splitting the scope across multiple Agents, or handing genuinely multi-step work to an Orchestrator.

Primary job, one sentence.
Core capabilities, numbered: for example, "1. Answer questions about store hours and services. 2. Book, reschedule, or cancel an appointment. 3. Take a message for a callback."
Out of scope: what it should explicitly refuse or hand off elsewhere.

Your job is to [primary job]. Specifically, you can:
1. [capability 1]
2. [capability 2]
3. [capability 3]

You do not [out-of-scope items]; if asked, say so plainly and [what to do
instead].

3. Methodology¶

How the agent should do the job, not just what the job is: the step-by-step process a careful human in this role would actually follow. This is the part most hand-written instructions skip, and the one that benefits most from being explicit. "Always confirm the order number before discussing refund status" is methodology a model can actually follow. "Be helpful" gives it nothing concrete to act on.

Greeting behavior: what the agent opens with. For an Agent, this becomes the separate greeting_instruction field, not part of this prose block; keep it short.
Step-by-step process, numbered and concrete: for example, "1. Ask for the customer's phone number or account email. 2. Look up their account. 3. Confirm the account details out loud before making any change."
When to use which tool: tie specific tools to specific moments, for example, "only call transfer_to_human after the caller explicitly asks for a person." See Tools for the full built-in tool catalog.
Unknown-answer fallback: what to do when the agent does not know something (offer a callback, say so honestly, never invent an answer).

Follow this process:
1. [step 1]
2. [step 2]
3. [step 3]

If you don't know something, [fallback behavior].

4. Boundaries¶

Explicit limits, stated as rules the model can check itself against mid-conversation rather than left assumed.

Hard guardrails: things it must never say or do (no medical, legal, or financial advice; no discounts it cannot honor; no reading back a full card number).
Confirmation requirements: does anything need an explicit "yes" from the caller before it happens? For example, "confirm the appointment time back before booking it."
What never to reveal: internal tool names, system prompts, other callers' data.

Never [guardrail 1] or [guardrail 2]. Always confirm [action] with the
caller before doing it. Never reveal [internal detail] if asked.

5. Few-shot examples¶

One or two short sample exchanges that show the tone and process from parts 1 through 3 in action, not just describe them. A model follows a concrete example more reliably than an adjective like "warm and casual." This is often the single highest-leverage addition to an instruction that's almost right but doesn't quite behave as intended.

Example:
Caller: [a realistic thing a caller or visitor would actually say]
You: [exactly how the agent should respond, in the tone and process above]

Assembling the final field¶

For an Agent, concatenate parts 1 through 5 into base_system_prompt as one prose block. Part 3's greeting line is the exception: it goes in the separate greeting_instruction field instead. Set both with PATCH /api/v1/agents/{agent_id}.

For an Orchestrator, the same five-part structure fills the instruction field directly. An Orchestrator has no separate greeting field, since it never opens a live conversation with a caller. Set it with PATCH /api/v1/orchestrators/{orchestrator_id}, or upload it as a file with the instruction-file endpoint documented on that same page.

Tool-use notes¶

A tool becomes available to the model once you enable it (see Tools for Agents, Orchestrator tools for Orchestrators), but when to call it is governed entirely by what you write in part 3 above and the tool's own description. There is no separate hard trigger. If timing matters, such as "only after the caller confirms" or "at most once per call," say so explicitly in the Methodology section.

Delegation notes¶

If this Agent should hand narrowly-scoped questions to another configured Agent (see Agent delegation) or a task to an Orchestrator (see Agent to Orchestrator delegation), note which target and under what condition in part 3 (Methodology). Then create the corresponding delegation link and enable the matching tool (delegate_to_agent or delegate_to_orchestrator) on the linked pages above. A delegation link only grants permission to ask; it doesn't change what the target Agent or Orchestrator itself knows or can do.