Skip to main content

​
Actions

Actions transform your AI from a passive question-answering system into an active assistant that can perform tasks, gather information, and interact with external systems. By configuring actions, you enable your AI to do more than just chat - it can search the web, escalate to humans, query databases, and integrate with custom tools.

​
Why Actions Matter

Without actions AI agents are limited to generating text based on their training and knowledge base. Actions unlock:
  • Real-time information: Search the web or fetch live data instead of relying on static knowledge
  • Task automation: Execute workflows, update systems, or trigger integrations
  • Human collaboration: Seamlessly hand off complex issues to support teams
  • Custom capabilities: Connect to your own APIs and services via MCP servers

​
Types of Actions

botBrains supports several categories of actions to power you AI agent.

​
Built-in Tools

These pre-configured tools are ready to use out of the box:

​
Knowledge Tools

Query your organization’s data to provide accurate, context-aware responses.

​
Search Tables

Search Tables allow your AI to query structured data you’ve uploaded to botBrains. Unlike MCP servers, Search Tables store data directly in the platform and are ideal for tabular data that needs to be searchable by the AI. What are Search Tables:
  • Structured data (CSV, JSON, or JSONL files) uploaded to botBrains
  • Configurable schema with searchable fields
  • Support for filtering, ranges, and multi-select queries
  • Data is stored and managed within the botBrains platform
Ideal for searching time based data, or large data in tabular format. Learn more about Search Tables here. Examples:
  • Product catalogs with pricing and inventory
  • Customer order histories
  • Order status databases
  • FAQ databases with structured Q&A pairs
When to use Search Tables:
  • Frequently updated data that changes too often for static knowledge
  • Tabular data with specific fields you want the AI to filter and search
  • Data that needs precise field-based queries (e.g., “find orders over $100”)
  • Large datasets that would be inefficient as static documents
Setup:
  1. Navigate to your project’s Tables section
  2. Create a new table and upload your data (CSV, JSON, or JSONL)
  3. Configure the schema: set data types and search types for each field
  4. Go to your profile’s Tools settings
  5. Add the search table to your profile’s tools
  6. The AI can now query this data at runtime
Search tables are ideal for data that lives in botBrains and needs to be queryable with structured filters. For data that lives in external systems, use MCP Servers instead.

​
MCP Servers (3rd Party Systems)

The Model Context Protocol (MCP) allows you to connect external systems and 3rd party services to your AI. Unlike Search Tables which store data in botBrains, MCP servers connect to data and functionality that lives in your existing systems. What are MCP Servers:
  • External services accessed via the Model Context Protocol
  • Data and actions remain in the 3rd party system (not stored in botBrains)
  • Can expose multiple tools per server
  • Support both read and write operations
  • Examples: Salesforce, HubSpot, Stripe, Shopify, Zapier, custom APIs
Common use cases:
  • CRM integrations - Query and update records in Salesforce, HubSpot
  • Ticketing systems - Create and manage tickets in Jira, Zendesk
  • Payment platforms - Check order status, process refunds in Stripe, PayPal
  • E-commerce platforms - Query inventory, update orders in Shopify, Square
  • Automation platforms - Trigger workflows in Zapier, Make
  • Internal APIs - Connect to your own custom services and databases
  • Custom business logic - Execute company-specific operations
When to use MCP Servers:
  • Data lives in an external system (CRM, ticketing, payment platform)
  • You need to execute actions in 3rd party services
  • Data is too sensitive to upload to botBrains
  • You want real-time access to data in its source system
  • The external system already has an API you can wrap with MCP
Configuration:
  1. Navigate to your profile’s MCP Servers tab
  2. Choose a pre-built integration or add a custom server URL
  3. Provide authentication credentials and headers
  4. Test the connection to discover available tools
  5. Configure which tools are enabled and set approval requirements
  6. Tools from the MCP server are now available to your AI
MCP servers require a compatible endpoint that implements the Model Context Protocol specification. botBrains provides pre-built integrations for popular platforms like Salesforce, Stripe, and HubSpot.

​
Search Tables vs MCP Servers

AspectSearch TablesMCP Servers
Data LocationStored in botBrainsStays in external system
Use CaseStructured data queriesExternal system integration
SetupUpload CSV/JSON filesConnect via URL + auth
ExamplesProduct catalogs, order historiesSalesforce, Stripe, HubSpot
Best ForData you can uploadData that must stay external
FreshnessOn manual uploadReal-time
ActionsRead-only queriesRead and write operations
We use Search Tables when the data can be uploaded and managed within botBrains, and doesn’t change frequently. For most data, we strongly suggest people use their own endpoints.

