Skip to main content

​
Guidance

Guidance is the heart of your AI’s behavior - it defines how you AI agent responds to customers, what actions it can take, and when to apply specific instructions. With guidance, you ensure consistent, high-quality customer service that aligns with your brand and business policies.

​
Why Guidance Matters

You AI agent needs clear instructions to deliver the customer experience you want. Guidance helps you: Maintain Service Quality - Define exactly how your AI should handle different situations, ensuring every customer interaction meets your standards. Enforce Business Rules - Implement your company policies, compliance requirements, and service protocols automatically across all conversations. Provide Context-Aware Responses - Create different behaviors for different customer segments, channels, or scenarios - all from a single AI instance. Empower Your AI with Tools - Control which actions and integrations your AI can use in each situation, balancing automation with safety. Scale Expertise - Codify your best support practices so every customer gets expert-level assistance, even as you grow.

​
What Guidance Controls

Each guidance rule defines a specific behavior or instruction set for your AI. When a customer interacts with your AI, botBrains evaluates all active guidance rules and applies the relevant ones to shape the response.

​
Core Components

Name - A descriptive identifier for the guidance rule (e.g., “Refund Policy for Premium Users”, “Technical Troubleshooting Steps”) Instructions - The specific behavior, rules, or information you want your AI to follow. Written in natural language, these instructions tell your AI how to respond, what tone to use, what information to include, and how to handle edge cases. Active Status - Whether the guidance is live (active) or saved as a draft for future use Allowed Tools - Which actions and integrations the AI can use when this guidance applies (e.g., knowledge search, data lookups, external API calls) Audience - Optional targeting rules that determine when this guidance applies based on customer attributes, channels, or conversation context

​
How Guidance Works

​
Automatic Tool Detection

When writing guidance instructions, you can reference tools using inline code formatting (e.g., `search_knowledge`). botBrains automatically detects these references and enables the mentioned tools for this guidance, making it easy to give your AI the right capabilities for each scenario.

​
Priority and Ordering

Guidance rules are applied in the order you define. You can drag and drop rules to reorder them, which is useful when you have overlapping scenarios where priority matters.

​
Live vs. Draft

  • Live guidance is active and influences your AI’s behavior in customer conversations
  • Draft guidance is saved but inactive - useful for preparing new rules before deployment

​
Audience Targeting

Use audience rules to make guidance conditional:
  • Apply different policies based on customer type (free vs. premium users)
  • Customize responses by channel (website vs. Slack vs. Zendesk)
  • Adjust behavior based on conversation context or customer attributes

​
Practical Examples

​
Basic Guidance: Greeting Policy

Name: Welcome Message for New Visitors Instructions: 
When a customer starts a conversation, greet them warmly and ask how you can help.
Keep the greeting brief and friendly. Mention that you're here to provide instant
support and can help with account questions, technical issues, or product information.
Allowed Tools: None (just conversational behavior)

​
Intermediate Guidance: Refund Handling

Name: Process Refund Requests Instructions: 
When a customer requests a refund:

1. Look up their order using `search_orders` to verify purchase details
2. Check if the order is within our 30-day refund window
3. For eligible refunds:
   - Explain that we'll process the refund within 5-7 business days
   - Use `create_refund` to initiate the refund
   - Provide the refund confirmation number
4. For ineligible refunds:
   - Politely explain the 30-day policy
   - Offer alternative solutions (store credit, exchange, or escalation to manager)

Always be empathetic and professional, even when denying requests.
Allowed Tools: search_orders, create_refund Audience: Customers with at least one completed order

​
Advanced Guidance: Technical Support Triage

Name: Engineering Escalation for Critical Issues Instructions: 
When a customer reports a critical technical issue (site down, data loss, security concern):

1. Immediately acknowledge the severity and express urgency in addressing it
2. Gather essential details: what they were doing, error messages, when it started
3. Search the knowledge base using `search_knowledge` for known issues
4. If it's a known issue with a workaround, provide the solution and confirm it works
5. If unknown or unresolved:
   - Use `create_ticket` with priority set to "Critical" and assign to "Engineering"
   - Provide the ticket number and set expectation for response time (within 1 hour)
   - Offer to notify them when updates are available

Do not attempt to troubleshoot complex database, security, or infrastructure issues
yourself - always escalate to engineering immediately.
Allowed Tools: search_knowledge, create_ticket, send_notification Audience: All channels, high priority

​
Audience-Specific Guidance

Name: VIP Customer White-Glove Service Instructions: 
You are assisting a VIP customer who receives premium support. Provide exceptional service:

- Address them by name if available
- Prioritize their requests over standard workflow
- Offer proactive solutions and alternatives
- If you cannot fully resolve their issue, immediately escalate to the VIP support team
- Follow up to ensure complete satisfaction

Tone should be professional, attentive, and highly personalized.
Allowed Tools: search_knowledge, search_orders, create_priority_ticket, assign_to_vip_team Audience: Customers where customer_tier = "VIP" or subscription_plan = "Enterprise"

​
Best Practices

​
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.

​
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.

​
Reference Tools Inline

Mention tools naturally in your instructions using inline code formatting: `tool_name`. This makes instructions readable and automatically configures tool access.

​
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.

​
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.

​
Review and Refine

Monitor conversations to see how guidance performs in practice. Update instructions based on real customer interactions to continuously improve quality.

​
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.

​
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.

​
Managing Guidance in Profiles

Guidance is part of your AI’s profile, 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 profile 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.

​
Common Use Cases

Customer Service Policies - Encode return policies, warranty terms, service level agreements, and other business rules Escalation Rules - Define when and how to hand off conversations to human agents Troubleshooting Workflows - Guide customers through diagnostic steps for technical issues Compliance Requirements - Ensure AI responses follow regulatory requirements (GDPR, HIPAA, financial regulations) Brand Voice and Tone - Specify communication style, terminology to use or avoid, and personality traits Multi-Product Support - Create different guidance for different product lines or services Channel-Specific Behavior - Adjust responses based on whether customers are on web chat, email, Slack, or other channels Seasonal or Promotional Guidance - Temporarily add guidance for sales events, product launches, or seasonal support needs

​
Next Steps

Now that you understand guidance, explore related concepts:
  • Actions - Learn about the tools and integrations you can enable in guidance
  • Audiences - Create customer segments for targeted guidance
  • Instruct AI Agent - Complete guide to training your AI
  • Deployments - Manage and deploy profile versions safely