Skip to main content
This guide walks you through writing effective guidance for your AI agent. Start with one general-purpose guidance rule, test it, then add targeted rules for specific scenarios as you learn from real conversations.

​
Writing Instructions

Write guidance as if you were training a new team member. Be specific about what to do, when to use tools, and how to communicate. 
Good:
"When a customer requests a refund, look up their order using `search_orders`.
If within 30 days, process using `create_refund` and confirm. If outside 30 days,
explain the policy and offer store credit."

Avoid:
"Help customers with refunds."
Set explicit boundaries for topics outside your AI’s scope: 
"If users ask for legal, medical, or financial advice, explain you can't help
with that and offer to connect them with the right team using `offer_handoff`."

​
Structuring with XML Tags

For complex guidance covering multiple concerns, use XML tags to organize sections: 
<use-language>
Always respond in the customer's language. If they write in German,
respond in German.
</use-language>

<tone-and-style>
Be professional yet friendly. Use clear, concise language.
Avoid jargon unless the customer demonstrates technical expertise.
</tone-and-style>

<escalation-criteria>
Escalate to human support if:
- Customer explicitly requests a human agent
- Issue involves account security or billing disputes
- You cannot resolve after 3 attempts
</escalation-criteria>
XML tags work well when guidance exceeds 10–15 lines or covers multiple distinct areas. For short, focused guidance, skip them.

​
Tools

Configured tools (actions, search tables, Unitools) aren’t available to the AI by default. You must explicitly enable each tool on a guidance rule for the AI to use it in conversations matching that rule. The simplest way to enable a tool is to mention it with @ in your instructions (for example, @search_products). This enables the tool on that guidance rule automatically and follows the best practice of always explaining when to use an enabled tool: 
When a customer asks about product availability or pricing, look up
the answer using @search_products before responding.
You can also enable tools manually in the Allowed Tools section of each guidance rule. Combine this with audience targeting to restrict tool access to specific customer segments or channels.
Only enable tools the AI needs for a given guidance rule. Extra tools add decision overhead and can lead to unnecessary tool calls.

​
Personalizing with Liquid

Instructions support Liquid templating for dynamic, personalized behavior. Available variables:
VariableDescriptionExample
{{user.first_name}}User’s first name”Sarah”
{{user.email}}User’s email address”sarah@example.com”
{{user.external_attributes.plan}}Custom attribute”enterprise”
{{conversation.channel_type}}Current channel”Zendesk,” “Slack,” “web”
Personalized greeting: 
Always greet the user by name: "Hello {{user.first_name}}, how can I help you today?"

{% if user.external_attributes.plan == "enterprise" %}
You are speaking with an enterprise customer. Prioritize their requests
and offer to schedule a call with their account manager if needed.
{% endif %}
Channel-specific behavior: 
{% if conversation.channel_type == "zendesk" %}
You are assisting a support agent. Keep responses concise and factual.
{% elsif conversation.channel_type == "slack" %}
Keep messages brief and use casual, friendly language.
{% else %}
Use a professional yet warm tone for website visitors.
{% endif %}
Store custom user data (subscription tier, company size, feature flags) in external attributes and access them via {{user.external_attributes.your_field}}.

​
Audience Targeting

Audience filters control which guidance rules and tools apply to a conversation. This is how you restrict instructions and capabilities to specific customer segments or channels. Without audience filters, every active guidance rule applies to every conversation. Click “Add Audience Filter” in any guidance rule to build targeting rules. User attributes: 
User → Plan → equals → "enterprise"
User → Location → starts with → "EU"
User → Email → ends with → "@company.com"
Conversation context: 
Conversation → Channel → equals → "zendesk"
Message → Contains → "urgent"
Combining conditions with AND/OR logic: 
(User.plan = "enterprise" OR User.plan = "business")
AND
User.location starts with "US"
Use audience filters instead of cramming conditional logic into one rule. Separate guidance rules per segment keep instructions focused and ensure the AI only has access to the tools each segment needs.

​
Guidance Order

The AI receives all matching guidance rules as a single combined prompt. The list order in the UI determines the order they appear in that prompt. Drag rules to reorder them. Audience filters are the primary mechanism for scoping behavior. Order is secondary, but place the most important instructions first for clarity: 
1. Zendesk Agent Assist  (audience: channel = zendesk, mode = private)
2. Zendesk Public Reply  (audience: channel = zendesk, mode = public)
3. Website Chat          (audience: channel = web)
4. General Assistant     (audience: everyone)

​
Procedures

For multi-step processes that require strict sequencing and conditional logic, use procedures instead of guidance. Procedures let you define structured workflows with branching, code-based checks, and guaranteed enforcement of business rules. Use procedures for refund flows, identity verification, account changes, and other processes where steps must happen in the right order and eligibility checks must be deterministic.

​
Guidance vs. Procedures

GuidanceProcedures
PurposeShape behavior and toneExecute multi-step processes
StructureFree-form instructionsOrdered steps with control flow
LogicNo branchingIf/else conditions, code checks
EnforcementAgent interprets on its ownDeterministic, agent follows the defined path
Use casesTone, policies, general rulesRefunds, returns, verifications, escalations
Most agents use both: guidance for general behavior and procedures for structured workflows. Start with guidance and add procedures when you need enforced step-by-step processes.

​
Common Patterns

Guidance 1: Enterprise Support
Instructions: "Provide detailed answers. Proactively offer resources.
Use `search_advanced_docs` for technical details. Offer to schedule
a call with the success team."
Audience: User.plan = "enterprise"
Tools: search_advanced_docs, search_web, offer_handoff

Guidance 2: Standard Support
Instructions: "Help users solve common issues. Point to documentation.
Escalate complex issues to the support team."
Audience: Everyone
Tools: search_docs, offer_handoff

Guidance 1: Sales Assistant
Instructions: "Focus on product benefits and use cases. Highlight
features relevant to the user's industry. Offer demos and trials."
Audience: User.is_customer = false
Tools: search_products, search_case_studies, search_web

Guidance 2: Customer Support
Instructions: "Help customers use the product. Answer how-to questions
and troubleshoot issues. Search documentation first."
Audience: User.is_customer = true
Tools: search_docs, search_products, offer_handoff

Guidance 1: Zendesk Agent Assist
Instructions: "You're assisting support agents, not end customers.
Provide concise, factual information agents can relay. Include
ticket number references and knowledge base links."
Audience: Channel = "zendesk", Mode = "private"
Tools: search_docs, search_tickets

Guidance 2: Website Chat
Instructions: "Engage directly with website visitors. Be welcoming.
Qualify leads by understanding needs before recommending solutions."
Audience: Channel = "web"
Tools: search_products, search_web, offer_handoff
After writing your guidance, build and deploy a new version to make changes live. Use test suites to validate behavior before deploying.