bolna

End-to-end open-source voice agents platform: Quickly build voice firsts conversational assistants through a json.

Discord | Hosted Docs | Website

[!NOTE] We are actively looking for maintainers.

Introduction

Bolna is the end-to-end open source production ready framework for quickly building LLM based voice driven conversational applications.

Demo

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

What is this repository?

This repository contains the entire orchestration platform to build voice AI applications. It technically orchestrates voice conversations using combination of different ASR+LLM+TTS providers and models over websockets.

Components

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

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

Development philosophy

Any integration, enhancement or feature initially lands on this open source package since it forms the backbone of our Hosted APIs and dashboard
Post that we expose APIs or make changes to existing APIs as required for the same
Thirdly, we push it to the UI dashboard

graph LR;
    A[Bolna open source] -->B[Hosted APIs];
    B[Hosted APIs] --> C[Hosted Playground]

Supported providers and models

Initiating a phone call using telephony providers like Twilio, Plivo, Exotel (coming soon), Vonage (coming soon) etc.
Transcribing the conversations using Deepgram, Azure etc.
Using LLMs like OpenAI, DeepSeek, Llama, Cohere, Mistral, etc to handle conversations
Synthesizing LLM responses back to telephony using AWS Polly, ElevenLabs, Deepgram, OpenAI, Azure, Cartesia, Smallest, Maya etc.

Refer to the docs for a deepdive into all supported providers.

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:

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
Bolna server: for creating and handling agents
ngrok: for tunneling. One will need to add the authtoken to ngrok-config.yml
redis: for persisting agents & prompt data

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.

Manual Setup

Alternatively, you can manually build and run the services:

Make sure you have Docker with Docker Compose V2 installed

Enable BuildKit for faster builds:

export DOCKER_BUILDKIT=1
export COMPOSE_DOCKER_CLI_BUILD=1

Build the images:
```
docker compose build
```
Run the services:
```
docker compose up -d
```

To run specific services only:

docker compose up -d bolna-app twilio-app
# or
docker compose up -d bolna-app plivo-app

Once the docker containers are up, you can now start to create your agents and instruct them to initiate calls.

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.

Using your own providers

You can populate the .env file to use your own keys for providers.

ASR Providers

These are the current supported ASRs Providers:

Provider	Environment variable to be added in `.env` file
Deepgram	`DEEPGRAM_AUTH_TOKEN`

LLM Providers

Bolna uses LiteLLM package to support multiple LLM integrations.

These are the current supported LLM Provider Family: https://github.com/bolna-ai/bolna/blob/10fa26e5985d342eedb5a8985642f12f1cf92a4b/bolna/providers.py#L30-L47

For LiteLLM based LLMs, add either of the following to the .env file depending on your use-case:

LITELLM_MODEL_API_KEY: API Key of the LLM
LITELLM_MODEL_API_BASE: URL of the hosted LLM
LITELLM_MODEL_API_VERSION: API VERSION for LLMs like Azure

For LLMs hosted via VLLM, add the following to the .env file:
VLLM_SERVER_BASE_URL: URL of the hosted LLM using VLLM

TTS Providers

These are the current supported TTS Providers: https://github.com/bolna-ai/bolna/blob/c8a0d1428793d4df29133119e354bc2f85a7ca76/bolna/providers.py#L7-L14

Provider	Environment variable to be added in `.env` file
AWS Polly	Accessed from system wide credentials via ~/.aws
Elevenlabs	`ELEVENLABS_API_KEY`
OpenAI	`OPENAI_API_KEY`
Deepgram	`DEEPGRAM_AUTH_TOKEN`
Cartesia	`CARTESIA_API_KEY`
Smallest	`SMALLEST_API_KEY`
Maya	`MAYA_API_KEY`

Telephony Providers

These are the current supported Telephony Providers:

Provider	Environment variable to be added in `.env` file
Twilio	`TWILIO_ACCOUNT_SID`, `TWILIO_AUTH_TOKEN`, `TWILIO_PHONE_NUMBER`
Plivo	`PLIVO_AUTH_ID`, `PLIVO_AUTH_TOKEN`, `PLIVO_PHONE_NUMBER`

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.

Extending with other Telephony Providers

In case you wish to extend and add some other Telephony like Vonage, Telnyx, etc. following the guidelines below:

Make sure bi-directional streaming is supported by the Telephony provider
Add the telephony-specific input handler file in input_handlers/telephony_providers writing custom functions extending from the telephony.py class
1. This file will mainly contain how different types of event packets are being ingested from the telephony provider
Add telephony-specific output handler file in output_handlers/telephony_providers writing custom functions extending from the telephony.py class
1. This mainly concerns converting audio from the synthesizer class to a supported audio format and streaming it over the websocket provided by the telephony provider
Lastly, you'll have to write a dedicated server like the example twilio_api_server.py provided in local_setup to initiate calls over websockets.

Security Acknowledgments

We would like to thank the following individuals for responsibly disclosing security vulnerabilities and helping us keep this project safe:

@anaskhan54 — June, 2026

Contributing

We love all types of contributions: whether big or small helping in improving this community resource.

There are a number of open issues present which can be good ones to start with
If you have suggestions for enhancements, wish to contribute a simple fix such as correcting a typo, or want to address an apparent bug, please feel free to initiate a new issue or submit a pull request
If you're contemplating a larger change or addition to this repository, be it in terms of its structure or the features, kindly begin by creating a new issue open a new issue :octocat: and outline your proposed changes. This will allow us to engage in a discussion before you dedicate a significant amount of time or effort. Your cooperation and understanding are appreciated

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

bolna-0.10.184.tar.gz (356.6 kB view details)

Uploaded Aug 12, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

bolna-0.10.184-py3-none-any.whl (407.2 kB view details)

Uploaded Aug 12, 2026 Python 3

File details

Details for the file bolna-0.10.184.tar.gz.

File metadata

Download URL: bolna-0.10.184.tar.gz
Upload date: Aug 12, 2026
Size: 356.6 kB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for bolna-0.10.184.tar.gz
Algorithm	Hash digest
SHA256	`c5691d9def15558c62a1642401196ecd534f5384a652bf91794fe6c80fd4a2de`
MD5	`48c718c83c80aaf6509de72b80d55e2c`
BLAKE2b-256	`3c05285e01d8e417a54f44bb5eec8c531416360540949e0a5a86a6d4a7fe8234`

See more details on using hashes here.

Provenance

The following attestation bundles were made for bolna-0.10.184.tar.gz:

Publisher: publish.yml on bolna-ai/bolna

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: bolna-0.10.184.tar.gz
- Subject digest: c5691d9def15558c62a1642401196ecd534f5384a652bf91794fe6c80fd4a2de
- Sigstore transparency entry: 2431969535
- Sigstore integration time: Aug 12, 2026
Source repository:
- Permalink: bolna-ai/bolna@a815f755bda5dca348293bda65260d282b55b56a
- Branch / Tag: refs/heads/master
- Owner: https://github.com/bolna-ai
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: publish.yml@a815f755bda5dca348293bda65260d282b55b56a
- Trigger Event: push