Prompt Engineering Guide

How a Capacity agent behaves comes down to a specific set of configurable pieces working together — the prompt, exit conditions, data sources, tools, variables, and model settings. This guide covers how to use each one well, for a single agent or for an agent on a team.

What Controls How an Agent Behaves

Prompt — the instructions that govern identity, tone, and task logic.
Exit Conditions (single agent) — a plain-language description of when the conversation is done, checked separately from the main conversation.
Data sources — which knowledge the agent can retrieve from.
Tools — what the agent can do, and how well it understands when to do it.
Variables — what the agent collects and carries forward.
Model options — which model runs the agent, and its temperature.

If the agent is part of an Agent Team, all of the above still applies — with two differences covered at the end of this guide.

Plan Before You Configure

Before writing a single line of prompt, write down what the agent is actually for: what it needs to accomplish, what information it needs from the person it's talking to, what it needs to look up, and what "done" looks like. Also decide upfront whether this is a single agent or whether the scope is broad enough to need a team (see the closing section).

A short plan should answer:

What's the goal of this conversation, and what counts as a successful outcome?
What does the agent need to know or collect from the person to get there?
What does it need to look up, and where does that information live?
What should happen when it can't help — escalate, hand off, or just say so?

Writing this down first keeps the prompt itself from having to improvise structure while you're also trying to write good instructions.

Write the Prompt as Structured Sections

Break the prompt into focused sections for better organization and LLM comprehension. This structured approach offers several benefits:

Reusability: Sections can be adapted across different agents.
Maintainability: Easy to update specific behaviors without affecting others.
Clarity: LLMs process structured information more accurately.

Recommended Prompt Structure

## Identity
You are a friendly AI assistant for [Company Name].
Your role is to [specific purpose].
You have expertise in [relevant domains].

## Style Guardrails
Be concise: Keep responses under 2 sentences unless explaining complex topics.
Be conversational: Use natural language, contractions, and acknowledge what the caller says.
Be empathetic: Show understanding for the caller's situation.

## Response Guidelines
Return dates in spoken form: Say "January fifteenth" not "1/15".
Ask one question at a time: Avoid overwhelming the caller with multiple questions.
Confirm understanding: Paraphrase important information back to the caller.

## Task Instructions
[Specific steps the agent should follow]

## Objection Handling
If the caller says they're not interested: "I understand. Is there anything specific..."
If the caller is frustrated: "I hear your frustration, let me help resolve this..."

Write the Agent's Exit Condition

For a single agent, the Exit Conditions field is one plain-language description of what "done" looks like for this conversation — not multiple named outcomes. It isn't something the agent's main prompt outputs or triggers inline: a separate evaluation step reads this text alongside the conversation after each turn and judges whether it's been met, responding with exactly true or false. Nothing else comes back from that check, and there's no support for multiple named results (like "conclude" vs. "escalate") at this level.

Because it's evaluated separately from the main conversation, writing conditional trigger instructions into the agent's main prompt ("if the caller says X, exit") has no effect on it. Write the Exit Condition as its own, self-contained description instead:

Describe the completed state, not an action. "The caller's question has been fully answered and they've confirmed they don't need anything else" gives the evaluator something concrete to check against the transcript — better than an instruction like "exit when the caller says goodbye."
Be unambiguous. The evaluator only has this text and the conversation history to go on — vague language like "when appropriate" leaves it guessing.
Keep it to the one outcome this agent is responsible for. If the conversation needs different exit paths (a normal close vs. an escalation), that's handled through an Agent Team's own exit conditions, not by trying to encode multiple outcomes into this one field.

Example: A Well-Written Exit Condition

The default Exit Conditions prompt is deliberately generic:

Decide whether this conversation should end now.

Examine the most recent exchanges. Respond with exactly "true" if the user's intent has been resolved or they have indicated they wish to stop, and "false" if more conversation is needed. Output only the literal token "true" or "false" with no other text.

Keep the scaffolding — the instruction to examine recent exchanges, and the exact "output only true or false" line — but replace the middle condition with something specific to what this agent is actually for. For an agent that only handles order-status lookups:

Decide whether this conversation should end now.

Examine the most recent exchanges. Respond with exactly "true" if the caller has received their order status and either confirmed they don't need anything else or said goodbye. Respond with "false" if they're still waiting on a lookup, have asked a follow-up question, or haven't confirmed they're done. Output only the literal token "true" or "false" with no other text.

The second version gives the evaluator a concrete, checkable condition tied to this agent's actual job, instead of relying on the generic "intent has been resolved" language to cover every case.

Note: "Exit Conditions" means two different things depending on where you're looking. On a single agent, it's this one plain-language field, evaluated on its own to true/false. On an Agent Team, exit conditions are a separate, named construct (e.g. conclude, escalate) configured at the team level — and a member agent's own Exit Conditions field is ignored entirely once it's part of a team. Don't assume the two work the same way just because they share a name.

