Skip to main content

​
Instruct AI Agent

Your AI’s behavior is defined by guidance - the instructions, tools, and rules that control how it responds to users. Unlike static chatbots with fixed responses, botBrains lets you craft dynamic, context-aware behavior that adapts to different situations and user segments.

​
Why Behavior Configuration Matters

Your AI needs clear instructions to provide valuable customer service. Proper behavior configuration enables your AI to:
  • Maintain brand voice - Ensure every response reflects your company’s tone and values
  • Handle different scenarios - Respond appropriately whether users need sales info, technical support, or account help
  • Use the right tools - Access search tables, web search, or escalation capabilities when needed
  • Personalize interactions - Adapt responses based on user attributes like plan tier, location, or role
  • Evolve continuously - Update behavior as your product and customer needs change
Think of guidance as training sessions for your AI - you’re teaching it how to represent your company to customers.

​
Understanding Behavior Configuration

Your AI’s behavior is defined in the Behavior section of the platform, which includes:
  • Guidance rules - Instructions for different scenarios
  • Tool access - Which capabilities the AI can use
  • LLM settings - Model selection and configuration
Behind the scenes, these settings are stored together in a versioned object called a Profile for versioning purposes. This allows you to:
  1. Edit your current behavior configuration
  2. Build a new version when ready
  3. Deploy the version to production
  4. Roll back to previous versions if needed
This versioning ensures you never lose working configurations and can test changes before deploying.

​
Creating Effective Guidance

Guidance rules are the building blocks of your AI’s behavior. Each guidance defines:
  • Instructions - What the AI should do and how
  • Audience - Which users this guidance applies to
  • Tools - Which capabilities the AI can access

​
Anatomy of a Guidance Rule

Navigate to Behavior → Guidance to manage your guidance rules. Name
  • Descriptive label for organization
  • Example: “Sales Inquiries”, “Technical Support”, “Premium Customer Service”
Instructions
  • Natural language description of desired behavior
  • Rich text editor with formatting support
  • Reference tools using inline code: search_products
  • Be specific about tone, detail level, and response format
Allowed Tools
  • Select which capabilities this guidance can use
  • Tools mentioned in instructions are auto-enabled
  • Examples: search_web, search_products, offer_handoff
Audience
  • Define which users this guidance applies to
  • Use query builder to filter by attributes
  • Leave empty for “everyone”
Active Status
  • Toggle guidance on/off without deleting
  • Inactive guidance is skipped during conversations

​
Personalization with Liquid Templating

Your instructions support Liquid templating, allowing you to personalize guidance based on user attributes and conversation context. 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 (e.g., subscription tier)“enterprise”
{{conversation.channel_type}}Current channel”zendesk”, “slack”, “web”
Example: 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 dedicated account manager if needed.
{% endif %}
Example: 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 %}
Use external attributes to store custom user data like subscription tier, company size, or feature flags. Access them via {{user.external_attributes.your_field}}.

​
Writing Instruction Templates

Your instructions guide the AI’s responses. Follow these principles: Be Specific 
Good:
"Help users find products by asking clarifying questions about their needs,
budget, and preferences. Search the product catalog using `search_products`
and recommend 2-3 options with pros and cons for each. Keep responses
concise (under 150 words) and friendly."

Avoid:
"Help users find products."
Define Tone and Style 
"Use a professional yet warm tone. Address users by first name if available.
Avoid jargon unless the user demonstrates technical expertise. Use bullet
points for lists of features or steps."
Specify Tool Usage 
"Before answering questions about pricing or availability, always search
the product catalog using `search_products`. For general product questions,
search the knowledge base first. Only use `search_web` if our internal
resources don't have the answer."
Set Boundaries 
"If users ask about topics outside your expertise (legal advice, medical
recommendations, financial guidance), politely explain you can't help with
that topic and offer to connect them with appropriate resources using
`offer_handoff`."
Include Examples 
"When explaining technical concepts, use analogies. For example, explain
API rate limits like: 'Think of API calls like ordering coffee - you can
make 1000 orders per hour, but if you try to order more, you'll need to
wait until the next hour starts.'"

​
Using XML Tags for Structure

For long or complex guidance, use XML tags to organize instructions into logical sections. This helps the AI understand different aspects of behavior and improves instruction clarity. Functional Organization Use XML tags to separate different functional requirements: 
<use-language>
Always respond in the customer's preferred language. If they write in German,
respond in German. If they write in English, respond in English.
</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 human agent
- Issue involves account security or billing disputes
- You cannot resolve after 3 attempts
</escalation-criteria>
Custom Formatting Requirements When your AI needs to follow specific formatting rules, use XML tags to make them explicit: 
<brand-formatting>
Always write the brand name as <span style="font-weight: bold; color: #ff5926">skapetze<sup>®</sup></span>
</brand-formatting>

