Core Concepts

This page explains the building blocks of Bonsai and how they fit together. Understanding these concepts will help you design better conversational experiences.

Projects — The Top Level

A project is the container for everything. It represents one complete conversational AI experience. All the design resources (stages, agents, classifiers, etc.) live inside a project, and all conversations happen within a project.

Think of a project as "the bot" — if you have a customer service bot and a sales bot, those would be two separate projects.

Stages — Conversation Steps

Stages are the heart of conversation design. Each stage represents a distinct phase in the conversation, like:

• A greeting stage where the AI introduces itself
• A collect information stage where the AI asks for the user's details
• A troubleshooting stage that walks the user through fixing a problem
• A farewell stage that wraps things up

Each stage has its own:

• Prompt — Instructions that tell the AI what to do and how to behave at this point
• Agent — Which personality and voice to use
• Actions — What the AI can do when triggered by user input
• Variables — Data being tracked at this step

Conversations move between stages through actions (specifically, the "go to stage" effect).

Agents — Personality & Voice

A agent defines who the AI is in the conversation. It includes:

• A personality prompt that describes tone, style, and behavioral rules (e.g., "Be friendly and professional, avoid jargon")
• Voice settings (optional) that control which synthetic voice is used for spoken output

You can have multiple agents in a project (e.g., a casual helper and a formal escalation agent) and assign different agents to different stages.

Actions & Effects — Making Things Happen

Actions are how the AI does more than just talk. An action is triggered when a user says something that matches it (via a classifier), or by other events. Each action contains a list of effects — the actual things that happen. Effects are listed here in the order they execute:

Effect	What It Does
Call tool	Invoke a tool (Smart Function, Webhook, or Script)
Modify variables	Set, reset, or update conversation data
Modify user profile	Update the end user's stored profile data
Modify user input	Change what the AI "sees" as the user's message
Generate response	Produce an AI reply (or a fixed, pre-written message)
End conversation	Gracefully close the conversation
Abort conversation	Immediately terminate the conversation
Go to stage	Move the conversation to a different stage

Effects run in order within an action. You can chain them — for example: call a webhook tool to check an order status → store the result in a variable → generate a response that includes the status.

Classifiers — Understanding Intent

A classifier is an AI-powered component that looks at what the user said and decides which action (if any) should be triggered. Behind the scenes, it sends the user's message plus a list of available actions to a language model, which picks the best match.

Each stage has a default classifier. Classifiers are also used in global actions (a separate project-level classifier routes cross-stage intents) and in guardrails (a dedicated classifier evaluates safety rules on every turn). You can create specialized classifiers for specific tasks and assign them where needed.

Context Transformers — Processing Each Turn

Context transformers run an LLM prompt on every conversation turn and can do more than just extract data. Common uses include:

• Data extraction — Pull structured values out of what the user says. For example: customerName → "Sarah", orderNumber → "12345".
• Whispers — Inject bracketed comments like [customer sounds frustrated] directly into the user's utterance, giving the AI subtle cues without the user seeing them.
• Prompt additions — Generate a chunk of text that gets appended to the stage prompt, letting the transformer dynamically shape what context the AI sees.
• Helper variables — Compute and set variables (e.g., detected intent score, sentiment) that conditions and scripts can use to steer the flow.

Extracted values are stored in the stage's variables and are available in prompts, conditions, and scripts.

Knowledge Base — FAQ Content

The knowledge base stores question-and-answer pairs organized into categories. When knowledge is enabled on a stage, the AI can draw on this content to give accurate, consistent answers to common questions — without you having to write specific actions for each one.

Tools — Callable Functions

Tools are callable functions that can be invoked during a conversation via action effects or directly by client applications. There are three types:

• Smart Functions — Use a language model to process input and produce output (translation, summarization, image analysis, etc.).
• Webhooks — Send HTTP requests to external APIs and return the response.
• Scripts — Run custom JavaScript in a secure sandbox for data processing or complex logic.

Global Actions — Shared Behaviors

Global actions are actions defined once at the project level and shared across multiple stages. They're perfect for behaviors that should work the same way everywhere, like:

• "I need help" → Escalate to a human
• "Cancel" → End the conversation
• "Switch to Spanish" → Change the language

There are also special actions (like Moderation Blocked) that are triggered automatically by the system. You configure their effects but not their triggers.

Guardrails — Safety Enforcement

Guardrails are project-wide safety rules that run on every user input turn using a dedicated project-level classifier. Unlike global actions (which must be enabled per stage), guardrails are always active and can't be bypassed by individual stage configuration.

Use guardrails for zero-tolerance rules: blocking harmful language, refusing off-topic requests, or enforcing usage policies that should apply everywhere.

Global Memory — Constants and User Profile

Global Memory is a single, integrated page (Design > Global Memory) that manages two complementary areas:

• Constants — Project-wide key-value pairs that never change per conversation (company name, support hours, policy limits, plan pricing). Accessed in both prompts and scripts as consts.key (e.g. {{consts.key}} in templates). Manage them on the Constants tab.
• User Profile schema — The custom fields stored on each end user's profile. Declaring fields here enables autocomplete in the prompt editor and documents your data model for the team. Accessed as {{userProfile.fieldName}} in prompts and set at runtime via modify_user_profile effects or scripts. Manage the schema on the User Profile tab.

Moderation — Content Safety

Moderation lets you enable automatic content safety checks on user messages. When enabled, each user message is evaluated by a moderation model and flagged if it matches any blocked category.

Configure moderation in Design > Guardrails (Moderation tab) by selecting an LLM provider (OpenAI or Mistral) and choosing which categories to block. To control what happens when a message is blocked, set up the Moderation Blocked special action in Design > Global Actions.

Providers — External AI Services

Providers are connections to external services that power the AI features:

Type	Purpose	Examples
LLM	Text generation, classification, extraction	OpenAI, Anthropic, Google Gemini
TTS	Converting text to speech	ElevenLabs, OpenAI TTS, Azure, Deepgram, Cartesia
ASR	Converting speech to text	Azure, Deepgram, ElevenLabs, AssemblyAI, Speechmatics
Storage	Saving conversation recordings and files	Amazon S3, Azure Blob, Google Cloud Storage

Providers are shared across all projects, so you only need to set up your API key once.

How It All Fits Together

Project
├── Stages (conversation steps)
│   ├── Agent (personality + voice)
│   ├── LLM Provider (for generating AI responses)
│   ├── Classifier (for understanding user intent)
│   ├── Context Transformers (for extracting data)
│   ├── Actions → Effects (behaviors)
│   ├── Variables (data tracked in this step)
│   ├── Global Actions (shared behaviors)
│   ├── Guardrails (safety rules)
│   └── Knowledge tags (FAQ content to include)
│
├── Agents (reusable across stages)
├── Classifiers (reusable across stages)
├── Context Transformers (reusable across stages)
├── Tools (AI-powered functions)
├── Knowledge Categories → Items (FAQ)
├── Global Actions (shared behaviors)
├── Guardrails (safety rules + moderation config)
├── Global Constants (project-wide values)
├── Global Memory (user profile schema)
├── Moderation (content safety)
└── API Keys (for client apps to connect)

Optimistic Locking

When multiple people are editing the same project in the console, Bonsai uses version numbers to prevent accidental overwrites. Every time you save a change, the version number increases. If someone else saved a change while you were editing, you'll be notified so you can refresh and try again.

Next Steps

• Navigating the Console — Learn your way around the interface.
• Design Overview — Start building your conversation.