How bolna-ai/bolna works
Purpose and Entry Points
Bolna is an asynchronous Python orchestration framework for streaming voice and text conversational agents. The public programmatic entry point is bolna/assistant.py, where Assistant is configured with tasks and consumed through the async-generator execute() API. Configuration/data models live in bolna/models.py; runnable examples are examples/simple_assistant.py and examples/text_only_assistant.py.
Task and Conversation Orchestration
Assistant delegates task lifecycle and per-turn coordination to manager-layer components. bolna/agent_manager/task_manager.py organizes configured tasks, while bolna/agent_manager/assistant_manager.py manages assistant-level execution. bolna/agent_manager/interruption_manager.py is a core control boundary for barge-in/interruption behavior, and bolna/agent_manager/voicemail_handler.py supports call-specific terminal handling.
Agent Execution Models
Agent types define what happens after input reaches the conversational core. bolna/agent_types/base_agent.py establishes the shared agent contract; bolna/agent_types/contextual_conversational_agent.py implements context-aware conversational behavior. Graph-driven workflows are represented by bolna/agent_types/graph_agent.py and bolna/agent_types/graph_based_conversational_agent.py, enabling routing/control-flow beyond a linear ASR→LLM→TTS turn. Specialized stages include extraction, knowledge-base, summarization, and webhook agents.
Streaming Media Pipeline
The primary voice path is bidirectional streaming: input audio → transcription → agent/LLM → synthesis → output audio. ASR provider implementations conform to the transcriber abstraction in bolna/transcriber/base_transcriber.py and are selected/managed through bolna/transcriber/transcriber_pool.py. TTS follows the equivalent abstraction and pooling boundary in bolna/synthesizer/base_synthesizer.py and bolna/synthesizer/synthesizer_pool.py. This design allows provider/model switching without coupling orchestration to a specific speech vendor.
LLM and Tool Boundary
LLM requests and streaming responses are abstracted in bolna/llms/llm.py, with LiteLLM-backed multi-provider support in bolna/llms/litellm.py and OpenAI-specific handling in bolna/llms/openai_llm.py. Message schemas and tool-call accumulation are isolated in bolna/llms/message_models.py and bolna/llms/tool_call_accumulator.py. Function/tool invocation support is coordinated through bolna/helpers/function_calling_helpers.py, separating model output from application-side execution.
Transport and Telephony Adapters
Input and output handler layers isolate runtime transport from the agent pipeline. Generic paths are bolna/input_handlers/default.py and bolna/output_handlers/default.py; telephony paths are bolna/input_handlers/telephony.py and bolna/output_handlers/telephony.py. Provider adapters, such as bolna/input_handlers/telephony_providers/twilio.py and bolna/output_handlers/telephony_providers/twilio.py, translate vendor WebSocket events/audio formats at the system boundary.
State, Deployment, and External Services
Conversation state and event metadata are handled by bolna/helpers/conversation_history.py and bolna/helpers/mark_event_meta_data.py; cache abstractions begin at bolna/memory/cache/base_cache.py. The local deployment is Docker Compose-based in local_setup/docker-compose.yml, running Bolna, a Twilio/Plivo telephony server, ngrok, and Redis. External dependencies include telephony providers, ASR/TTS vendors, LLM APIs or self-hosted VLLM endpoints, and optional RAG services via bolna/helpers/rag_service_client.py.
Main entry points: contextual_conversational_agent.py Contextual conversational agent · assistant_manager.py Assistant manager · base_agent.py Base agent · transcriber_pool.py Transcriber pool
Components 22
Public API
- Assistant · Configures tasks and streams execute() results.
bolna/assistant.py - Configuration models
bolna/models.py
Orchestration
- Assistant manager
bolna/agent_manager/assistant_manager.py - Task manager
bolna/agent_manager/task_manager.py - Interruption manager
bolna/agent_manager/interruption_manager.py - Voicemail handler
bolna/agent_manager/voicemail_handler.py
Agent execution
- Base agent
bolna/agent_types/base_agent.py - Contextual conversational agent
bolna/agent_types/contextual_conversational_agent.py - Graph workflow agents · Supports non-linear conversational routing.
bolna/agent_types/graph_based_conversational_agent.py - LLM abstraction
bolna/llms/llm.py - Function calling · Executes application-side tools from model output.
bolna/helpers/function_calling_helpers.py
Streaming media
- Transcriber pool
bolna/transcriber/transcriber_pool.py - Base transcriber
bolna/transcriber/base_transcriber.py - Synthesizer pool
bolna/synthesizer/synthesizer_pool.py - Base synthesizer
bolna/synthesizer/base_synthesizer.py
Transport adapters
- Input handlers
bolna/input_handlers/default.py - Twilio input adapter
bolna/input_handlers/telephony_providers/twilio.py - Output handlers
bolna/output_handlers/default.py - Twilio output adapter
bolna/output_handlers/telephony_providers/twilio.py
State & external services
- Conversation history
bolna/helpers/conversation_history.py - Cache abstraction
bolna/memory/cache/base_cache.py - RAG service client
bolna/helpers/rag_service_client.py
Connections 23
- Configuration models → Assistant: configures
- Assistant → Assistant manager: delegates execution
- Assistant manager → Task manager: coordinates tasks
- Task manager → Base agent: instantiates
- Base agent → Contextual conversational agent: implemented by
- Base agent → Graph workflow agents: implemented by
- Input handlers → Transcriber pool: audio input
- Twilio input adapter → Input handlers: vendor events
- Transcriber pool → Base transcriber: selects provider
- Transcriber pool → Contextual conversational agent: transcript
- Contextual conversational agent → LLM abstraction: streams prompts
- Graph workflow agents → LLM abstraction: uses
- LLM abstraction → Function calling: tool calls
- Function calling → Contextual conversational agent: tool results
- Contextual conversational agent → Synthesizer pool: response text
- Synthesizer pool → Base synthesizer: selects provider
- Synthesizer pool → Output handlers: synthesized audio
- Output handlers → Twilio output adapter: telephony audio
- Assistant manager → Interruption manager: handles barge-in
- Assistant manager → Voicemail handler: handles terminal calls
- Contextual conversational agent → Conversation history: reads and updates
- Contextual conversational agent → Cache abstraction: uses
- Contextual conversational agent → RAG service client: retrieves knowledge