<product-display>
Display products in a carousel format using this syntax:

<carousel>
<slide image="[url]" title="[name]" price="[price]" link="[url]" subtitle="[brief features]"></slide>
<slide image="[url]" title="[name]" price="[price]" link="[url]" subtitle="[brief features]"></slide>
</carousel>

Important: You must call a product search tool before displaying the carousel
to get accurate product links and details.
</product-display>

<response-structure>
Use markdown hierarchy to organize responses:
- # for main topics
- ## for subtopics
- ### for detailed sections
- #### for sub-details
- Numbered lists for sequential steps
</response-structure>
Example: E-commerce Product Recommendations 
<product-recommendations>

<search-first>
Before recommending products, always use `search_products` to find current
inventory, pricing, and availability.
</search-first>

<presentation-format>
Present product recommendations in a carousel:

<carousel>
<slide image="product_image_url" title="Product Name" price="€XX.XX" link="product_url" subtitle="Key features that match customer needs"></slide>
</carousel>

Keep subtitle to one concise sentence highlighting relevant features.
Each product gets its own slide.
</presentation-format>

<brand-consistency>
Write company name as <span style="font-weight: bold; color: #ff5926">skapetze<sup>®</sup></span>
</brand-consistency>

<response-organization>
Structure recommendations using markdown:
1. Brief greeting and acknowledgment of customer needs (##)
2. Product recommendations in carousel
3. Additional guidance or alternatives (###)
4. Next steps or questions (###)
</response-organization>

</product-recommendations>
Benefits of XML Tags
  • Clarity: Separate concerns into distinct sections
  • Maintainability: Easy to update specific aspects without affecting others
  • Readability: Clear structure for both humans and AI
  • Scalability: Add new sections without restructuring entire guidance
When to Use XML Tags Use XML tags when:
  • Guidance covers multiple distinct functional areas
  • You need specific formatting or output requirements
  • Instructions are longer than 10-15 lines
  • Different team members manage different aspects of behavior
Keep it simple when:
  • Guidance is short and focused on one task
  • Instructions are straightforward without special formatting
  • Adding tags would make instructions harder to read

​
Audience Targeting

Audience targeting lets you create different behavior for different user segments.

​
Why Use Audiences?

  • Tiered Support - Premium customers get different service than free users
  • Regional Adaptation - Adjust responses for language, timezone, or local regulations
  • Role-Based Behavior - Treat developers differently from business users
  • Channel-Specific - Behavior varies by integration (website vs. Zendesk vs. Slack)

​
Creating Audience Rules

Click “Add Audience Filter” in any guidance 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"
Conversation → Topic → contains → "billing"
Message → Contains → "urgent"
Time Conditions 
Current Time → Hour → between → 9 and 17
Current Time → Day of Week → in → ["Monday", "Tuesday", "Wednesday"]
Combining Conditions Use AND/OR logic to create complex rules: 
(User.plan = "enterprise" OR User.plan = "business")
AND
User.location starts with "US"

​
Tool Configuration

Tools extend your AI’s capabilities beyond conversation. Configure tools in the Tools tab.

​
General Tools

Enable built-in capabilities: Web Search
  • Search the internet for current information
  • Use when: Product launches, news, real-time data
  • Example: “What are the latest features in version 2.0?”
Fetch Web Pages
  • Retrieve specific URLs for content
  • Use when: Reading documentation, release notes, blog posts
  • Example: “Summarize the changelog from our blog”
Offer Handoff
  • Create email escalation to support team
  • User reviews and confirms before sending
  • Use when: Complex issues requiring human expertise
Escalate to Human
  • Immediately transfer conversation to support
  • No user confirmation required
  • Use when: Urgent issues, compliance concerns, high-value customers
Only enable tools your AI actually needs. Extra tools add decision overhead and can confuse the AI about when to use each one.

​
Search Tables

Connect structured data sources for precise information retrieval:
  1. Navigate to Tools → Search Tables
  2. Click Add Search Table
  3. Configure:
    • Tool Name: How AI refers to it (e.g., search_products)
    • Description: When to use this tool
    • Select Table: Choose your configured table
  4. Save
The AI automatically generates search parameters based on user questions. Example Configuration 
Tool Name: search_products
Description: Search our product catalog by category, price range, brand,
and availability. Use this when users ask about products, features, pricing,
or inventory.
Table: product_catalog

​
MCP Servers

Connect external systems via Model Context Protocol:
  1. Navigate to Tools → MCP Servers
  2. Add Server with URL and authentication
  3. Import Tools from the server
  4. Configure approval requirements for each tool
MCP servers enable integrations with CRM, ticketing, databases, and custom APIs.

​
Guidance Priority and Matching

When multiple guidance rules exist, the AI uses the first matching rule based on:
  1. Order in the list - Drag to reorder guidance rules
  2. Active status - Only active guidance is considered
  3. Audience match - User must match audience criteria
  4. Tool availability - Required tools must be enabled

​
Organizing Guidance

Specific to General Place targeted guidance first, general guidance last: 
1. Premium Support (audience: enterprise customers)
2. Billing Questions (audience: topic contains "billing")
3. Product Questions (audience: everyone)
4. General Assistant (audience: everyone, fallback)
By Channel Different behavior per integration: 
1. Zendesk Private Mode (audience: channel = zendesk, mode = private)
2. Zendesk Public Mode (audience: channel = zendesk, mode = public)
3. Website Chat (audience: channel = web)
4. Slack Internal (audience: channel = slack)
By Use Case Organize around common scenarios: 
1. Sales Inquiries
2. Technical Support
3. Account Management
4. Onboarding
5. General Questions

​
Building and Deploying

After editing guidance, you must build and deploy a new version.

​
Build Process

  1. Make Changes - Edit guidance, tools, or settings
  2. Review - Check “Unsaved Changes” indicator
  3. Build Version - Creates new immutable version
  4. Wait - System processes changes and creates deployment
  5. Deploy - Set new version as active in production

​
Build Options

Build Version, Set Active
  • Creates new version and deploys to production immediately
  • Recommended for most updates
  • Takes 30-60 seconds
Build Version
  • Creates version without deploying
  • Use when: Testing changes before going live
  • Deploy manually later from General tab
Build Version, Set Active, Get Email
  • For large deployments affecting many channels
  • Receive email notification when complete
  • Use when: Major behavior changes, many integrations

​
Deployment Status

Check deployment health in the header: Knowledge Fresh
  • Green indicator: AI has latest knowledge
  • Orange indicator: Knowledge sources updated, rebuild needed
Unsaved Changes
  • Orange indicator: Edits not yet built
  • Build required to save changes
Changes Saved
  • Gray indicator: No pending edits

​
Best Practices for Writing Guidance

​
Write Clear, Specific Instructions

Be explicit about what your AI should do. Instead of “be helpful with refunds,” write step-by-step instructions with specific criteria and actions. Example: 
Good: "When a customer requests a refund, first check the order date
using `search_orders`. If within 30 days, process using `create_refund`.
If outside 30 days, explain the policy and offer store credit."

Avoid: "Help customers with refunds."

​
Use Natural Language

Write guidance as if you’re training a new team member. You don’t need technical jargon - explain what to do and why in plain language. Example: 
"When customers ask about shipping times, tell them standard shipping
takes 5-7 business days. If they're in the US, mention free shipping
over $50. Always check their location first using `get_user_location`."

​
Reference Tools Inline

Mention tools naturally in your instructions using inline code formatting: `tool_name`. This makes instructions readable and automatically configures tool access. Example: 
"Search the knowledge base using `search_kb` before answering technical
questions. If you can't find an answer, use `search_web` to check our
public documentation."

​
Start Narrow, Then Expand

Begin with guidance for the most common or critical scenarios. As you see how your AI performs, add more guidance to handle edge cases and new situations. Start with: 
Name: General Customer Support
Instructions: Help customers with common questions about products,
shipping, and accounts. Be friendly and professional.
Audience: Everyone
Then add specific scenarios: 
Name: VIP Customer Service
Instructions: Provide premium support with immediate escalation options.
Audience: user.tier = "VIP"

Name: Technical Support Escalation
Instructions: For complex technical issues, gather details and create
priority ticket using `create_ticket`.
Audience: Everyone

​
Test Before Activating

Create guidance as drafts first. Use the preview panel to test how your AI responds with the new guidance before marking it as live.
  1. Write guidance and save as draft
  2. Use preview panel to test responses
  3. Refine instructions based on test results
  4. Activate when satisfied

​
Review and Refine

Monitor conversations to see how guidance performs in practice. Update instructions based on real customer interactions to continuously improve quality. Regular review process:
  1. Check recent conversations in Analyze
  2. Identify where AI responses could improve
  3. Update relevant guidance instructions
  4. Build and deploy new version
  5. Monitor impact of changes

​
Consider Audience Targeting

If different customer segments need different treatment, use audience rules rather than trying to handle all scenarios in a single guidance rule. Instead of one complex rule: 
Instructions: "If the customer is VIP, do X. If they're enterprise, do Y.
If they're free tier, do Z..."
Use targeted guidance: 
Guidance 1: VIP Service (audience: user.tier = "VIP")
Guidance 2: Enterprise Support (audience: user.tier = "Enterprise")
Guidance 3: Free Tier Support (audience: user.tier = "Free")

​
Balance Guidance Quantity

Too few guidance rules may miss important scenarios. Too many overlapping rules can create confusion. Aim for clear, distinct scenarios with minimal overlap. Good structure:
  • 3-5 general guidance rules for common scenarios
  • 2-4 audience-specific rules for key segments
  • 1-2 channel-specific rules if needed
Avoid:
  • Dozens of highly specific rules that overlap
  • Single monolithic rule trying to cover everything

​
Managing Guidance Versions

Guidance is part of your AI’s behavior configuration, which also includes knowledge sources, available tools, and model settings. When you modify guidance:
  1. Make your changes in the Guidance tab
  2. Save changes by building a new version
  3. Deploy the version to make it active in production
This versioning system lets you test changes safely before they affect customer interactions. See Deployments for more on managing versions. Version strategically: Create new versions for:
  • Significant behavior changes
  • New tool additions
  • Audience targeting updates
  • Multiple guidance updates at once
Don’t create versions for:
  • Minor wording tweaks (batch several together)
  • Experimental changes (test in preview first)

​
Common Patterns

Goal: Premium customers get enhanced service
Guidance 1: Enterprise Support
Instructions: "Provide detailed, comprehensive answers. Proactively offer
resources and best practices. Use `search_advanced_docs` for technical
details. Always offer to schedule a call with our success team."
Audience: User.plan = "enterprise"
Tools: search_advanced_docs, search_web, offer_handoff

Guidance 2: Standard Support
Instructions: "Help users solve common issues efficiently. Point to
documentation and guides. Escalate complex issues to support team."
Audience: Everyone
Tools: search_docs, offer_handoff
Goal: Different behavior for prospects vs. customers
Guidance 1: Sales Assistant
Instructions: "Focus on product benefits and use cases. Highlight features
relevant to user's industry. Offer demos and trials. Use `search_case_studies`
to show customer success stories."
Audience: User.is_customer = false
Tools: search_products, search_case_studies, search_web

Guidance 2: Customer Support
Instructions: "Help customers use the product effectively. Answer how-to
questions and troubleshoot issues. Search documentation first."
Audience: User.is_customer = true
Tools: search_docs, search_products, offer_handoff
Goal: Adapt to integration context
Guidance 1: Zendesk Agent Assist
Instructions: "You're assisting support agents, not end customers. Provide
concise, factual information agents can relay to customers. 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 and
helpful. Qualify leads by understanding their needs before recommending
solutions."
Audience: Channel = "web"
Tools: search_products, search_web, offer_handoff
Goal: Different responses for regulated regions
Guidance 1: EU Data Privacy
Instructions: "When discussing data handling, emphasize GDPR compliance.
Provide links to privacy policy. Never share specific customer data without
explicit consent. Offer to connect users with data protection officer."
Audience: User.region starts with "EU"
Tools: search_privacy_docs, offer_handoff

Guidance 2: General Region
Instructions: "Answer data and privacy questions using standard privacy
policy. Focus on security measures and data protection."
Audience: Everyone
Tools: search_privacy_docs

​
Frequently Asked Questions

Symptoms: Responses don’t match your instructionsSolutions:
  • Check audience filters - user might not match criteria
  • Verify guidance is active (toggle on)
  • Review guidance order - a general rule might match first
  • Ensure required tools are enabled
  • Check instruction clarity - be more explicit
Symptoms: AI says it can’t use a tool you enabledSolutions:
  • Verify tool is checked in allowed_tools for the active guidance
  • Confirm tool is enabled in Tools tab
  • For search tables, ensure table exists and has data
  • For MCP servers, check connection status
  • Rebuild to apply tool changes
Symptoms: Similar questions get different answersSolutions:
  • Tighten instructions to reduce variability
  • Provide specific examples of desired responses
  • Use search tables instead of general knowledge for facts
  • Add explicit rules for edge cases
  • Review conversation history to identify patterns
Symptoms: “Build failed” error when creating versionSolutions:
  • Check for TODO items in advanced configuration
  • Verify all required fields are filled
  • Ensure at least one guidance exists (or system prompt in advanced)
  • Review error message for specific issue
  • Contact support if error persists
Symptoms: Orange “Knowledge Stale” indicatorSolutions:
  • Rebuild to use latest knowledge snapshots
  • This happens when data providers sync new content
  • Build process incorporates latest knowledge into deployment

​
Next Steps

Now that you understand how to instruct your AI: Your AI’s behavior is never “finished” - continuously refine guidance based on user interactions and evolving business needs.