Local example setup [will be moved to a different repository]

A basic local setup includes usage of Twilio or Plivo for telephony. We have dockerized the setup in local_setup/. One will need to populate an environment .env file from .env.sample.

The setup consists of four containers:

1. Telephony web server: Choosing Twilio: for initiating the calls one will need to set up a Twilio account Choosing Plivo: for initiating the calls one will need to set up a Plivo account 2. Bolna server: for creating and handling agents 3. ngrok: for tunneling. One will need to add the authtoken to ngrok-config.yml 4. redis: for persisting agents & prompt data

Manual Setup

Alternatively, you can manually build and run the services:

1. Make sure you have Docker with Docker Compose V2 installed 2. Enable BuildKit for faster builds:

   export DOCKER_BUILDKIT=1
   export COMPOSE_DOCKER_CLI_BUILD=1
   

   docker compose build
   

   docker compose up -d
   

To run specific services only:

```bash docker compose up -d bolna-app twilio-app

Quick Start

The easiest way to get started is to use the provided script:

cd local_setup
chmod +x start.sh
./start.sh

This script will check for Docker dependencies, build all services with BuildKit enabled, and start them in detached mode.

Example agents to create, use and start making calls

You may try out different agents from example.bolna.dev.

Programmatic usage (minimal example)

You can also build and run an agent directly in Python without the local telephony setup.

Example script: examples/simple_assistant.py

import asyncio
from bolna.assistant import Assistant
from bolna.models import (
    Transcriber,
    Synthesizer,
    ElevenLabsConfig,
    LlmAgent,
    SimpleLlmAgent,
)


async def main():
    assistant = Assistant(name="demo_agent")

    # Configure audio input (ASR)
    transcriber = Transcriber(provider="deepgram", model="nova-2", stream=True, language="en")

    # Configure LLM
    llm_agent = LlmAgent(
        agent_type="simple_llm_agent",
        agent_flow_type="streaming",
        llm_config=SimpleLlmAgent(
            provider="openai",
            model="gpt-4o-mini",
            temperature=0.3,
        ),
    )

    # Configure audio output (TTS)
    synthesizer = Synthesizer(
        provider="elevenlabs",
        provider_config=ElevenLabsConfig(
            voice="George", voice_id="JBFqnCBsd6RMkjVDRZzb", model="eleven_turbo_v2_5"
        ),
        stream=True,
        audio_format="wav",
    )

    # Build a single coherent pipeline: transcriber -> llm -> synthesizer
    assistant.add_task(
        task_type="conversation",
        llm_agent=llm_agent,
        transcriber=transcriber,
        synthesizer=synthesizer,
        enable_textual_input=False,
    )

    # Stream results
    async for chunk in assistant.execute():
        print(chunk)


if __name__ == "__main__":
    asyncio.run(main())

How to run:

export OPENAI_API_KEY=...
export DEEPGRAM_AUTH_TOKEN=...
export ELEVENLABS_API_KEY=...
python examples/simple_assistant.py

This demonstrates orchestration and streaming output. For telephony, use the services in local_setup/.

Note: For REST-based usage (Agent CRUD over HTTP), see API.md in the repo root.

Expected output shape: assistant.execute() is an async generator yielding per-task result dicts (event-like chunks). The exact keys depend on configured tools/providers; treat it as a stream and process incrementally.

Text-only pipeline example

If you want a text-only flow (no transcriber/synthesizer), you can enable a text-only pipeline:

Example script: examples/text_only_assistant.py

import asyncio
from bolna.assistant import Assistant
from bolna.models import LlmAgent, SimpleLlmAgent


async def main():
    assistant = Assistant(name="text_only_agent")

    llm_agent = LlmAgent(
        agent_type="simple_llm_agent",
        agent_flow_type="streaming",
        llm_config=SimpleLlmAgent(
            provider="openai",
            model="gpt-4o-mini",
            temperature=0.2,
        ),
    )

    # No transcriber/synthesizer; enable a text-only pipeline
    assistant.add_task(
        task_type="conversation",
        llm_agent=llm_agent,
        enable_textual_input=True,
    )

    async for chunk in assistant.execute():
        print(chunk)


if __name__ == "__main__":
    asyncio.run(main())

How to run (text-only):

export OPENAI_API_KEY=...
python examples/text_only_assistant.py

Expected output shape: assistant.execute() yields streaming dicts per task step; fields vary by configuration. Handle chunk-by-chunk.

Demo

https://github.com/bolna-ai/bolna/assets/1313096/2237f64f-1c5b-4723-b7e7-d11466e9b226

Open-source v/s Hosted APIs

We have in the past tried to maintain both the open source and the hosted solution (via APIs and a UI dashboard).

We have fluctuated b/w maintaining this repository purely from a point of time crunch and not interest.

Currently, we are continuing to maintain it for the community and improving the adoption of Voice AI.

Though the repository is completely open source, you can connect with us if interested in managed hosted offerings or more customized solutions. <a href="https://calendly.com/bolna/30min"><img alt="Schedule a meeting" src="https://cdn.cookielaw.org/logos/122ecfc3-4694-42f1-863f-2db42d1b1e68/0bcbbcf4-9b83-4684-ba59-bc913c0d5905/c21bea90-f4f1-43d1-8118-8938bbb27a9d/logo.png" /></a>

Components

Bolna helps you create AI Voice Agents which can be instructed to do tasks beginning with:

1. Orchestration platform (this open source repository)
2. Hosted APIs (https://docs.bolna.ai/api-reference/introduction) built on top of this orchestration platform [currently closed source]
3. No-code UI playground at https://platform.bolna.ai/ using the hosted APIs + tailwind CSS [currently closed source]