{"id":13584814,"url":"https://github.com/bolna-ai/bolna","last_synced_at":"2026-05-26T09:01:39.239Z","repository":{"id":283254082,"uuid":"846923721","full_name":"bolna-ai/bolna","owner":"bolna-ai","description":"Conversational voice AI agents","archived":false,"fork":false,"pushed_at":"2026-05-20T06:36:41.000Z","size":46201,"stargazers_count":648,"open_issues_count":59,"forks_count":292,"subscribers_count":14,"default_branch":"master","last_synced_at":"2026-05-20T08:52:19.259Z","etag":null,"topics":["agentic-ai","agents","ai-agents","cartesia","conversational-ai","deepgram","deepseek","deepseek-chat","elevenlabs","function-calling","gpt-4","llama","openai","plivo","twilio","voice-agents","voice-ai-agents","voice-assistant","whisper"],"latest_commit_sha":null,"homepage":"https://www.bolna.ai","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bolna-ai.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":null,"patreon":null,"open_collective":null,"ko_fi":null,"tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"lfx_crowdfunding":null,"polar":null,"buy_me_a_coffee":null,"custom":"https://buy.stripe.com/7sIaIyg4m19f31SdQW"}},"created_at":"2024-08-24T10:40:26.000Z","updated_at":"2026-05-20T06:36:34.000Z","dependencies_parsed_at":"2026-03-31T04:02:15.138Z","dependency_job_id":null,"html_url":"https://github.com/bolna-ai/bolna","commit_stats":null,"previous_names":["bolna-ai/bolna"],"tags_count":75,"template":false,"template_full_name":null,"purl":"pkg:github/bolna-ai/bolna","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bolna-ai%2Fbolna","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bolna-ai%2Fbolna/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bolna-ai%2Fbolna/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bolna-ai%2Fbolna/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bolna-ai","download_url":"https://codeload.github.com/bolna-ai/bolna/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bolna-ai%2Fbolna/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33462501,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-25T02:24:28.008Z","status":"ssl_error","status_checked_at":"2026-05-25T02:23:23.339Z","response_time":57,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agentic-ai","agents","ai-agents","cartesia","conversational-ai","deepgram","deepseek","deepseek-chat","elevenlabs","function-calling","gpt-4","llama","openai","plivo","twilio","voice-agents","voice-ai-agents","voice-assistant","whisper"],"created_at":"2024-08-01T15:04:32.291Z","updated_at":"2026-05-26T09:01:39.179Z","avatar_url":"https://github.com/bolna-ai.png","language":"Python","funding_links":["https://buy.stripe.com/7sIaIyg4m19f31SdQW"],"categories":["🗣️ 音声とマルチモーダルエージェント","Python","Frameworks \u0026 Platforms | 框架与平台","Chatbots"],"sub_categories":["自動運転","Comprehensive Frameworks | 综合性框架"],"readme":"\u003ch1 align=\"center\"\u003e\n\u003c/h1\u003e\n\u003cp align=\"center\"\u003e\n  \u003cp align=\"center\"\u003e\u003cb\u003eEnd-to-end open-source voice agents platform\u003c/b\u003e: Quickly build voice firsts conversational assistants through a json. \u003c/p\u003e\n\u003c/p\u003e\n\n\u003ch4 align=\"center\"\u003e\n  \u003ca href=\"https://discord.gg/59kQWGgnm8\"\u003eDiscord\u003c/a\u003e |\n  \u003ca href=\"https://docs.bolna.ai\"\u003eHosted Docs\u003c/a\u003e |\n  \u003ca href=\"https://bolna.ai\"\u003eWebsite\u003c/a\u003e\n\u003c/h4\u003e\n\n\u003ch4 align=\"center\"\u003e\n  \u003ca href=\"https://discord.gg/59kQWGgnm8\"\u003e\n      \u003cimg src=\"https://img.shields.io/static/v1?label=Chat%20on\u0026message=Discord\u0026color=blue\u0026logo=Discord\u0026style=flat-square\" alt=\"Discord\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://github.com/bolna-ai/bolna/blob/main/LICENSE\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/license-MIT-blue.svg\" alt=\"Bolna is released under the MIT license.\" /\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://github.com/bolna-ai/bolna/blob/main/CONTRIBUTING.md\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/PRs-Welcome-brightgreen\" alt=\"PRs welcome!\" /\u003e\n  \u003c/a\u003e\n\u003c/h4\u003e\n\n\u003e [!NOTE]\n\u003e We are actively looking for maintainers.\n\n## Introduction\n\n**[Bolna](https://bolna.ai)** is the end-to-end open source production ready framework for quickly building LLM based voice driven conversational applications.\n\n## Demo\nhttps://github.com/bolna-ai/bolna/assets/1313096/2237f64f-1c5b-4723-b7e7-d11466e9b226\n\n\n## What is this repository?\nThis 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.\n\n\n## Components\nBolna helps you create AI Voice Agents which can be instructed to do tasks beginning with:\n\n1. Orchestration platform (this open source repository)\n2. Hosted APIs (https://docs.bolna.ai/api-reference/introduction) built on top of this orchestration platform [currently closed source]\n3. No-code UI playground at https://platform.bolna.ai/ using the hosted APIs + tailwind CSS [currently closed source]\n\n\n## Development philosophy\n1. Any integration, enhancement or feature initially lands on this open source package since it forms the backbone of our Hosted APIs and dashboard\n2. Post that we expose APIs or make changes to existing APIs as required for the same\n3. Thirdly, we push it to the UI dashboard\n\n```mermaid\ngraph LR;\n    A[Bolna open source] --\u003eB[Hosted APIs];\n    B[Hosted APIs] --\u003e C[Hosted Playground]\n```\n\n## Supported providers and models\n1. Initiating a phone call using telephony providers like `Twilio`, `Plivo`, `Exotel` (coming soon), `Vonage` (coming soon) etc.\n2. Transcribing the conversations using `Deepgram`, `Azure` etc.\n3. Using LLMs like `OpenAI`, `DeepSeek`, `Llama`, `Cohere`, `Mistral`,  etc to handle conversations\n4. Synthesizing LLM responses back to telephony using `AWS Polly`, `ElevenLabs`, `Deepgram`, `OpenAI`, `Azure`, `Cartesia`, `Smallest` etc.\n\n\nRefer to the [docs](https://docs.bolna.ai/providers) for a deepdive into all supported providers.\n\n\n## Local example setup [will be moved to a different repository]\nA basic local setup includes usage of [Twilio](local_setup/telephony_server/twilio_api_server.py) or [Plivo](local_setup/telephony_server/plivo_api_server.py) for telephony. We have dockerized the setup in `local_setup/`. One will need to populate an environment `.env` file from `.env.sample`.\n\nThe setup consists of four containers:\n\n1. Telephony web server:\n   * Choosing Twilio: for initiating the calls one will need to set up a [Twilio account](https://www.twilio.com/docs/usage/tutorials/how-to-use-your-free-trial-account)\n   * Choosing Plivo: for initiating the calls one will need to set up a [Plivo account](https://www.plivo.com/)\n2. Bolna server: for creating and handling agents \n3. `ngrok`: for tunneling. One will need to add the `authtoken` to `ngrok-config.yml`\n4. `redis`: for persisting agents \u0026 prompt data\n\n### Quick Start\n\nThe easiest way to get started is to use the provided script:\n\n```bash\ncd local_setup\nchmod +x start.sh\n./start.sh\n```\n\nThis script will check for Docker dependencies, build all services with BuildKit enabled, and start them in detached mode.\n\n### Manual Setup\n\nAlternatively, you can manually build and run the services:\n\n1. Make sure you have Docker with Docker Compose V2 installed\n2. Enable BuildKit for faster builds:\n   ```bash\n   export DOCKER_BUILDKIT=1\n   export COMPOSE_DOCKER_CLI_BUILD=1\n   ```\n3. Build the images:\n   ```bash\n   docker compose build\n   ```\n4. Run the services:\n   ```bash\n   docker compose up -d\n   ```\n\nTo run specific services only:\n\n```bash\ndocker compose up -d bolna-app twilio-app\n# or\ndocker compose up -d bolna-app plivo-app\n```\n\nOnce the docker containers are up, you can now start to create your agents and instruct them to initiate calls.\n\n\n## Example agents to create, use and start making calls\nYou may try out different agents from [example.bolna.dev](https://examples.bolna.dev).\n\n## Programmatic usage (minimal example)\n\nYou can also build and run an agent directly in Python without the local telephony setup.\n\nExample script: `examples/simple_assistant.py`\n\n```python\nimport asyncio\nfrom bolna.assistant import Assistant\nfrom bolna.models import (\n    Transcriber,\n    Synthesizer,\n    ElevenLabsConfig,\n    LlmAgent,\n    SimpleLlmAgent,\n)\n\n\nasync def main():\n    assistant = Assistant(name=\"demo_agent\")\n\n    # Configure audio input (ASR)\n    transcriber = Transcriber(provider=\"deepgram\", model=\"nova-2\", stream=True, language=\"en\")\n\n    # Configure LLM\n    llm_agent = LlmAgent(\n        agent_type=\"simple_llm_agent\",\n        agent_flow_type=\"streaming\",\n        llm_config=SimpleLlmAgent(\n            provider=\"openai\",\n            model=\"gpt-4o-mini\",\n            temperature=0.3,\n        ),\n    )\n\n    # Configure audio output (TTS)\n    synthesizer = Synthesizer(\n        provider=\"elevenlabs\",\n        provider_config=ElevenLabsConfig(\n            voice=\"George\", voice_id=\"JBFqnCBsd6RMkjVDRZzb\", model=\"eleven_turbo_v2_5\"\n        ),\n        stream=True,\n        audio_format=\"wav\",\n    )\n\n    # Build a single coherent pipeline: transcriber -\u003e llm -\u003e synthesizer\n    assistant.add_task(\n        task_type=\"conversation\",\n        llm_agent=llm_agent,\n        transcriber=transcriber,\n        synthesizer=synthesizer,\n        enable_textual_input=False,\n    )\n\n    # Stream results\n    async for chunk in assistant.execute():\n        print(chunk)\n\n\nif __name__ == \"__main__\":\n    asyncio.run(main())\n```\n\nHow to run:\n\n```bash\nexport OPENAI_API_KEY=...\nexport DEEPGRAM_AUTH_TOKEN=...\nexport ELEVENLABS_API_KEY=...\npython examples/simple_assistant.py\n```\n\nThis demonstrates orchestration and streaming output. For telephony, use the services in `local_setup/`.\n\nNote: For REST-based usage (Agent CRUD over HTTP), see `API.md` in the repo root.\n\nExpected 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.\n\n### Text-only pipeline example\n\nIf you want a text-only flow (no transcriber/synthesizer), you can enable a text-only pipeline:\n\nExample script: `examples/text_only_assistant.py`\n\n```python\nimport asyncio\nfrom bolna.assistant import Assistant\nfrom bolna.models import LlmAgent, SimpleLlmAgent\n\n\nasync def main():\n    assistant = Assistant(name=\"text_only_agent\")\n\n    llm_agent = LlmAgent(\n        agent_type=\"simple_llm_agent\",\n        agent_flow_type=\"streaming\",\n        llm_config=SimpleLlmAgent(\n            provider=\"openai\",\n            model=\"gpt-4o-mini\",\n            temperature=0.2,\n        ),\n    )\n\n    # No transcriber/synthesizer; enable a text-only pipeline\n    assistant.add_task(\n        task_type=\"conversation\",\n        llm_agent=llm_agent,\n        enable_textual_input=True,\n    )\n\n    async for chunk in assistant.execute():\n        print(chunk)\n\n\nif __name__ == \"__main__\":\n    asyncio.run(main())\n```\n\nHow to run (text-only):\n\n```bash\nexport OPENAI_API_KEY=...\npython examples/text_only_assistant.py\n```\n\nExpected output shape: `assistant.execute()` yields streaming dicts per task step; fields vary by configuration. Handle chunk-by-chunk.\n\n\n## Using your own providers\nYou can populate the `.env` file to use your own keys for providers.\n\n\u003cdetails\u003e\n\n\u003csummary\u003eASR Providers\u003c/summary\u003e\u003cbr\u003e\nThese are the current supported ASRs Providers:\n\n| Provider     | Environment variable to be added in `.env` file |\n|--------------|-------------------------------------------------|\n| Deepgram     | `DEEPGRAM_AUTH_TOKEN`                           |\n\n\u003c/details\u003e\n\u0026nbsp;\u003cbr\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eLLM Providers\u003c/summary\u003e\u003cbr\u003e\nBolna uses LiteLLM package to support multiple LLM integrations.\n\nThese are the current supported LLM Provider Family:\nhttps://github.com/bolna-ai/bolna/blob/10fa26e5985d342eedb5a8985642f12f1cf92a4b/bolna/providers.py#L30-L47\n\nFor LiteLLM based LLMs, add either of the following to the `.env` file depending on your use-case:\u003cbr\u003e\u003cbr\u003e\n`LITELLM_MODEL_API_KEY`: API Key of the LLM\u003cbr\u003e\n`LITELLM_MODEL_API_BASE`: URL of the hosted LLM\u003cbr\u003e\n`LITELLM_MODEL_API_VERSION`: API VERSION for LLMs like Azure\n\nFor LLMs hosted via VLLM, add the following to the `.env` file:\u003cbr\u003e\n`VLLM_SERVER_BASE_URL`: URL of the hosted LLM using VLLM\n\n\u003c/details\u003e\n\u0026nbsp;\u003cbr\u003e\n\n\u003cdetails\u003e\n\n\u003csummary\u003eTTS Providers\u003c/summary\u003e\u003cbr\u003e\nThese are the current supported TTS Providers:\nhttps://github.com/bolna-ai/bolna/blob/c8a0d1428793d4df29133119e354bc2f85a7ca76/bolna/providers.py#L7-L14\n\n| Provider   | Environment variable to be added in `.env` file  |\n|------------|--------------------------------------------------|\n| AWS Polly  | Accessed from system wide credentials via ~/.aws |\n| Elevenlabs | `ELEVENLABS_API_KEY`                             |\n| OpenAI     | `OPENAI_API_KEY`                                 |\n| Deepgram   | `DEEPGRAM_AUTH_TOKEN`                            |\n| Cartesia   | `CARTESIA_API_KEY`                            |\n| Smallest   | `SMALLEST_API_KEY`                            |\n\n\u003c/details\u003e\n\u0026nbsp;\u003cbr\u003e\n\n\u003cdetails\u003e\n\n\u003csummary\u003eTelephony Providers\u003c/summary\u003e\u003cbr\u003e\nThese are the current supported Telephony Providers:\n\n| Provider | Environment variable to be added in `.env` file                                                                                                                    |\n|----------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| Twilio   | `TWILIO_ACCOUNT_SID`, `TWILIO_AUTH_TOKEN`, `TWILIO_PHONE_NUMBER`|\n| Plivo    | `PLIVO_AUTH_ID`, `PLIVO_AUTH_TOKEN`, `PLIVO_PHONE_NUMBER`|\n\n\u003c/details\u003e\n\n## Open-source v/s Hosted APIs\n**We have in the past tried to maintain both the open source and the hosted solution (via APIs and a UI dashboard)**.\n\nWe have fluctuated b/w maintaining this repository purely from a point of time crunch and not interest.\n\nCurrently, we are continuing to maintain it for the community and improving the adoption of Voice AI.\n\nThough the repository is completely open source, you can connect with us if interested in managed hosted offerings or more customized solutions.\n\u003ca href=\"https://calendly.com/bolna/30min\"\u003e\u003cimg 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\" /\u003e\u003c/a\u003e\n\n## Extending with other Telephony Providers\nIn case you wish to extend and add some other Telephony like Vonage, Telnyx, etc. following the guidelines below:\n1. Make sure bi-directional streaming is supported by the Telephony provider\n2. Add the telephony-specific input handler file in [input_handlers/telephony_providers](https://github.com/bolna-ai/bolna/tree/master/bolna/input_handlers/telephony_providers) writing custom functions extending from the [telephony.py](https://github.com/bolna-ai/bolna/blob/master/bolna/input_handlers/telephony.py) class\n   1. This file will mainly contain how different types of event packets are being ingested from the telephony provider\n3. Add telephony-specific output handler file in [output_handlers/telephony_providers](https://github.com/bolna-ai/bolna/tree/master/bolna/output_handlers/telephony_providers) writing custom functions extending from the [telephony.py](https://github.com/bolna-ai/bolna/blob/master/bolna/output_handlers/telephony.py) class\n   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\n4. Lastly, you'll have to write a dedicated server like the example [twilio_api_server.py](https://github.com/bolna-ai/bolna/blob/master/local_setup/telephony_server/twilio_api_server.py) provided in [local_setup](https://github.com/bolna-ai/bolna/blob/master/local_setup/telephony_server) to initiate calls over websockets.\n\n\n## Contributing\nWe love all types of contributions: whether big or small helping in improving this community resource.\n\n1. There are a number of [open issues present](https://github.com/bolna-ai/bolna/issues) which can be good ones to start with\n2. 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\n2. 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:](https://github.com/bolna-ai/bolna/issues/new) 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\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbolna-ai%2Fbolna","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbolna-ai%2Fbolna","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbolna-ai%2Fbolna/lists"}