Scope Your Data Sources

Only give an agent the data sources it actually needs for its job. A knowledge base with every product line in it competes against itself at retrieval time — the correct answer can be buried in ranking competition from content the agent never needed access to in the first place, even when nothing is technically missing from the knowledge base.

Folder Level Scoping

When using our native Knowledge Base Data Source, you also have the ability to narrow a search further at query time, directly from the prompt — e.g. telling the agent "when the caller asks about a specific product manual, search the folder id 23344" — without any additional configuration. This will only be able to narrow within the data sources already scoped to the agent, not expand beyond them. The folder ID can be found in the URL path of the folder in the KB.

Connect Tools and Describe Them Well

Two different things shape how well an agent uses a tool, and they do different jobs.

The Agent Tool Description is configured on the tool itself and is shared by every agent that uses it. It's the only thing the model sees when deciding whether and how to call the tool, so it should describe the tool generically: what it does, what its parameters mean, and roughly when it applies — the same description holds regardless of which agent is calling it.

Note: This description can be found in the Developer Platform for the specific API endpoint. When the endpoint is selected, there is an input box in the right rail, labeled "Agent Tool Description".

What the Agent Tool Description can't capture is anything specific to how one particular agent should use that tool — because the same tool might need to be used differently depending on the conversation it's embedded in. That's what belongs in the prompt itself.

Say when this agent, specifically, should call it — a shared tool used by three different agents might have three different "when" rules.
Set boundaries for when this agent should not call it.
Give any parameter guidance specific to this agent's context — e.g. which folder or scope to search, if that varies by agent.
For voice, narrate before a slow call. Dead air while a tool runs reads as the agent freezing. Tell the agent directly, in the prompt, to say something first:

Before calling `check_order_status`, say something like:
"Let me look that up for you now."
Then call the tool immediately after.

See Configuring Your Voice Agent for Speed for more on why this matters for perceived response time.

Example: Tool Trigger Instructions

## Tool Usage Instructions

1. Gather initial information about the customer's issue.

2. Determine the type of request:
   - If customer needs order status:
     -> Call function `check_order_status` with order_id
   - If customer wants to change their order:
     -> First call `check_order_status`
     -> Then ask what they'd like to change

3. After retrieving information:
   - Always summarize what you found
   - Ask if they need additional help

Declare Variables and Describe Them Well

Each variable you declare on an agent has a name, a type, a description, and whether it should be prioritized. The description isn't just documentation — it's what tells both the variable-collection step and the model itself what the variable means, what format to expect, and when it should or shouldn't have a value.

State the format explicitly. "10-digit US phone number, digits only" is more useful than "phone number."
Give an example value. A concrete example resolves ambiguity faster than more prose.
Say when it's expected to be empty, if that's a valid state — e.g. a variable that's only collected partway through the conversation.
Mark it required only if the conversation genuinely can't proceed without it. Over-marking variables as required makes every gap in collected data look like an error.

Flag for review: exactly how an unset or undeclared variable behaves when referenced in a prompt is still being confirmed internally. Until that's settled, write prompts defensively: tell the agent explicitly how to handle a variable that might not have a value yet (e.g. "If you don't yet know the caller's name, ask for it rather than assuming") instead of relying on a specific blank/placeholder behavior.

Choose Model Options Deliberately

Each agent has its own model and temperature setting — these aren't fixed platform-wide, and they're worth deciding on purpose rather than leaving at a default.

Lower the temperature toward zero for agents that need consistent, repeatable answers — compliance-sensitive flows, precise confirmations, anything where you don't want wording to vary call to call.
Allow a higher temperature where natural variation makes the conversation feel less scripted, and exact wording isn't load-bearing.
Pick the model for the task, not by default. A simple, narrow agent may not need your most capable (or slowest) model; a complex reasoning-heavy agent might need more than the fastest option provides.

Agent Teams: Same Levers, Two Differences

Everything above still applies to each agent on a team. Two things work differently than they do for a standalone agent:

The team itself has no prompt. Each member's own prompt still does all the same work described above — but should be scoped more narrowly than a standalone agent's prompt, since responsibility for the overall conversation is now split across members instead of held by one.
Each member's own Exit Conditions field is ignored. Exit conditions are configured at the team level instead of on each member agent.

Team membership also introduces a new piece of "prompting": the role description written for each member. This is what determines whether a given turn gets routed to this agent at all, so it deserves the same care as a good AI Tool Description — write it as specific, actionable guidance about when this agent should handle a turn, not a one-line job title. A vague role description leads to a turn landing on the wrong agent just as easily as a vague tool description leads to the wrong tool being called.

Was this article helpful?