​
Trigger-Based Actions

Triggers execute automated actions when specific conditions are met, without requiring AI decision-making. Available trigger actions:

Block

Prevent conversations from continuing when criteria match

Assign Label

Automatically tag conversations, users, or messages

Unassign Label

Remove labels based on conditions
Configuration: Triggers are configured in Settings under “Triggers”. You define:
  • When: The event that fires the trigger (e.g., “User Message Received”)
  • Audience: Conditions that must be met (using audience builder)
  • Then: Actions to execute
Example trigger: 
When: User Message Received
Audience: User has label "spam"
Then: Block conversation
Triggers are processed before the AI responds, making them ideal for security, moderation, and routing logic.

​
Configuring Actions

​
Enabling Built-in Tools

  1. Navigate to your profile in the botBrains platform
  2. Go to the Tools tab
  3. Toggle the desired tools under “General Tools”
  4. Configure tool-specific parameters if needed
  5. Save your profile

​
Adding Custom MCP Servers

  1. Go to your profile’s MCP Servers section
  2. Click “Add Server”
  3. Enter the server URL and any required authentication headers
  4. Test the connection to verify it’s working
  5. Import tools from the server
  6. Configure tool approval settings:
    • Always allowed: AI can use without approval
    • Require approval: User must confirm before execution
    • Disabled: Tool is not available

​
Setting Up Triggers

  1. Navigate to Settings > Triggers
  2. Click “Create Trigger”
  3. Name your trigger and define the conditions:
    • Select the trigger event
    • Use the audience builder to specify criteria
  4. Add one or more actions to execute
  5. Enable the trigger and save

​
Action Approval Flow

For sensitive or critical actions, you can require user approval before execution.

​
How it works:

  1. AI determines an action is needed
  2. AI presents the action to the user with an explanation
  3. User approves or rejects the action
  4. If approved, the action executes and results are returned to the AI
  5. AI continues the conversation with the action’s results

​
Configuring approval:

For MCP server tools, set the approval requirement in the tool configuration:
  • Tools marked “with approval” will ask for user confirmation
  • Tools marked “always” execute immediately
  • Tools marked “disabled” are not available to the AI
Only require approval for actions that modify data or have significant consequences. Requiring approval for read-only actions degrades user experience.

​
Best Practices

​
When to Use Actions

  • Good Use Cases
  • Poor Use Cases
  • Searching for real-time information
  • Querying frequently updated data
  • Creating support tickets or handoffs
  • Executing well-defined workflows
  • Integrating with existing tools

​
Security Considerations

  • Only grant access to tools the AI genuinely needs
  • Require approval for actions that modify data
  • Use triggers for security and moderation rules
  • Regularly audit which tools are enabled
  • Validate MCP server connections are secure

​
Performance Tips

  • Keep tool responses concise and structured
  • Cache frequently accessed data in search tables
  • Use triggers instead of tool-based logic for simple rules
  • Monitor tool usage and response times
  • Disable unused tools to reduce decision overhead

​
Practical Examples

​
Example 1: E-commerce Support Bot

Scenario: Customer asking about order status Actions configured:
  • Search Table: Order database
  • Offer Handoff: For complex shipping issues
  • Trigger: Auto-label conversations mentioning “refund”
Workflow:
  1. User asks “Where is my order #12345?”
  2. AI uses order database search table to find order status
  3. If order is delayed, AI offers handoff to support team
  4. Trigger automatically labels conversation with “order-status”

​
Example 2: Technical Documentation Assistant

Scenario: Developer looking for API information Actions configured:
  • Web Search: For community discussions
  • Fetch Web Pages: To read latest documentation
  • Search Table: API endpoint reference
Workflow:
  1. User asks “How do I authenticate with the API?”
  2. AI searches API reference table for authentication endpoints
  3. If latest changes exist, AI fetches current documentation page
  4. AI provides comprehensive answer with code examples

​
Example 3: Content Moderation

Scenario: Blocking spam and inappropriate content Actions configured:
  • Trigger: Block conversations from users labeled “spam”
  • Trigger: Auto-label messages with profanity as “flagged”
  • Escalate to Human: For severe policy violations
Workflow:
  1. User with “spam” label sends message
  2. Trigger immediately blocks the conversation
  3. If message contains profanity, separate trigger labels it “flagged”
  4. Human moderators review flagged conversations
  • Guidance - Configure AI behavior and instructions
  • Knowledge - Manage your AI’s knowledge base
  • Audiences - Define user segments for triggers
  • Triggers - Set up automated security and routing rules
  • Escalations - Configure human handoff workflows