### Quick Start Docker Setup

Source: https://github.com/bolna-ai/bolna/blob/master/local_setup/README.md

Execute this script to automatically set up Docker dependencies, build services with BuildKit, and start them in detached mode.

```bash
chmod +x start.sh
./start.sh
```

--------------------------------

### Start Bolna Local Setup Script

Source: https://github.com/bolna-ai/bolna/blob/master/README.md

Execute this script to set up and start all Bolna services locally. It checks for Docker dependencies and builds services using BuildKit.

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

--------------------------------

### Run Specific Docker Services

Source: https://github.com/bolna-ai/bolna/blob/master/local_setup/README.md

Start only specific services, such as the Bolna application and either the Twilio or Plivo app. Useful for targeted development or testing.

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

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

--------------------------------

### Run All Docker Services

Source: https://github.com/bolna-ai/bolna/blob/master/local_setup/README.md

Start all defined Docker services in detached mode. This is the standard way to run the full local environment.

```bash
docker compose up -d
```

--------------------------------

### Configure Groq LLM Agent with Reasoning Effort

Source: https://context7.com/bolna-ai/bolna/llms.txt

Configures a SimpleLlmAgent for Groq's inference service, using a Llama3 model. This example demonstrates setting temperature and max_tokens. Note: ReasoningEffort enum is imported but not used in this specific snippet.

```python
# Groq (fast inference) with reasoning effort
from bolna.enums import ReasoningEffort
llm_groq = LlmAgent(
    agent_type="simple_llm_agent",
    agent_flow_type="streaming",
    llm_config=SimpleLlmAgent(
        provider="groq",
        model="llama3-8b-8192",
        temperature=0.4,
        max_tokens=150,
    ),
)
```

--------------------------------

### Get All Agents

Source: https://github.com/bolna-ai/bolna/blob/master/API.md

Retrieves all agents from the system.

```APIDOC
## GET /all

### Description
Retrieves all agents from the system.

### Method
GET

### Endpoint
/all

### Response
#### Success Response (200 OK)
- **agents** (array) - A list of agents.
  - **agent_id** (string) - The unique identifier of the agent.
  - **data** (object) - Contains the agent's configuration and prompts.
    - **agent_config** (object) - The agent's configuration.
    - **agent_prompts** (object) - The agent's prompts.

#### Response Example
```json
{
  "agents": [
    {
      "agent_id": "string",
      "data": {
        "agent_config": {
          "agent_name": "Alfred",
          "agent_type": "other",
          "tasks": []
        },
        "agent_prompts": {}
      }
    }
  ]
}
```
```

--------------------------------

### Configure Cartesia TTS with Language and Speed

Source: https://context7.com/bolna-ai/bolna/llms.txt

Configures the Synthesizer model for Cartesia with streaming enabled. This example sets a specific voice, model, language, and adjusts the speech speed.

```python
# Cartesia with language and speed
tts_cartesia = Synthesizer(
    provider="cartesia",
    stream=True,
    audio_format="pcm",
    provider_config=CartesiaConfig(
        voice_id="a0e99841-438c-4a64-b679-ae501e7d6091",
        voice="Barbershop Man",
        model="sonic-english",
        language="en",
        speed=1.1,
    ),
)
```

--------------------------------

### Get All Agents Response Body

Source: https://github.com/bolna-ai/bolna/blob/master/API.md

The response when retrieving all agents. It contains a list of agents, each with its ID and configuration data.

```json
{
  "agents": [
    {
      "agent_id": "string",
      "data": {
        "agent_config": {
          "agent_name": "Alfred",
          "agent_type": "other",
          "tasks": []
        },
        "agent_prompts": {}
      }
    }
  ]
}
```

--------------------------------

### Get Agent

Source: https://github.com/bolna-ai/bolna/blob/master/API.md

Retrieves an agent's information by agent id.

```APIDOC
## GET /agent/{agent_id}

### Description
Retrieves an agent's information by agent id.

### Method
GET

### Endpoint
/agent/{agent_id}

### Parameters
#### Path Parameters
- **agent_id** (string) - Required - Unique identifier of the agent
```

--------------------------------

### Assistant - Programmatic Voice Pipeline Builder

Source: https://context7.com/bolna-ai/bolna/llms.txt

Demonstrates how to use the `Assistant` class to programmatically build and execute an ASR-LLM-TTS voice pipeline. It shows how to configure transcriber, LLM agent, and synthesizer components and add them as tasks to the assistant.

```APIDOC
## Assistant - Programmatic Voice Pipeline Builder

`Assistant` is the high-level Python entry point. It accumulates tasks via `add_task()` and runs the full ASR→LLM→TTS pipeline as an async generator via `execute()`.

```python
import asyncio
import os
from bolna.assistant import Assistant
from bolna.models import Transcriber, Synthesizer, ElevenLabsConfig, LlmAgent, SimpleLlmAgent

async def main():
    # Set provider credentials
    os.environ["OPENAI_API_KEY"] = "sk-..."
    os.environ["DEEPGRAM_AUTH_TOKEN"] = "..."
    os.environ["ELEVENLABS_API_KEY"] = "..."

    assistant = Assistant(name="support_agent")

    # 1. ASR: Deepgram nova-2, streaming, English
    transcriber = Transcriber(
        provider="deepgram",
        model="nova-2",
        stream=True,
        language="en",
        endpointing=400,          # ms silence before utterance-end
    )

    # 2. LLM: OpenAI GPT-4o-mini, streaming
    llm_agent = LlmAgent(
        agent_type="simple_llm_agent",
        agent_flow_type="streaming",
        llm_config=SimpleLlmAgent(
            provider="openai",
            model="gpt-4o-mini",
            temperature=0.3,
            max_tokens=200,
        ),
    )

    # 3. TTS: ElevenLabs streaming, WAV output
    synthesizer = Synthesizer(
        provider="elevenlabs",
        stream=True,
        audio_format="wav",
        buffer_size=100,
        provider_config=ElevenLabsConfig(
            voice="George",
            voice_id="JBFqnCBsd6RMkjVDRZzb",
            model="eleven_turbo_v2_5",
            speed=1.0,
        ),
    )

    assistant.add_task(
        task_type="conversation",
        llm_agent=llm_agent,
        transcriber=transcriber,
        synthesizer=synthesizer,
        enable_textual_input=False,   # set True for text-only channel
    )

    # execute() is an async generator yielding per-task result dicts
    async for task_output in assistant.execute():
        # Each dict contains: messages, conversation_time, latency_dict, etc.
        print("Conversation history:", task_output.get("messages"))
        print("Duration:", task_output.get("conversation_time"), "s")

asyncio.run(main())
```
```

--------------------------------

### Build and Run Minimal Assistant Pipeline

Source: https://github.com/bolna-ai/bolna/blob/master/README.md

Use this snippet to create a basic conversational agent with audio input (transcriber), LLM processing, and audio output (synthesizer). Ensure API keys for Deepgram, OpenAI, and ElevenLabs are set as environment variables.

```python
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())
```

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

--------------------------------

### Build and Execute Voice Pipeline with Assistant API

Source: https://context7.com/bolna-ai/bolna/llms.txt

Use the `Assistant` class to programmatically define and run a full ASR->LLM->TTS voice pipeline. Configure providers for transcription, LLM inference, and synthesis, then add tasks to the assistant. The `execute()` method yields results as an async generator.

```python
import asyncio
import os
from bolna.assistant import Assistant
from bolna.models import Transcriber, Synthesizer, ElevenLabsConfig, LlmAgent, SimpleLlmAgent

async def main():
    # Set provider credentials
    os.environ["OPENAI_API_KEY"] = "sk-..."
    os.environ["DEEPGRAM_AUTH_TOKEN"] = "..."
    os.environ["ELEVENLABS_API_KEY"] = "..."

    assistant = Assistant(name="support_agent")

    # 1. ASR: Deepgram nova-2, streaming, English
    transcriber = Transcriber(
        provider="deepgram",
        model="nova-2",
        stream=True,
        language="en",
        endpointing=400,          # ms silence before utterance-end
    )

    # 2. LLM: OpenAI GPT-4o-mini, streaming
    llm_agent = LlmAgent(
        agent_type="simple_llm_agent",
        agent_flow_type="streaming",
        llm_config=SimpleLlmAgent(
            provider="openai",
            model="gpt-4o-mini",
            temperature=0.3,
            max_tokens=200,
        ),
    )

    # 3. TTS: ElevenLabs streaming, WAV output
    synthesizer = Synthesizer(
        provider="elevenlabs",
        stream=True,
        audio_format="wav",
        buffer_size=100,
        provider_config=ElevenLabsConfig(
            voice="George",
            voice_id="JBFqnCBsd6RMkjVDRZzb",
            model="eleven_turbo_v2_5",
            speed=1.0,
        ),
    )

    assistant.add_task(
        task_type="conversation",
        llm_agent=llm_agent,
        transcriber=transcriber,
        synthesizer=synthesizer,
        enable_textual_input=False,   # set True for text-only channel
    )

    # execute() is an async generator yielding per-task result dicts
    async for task_output in assistant.execute():
        # Each dict contains: messages, conversation_time, latency_dict, etc.
        print("Conversation history:", task_output.get("messages"))
        print("Duration:", task_output.get("conversation_time"), "s")

asyncio.run(main())

```

--------------------------------

### Build Docker Images

Source: https://github.com/bolna-ai/bolna/blob/master/local_setup/README.md

Build all Docker images defined in the docker-compose file. Ensure BuildKit is enabled for optimal performance.

```bash
docker compose build
```

--------------------------------

### Configure OpenAI GPT-4o Streaming LLM Agent

Source: https://context7.com/bolna-ai/bolna/llms.txt

Configures a SimpleLlmAgent for OpenAI's GPT-4o model with streaming enabled. Adjust temperature, max_tokens, and top_p for desired response characteristics.

```python
from bolna.models import LlmAgent, SimpleLlmAgent

# OpenAI GPT-4o streaming agent
llm_agent = LlmAgent(
    agent_type="simple_llm_agent",
    agent_flow_type="streaming",
    llm_config=SimpleLlmAgent(
        provider="openai",
        model="gpt-4o-mini",
        temperature=0.3,
        max_tokens=200,
        top_p=0.9,
        frequency_penalty=0.1,
    ),
)
```

--------------------------------

### Enable BuildKit for Docker

Source: https://github.com/bolna-ai/bolna/blob/master/local_setup/README.md

Set these environment variables to enable BuildKit for faster Docker image builds.

```bash
export DOCKER_BUILDKIT=1
export COMPOSE_DOCKER_CLI_BUILD=1
```

--------------------------------

### Create Agent with Configuration

Source: https://context7.com/bolna-ai/bolna/llms.txt

Use this endpoint to create a new named agent and persist its configuration. A unique UUID is returned for subsequent calls.

```bash
curl -s -X POST http://localhost:8000/agent \
  -H "Content-Type: application/json" \
  -d '{
    "agent_config": {
      "agent_name": "SupportBot",
      "agent_type": "other",
      "agent_welcome_message": "Hi! How can I help you today?",
      "tasks": [
        {
          "task_type": "conversation",
          "toolchain": {
            "execution": "parallel",
            "pipelines": [["transcriber", "llm", "synthesizer"]]
          },
          "tools_config": {
            "input":  { "format": "wav", "provider": "twilio" },
            "output": { "format": "wav", "provider": "twilio" },
            "transcriber": {
              "provider": "deepgram",
              "model": "nova-2",
              "language": "en",
              "stream": true,
              "encoding": "linear16",
              "endpointing": 400
            },
            "llm_agent": {
              "agent_type": "simple_llm_agent",
              "agent_flow_type": "streaming",
              "llm_config": {
                "provider": "openai",
                "model": "gpt-4o-mini",
                "temperature": 0.3,
                "max_tokens": 200
              }
            },
            "synthesizer": {
              "provider": "elevenlabs",
              "stream": true,
              "audio_format": "wav",
              "buffer_size": 100,
              "provider_config": {
                "voice": "George",
                "voice_id": "JBFqnCBsd6RMkjVDRZzb",
                "model": "eleven_turbo_v2_5"
              }
            }
          },
          "task_config": {
            "hangup_after_silence": 30
          }
        }
      ]
    },
    "agent_prompts": {
      "task_1": {
        "system_prompt": "You are a friendly support agent. Be concise and helpful."
      }
    }
  }'
```

--------------------------------

### Configure Anthropic Claude LLM Agent via LiteLLM

Source: https://context7.com/bolna-ai/bolna/llms.txt

Configures a SimpleLlmAgent for Anthropic's Claude model using LiteLLM. This allows access to Anthropic models through a unified interface. Adjust temperature and max_tokens as needed.

```python
# Anthropic Claude via LiteLLM
llm_anthropic = LlmAgent(
    agent_type="simple_llm_agent",
    agent_flow_type="streaming",
    llm_config=SimpleLlmAgent(
        provider="anthropic",
        model="claude-3-haiku-20240307",
        temperature=0.5,
        max_tokens=300,
    ),
)
```

--------------------------------

### Create Agent

Source: https://github.com/bolna-ai/bolna/blob/master/API.md

Creates a new agent with specified configuration.

```APIDOC
## POST /agent

### Description
Creates a new agent with specified configuration.

### Method
POST

### Endpoint
/agent

### Request Body
- **agent_config** (object) - Required - Configuration for the agent.
- **agent_prompts** (object) - Optional - Prompts for the agent.

### Request Example
```json
{
  "agent_config": {
    "agent_name": "Alfred",
    "agent_type": "other",
    "tasks": [
      {
        "task_type": "conversation",
        "toolchain": {
          "execution": "parallel",
          "pipelines": [["transcriber", "llm", "synthesizer"]]
        },
        "tools_config": {
          "input": { "format": "wav", "provider": "twilio" },
          "output": { "format": "wav", "provider": "twilio" },
          "transcriber": {
            "encoding": "linear16",
            "language": "en",
            "provider": "deepgram",
            "stream": true
          },
          "llm_agent": {
            "agent_type": "simple_llm_agent",
            "agent_flow_type": "streaming",
            "llm_config": {
              "provider": "openai",
              "model": "gpt-4o-mini",
              "request_json": true
            }
          },
          "synthesizer": {
            "audio_format": "wav",
            "provider": "elevenlabs",
            "stream": true,
            "provider_config": {
              "voice": "George",
              "model": "eleven_turbo_v2_5",
              "voice_id": "JBFqnCBsd6RMkjVDRZzb"
            },
            "buffer_size": 100.0
          }
        },
        "task_config": {
          "hangup_after_silence": 30.0
        }
      }
    ],
    "agent_welcome_message": "How are you doing Bruce?"
  },
  "agent_prompts": {
    "task_1": {
      "system_prompt": "Why Do We Fall, Sir? So That We Can Learn To Pick Ourselves Up."
    }
  }
}
```

### Response
#### Success Response (200 OK)
- **agent_id** (string) - Unique identifier of the created agent.
- **state** (string) - The current state of the agent (e.g., "created").

#### Response Example
```json
{
  "agent_id": "uuid-string",
  "state": "created"
}
```
```

--------------------------------

### Retrieve Agent Configuration

Source: https://context7.com/bolna-ai/bolna/llms.txt

Fetch a stored agent's full configuration and prompts using its UUID. The response includes agent configuration and prompt details.

```bash
AGENT_ID="3fa85f64-5717-4562-b3fc-2c963f66afa6"

curl -s http://localhost:8000/agent/$AGENT_ID | python3 -m json.tool
```

--------------------------------

### Configure ElevenLabs TTS with Streaming

Source: https://context7.com/bolna-ai/bolna/llms.txt

Configures the Synthesizer model for ElevenLabs with streaming enabled. Specify the desired voice, model, and audio format. Caching is enabled for performance.

```python
from bolna.models import (
    Synthesizer, ElevenLabsConfig, PollyConfig,
    CartesiaConfig, OpenAIConfig, AzureConfig,
)

# ElevenLabs streaming
tts_elevenlabs = Synthesizer(
    provider="elevenlabs",
    stream=True,
    audio_format="wav",
    buffer_size=100,
    caching=True,
    provider_config=ElevenLabsConfig(
        voice="George",
        voice_id="JBFqnCBsd6RMkjVDRZzb",
        model="eleven_turbo_v2_5",
        temperature=0.5,
        similarity_boost=0.75,
        speed=1.0,
    ),
)
```

--------------------------------

### List All Agents

Source: https://context7.com/bolna-ai/bolna/llms.txt

Retrieve a comprehensive list of all agents currently stored in the system. The response includes agent IDs and their configurations.

```bash
curl -s http://localhost:8000/all | python3 -m json.tool
```

--------------------------------

### Set Multiple Environment Variables

Source: https://context7.com/bolna-ai/bolna/llms.txt

Inject multiple provider API keys and credentials at runtime using `setenv`. These values are then accessible by all subsequent pipeline components.

```python
from bolna import setenv

setenv({
    "OPENAI_API_KEY":        "sk-வுகளை",
    "DEEPGRAM_AUTH_TOKEN":   "...",
    "ELEVENLABS_API_KEY":    "...",
    "CARTESIA_API_KEY":      "...",
    "TWILIO_ACCOUNT_SID":    "AC...",
    "TWILIO_AUTH_TOKEN":     "...",
    "TWILIO_PHONE_NUMBER":   "+1...",
})
# All subsequent Assistant / TaskManager instances will pick up these values.
```

--------------------------------

### LLM Agent Configuration

Source: https://context7.com/bolna-ai/bolna/llms.txt

Configure Large Language Model (LLM) agents using LlmAgent and SimpleLlmAgent models.

```APIDOC
## LLM Agent Models

### Description
`LlmAgent` wraps agent-type-specific configurations. `SimpleLlmAgent` is designed for standard streaming conversation use cases. Supported LLM providers include `openai`, `anthropic`, `google`, `groq`, `azure-openai`, `azure`, `cohere`, `deepseek`, `openrouter`, `ollama`, `vllm`, and all LiteLLM-compatible endpoints.

### Usage
```python
from bolna.models import LlmAgent, SimpleLlmAgent
from bolna.enums import ReasoningEffort

# Example: OpenAI GPT-4o streaming agent
llm_agent = LlmAgent(
    agent_type="simple_llm_agent",
    agent_flow_type="streaming",
    llm_config=SimpleLlmAgent(
        provider="openai",
        model="gpt-4o-mini",
        temperature=0.3,
        max_tokens=200,
        top_p=0.9,
        frequency_penalty=0.1,
    ),
)

# Example: Anthropic Claude via LiteLLM
llm_anthropic = LlmAgent(
    agent_type="simple_llm_agent",
    agent_flow_type="streaming",
    llm_config=SimpleLlmAgent(
        provider="anthropic",
        model="claude-3-haiku-20240307",
        temperature=0.5,
        max_tokens=300,
    ),
)

# Example: Groq (fast inference) with reasoning effort
llm_groq = LlmAgent(
    agent_type="simple_llm_agent",
    agent_flow_type="streaming",
    llm_config=SimpleLlmAgent(
        provider="groq",
        model="llama3-8b-8192",
        temperature=0.4,
        max_tokens=150,
    ),
)
```

### Parameters
- **agent_type** (string) - Required - The type of agent (e.g., `simple_llm_agent`).
- **agent_flow_type** (string) - Required - The flow type of the agent (e.g., `streaming`).
- **llm_config** (object) - Required - Configuration for the LLM provider.
  - **provider** (string) - Required - The LLM provider (e.g., `openai`, `anthropic`).
  - **model** (string) - Required - The LLM model to use.
  - **temperature** (float) - Optional - Controls randomness in output.
  - **max_tokens** (integer) - Optional - Maximum number of tokens to generate.
  - **top_p** (float) - Optional - Nucleus sampling parameter.
  - **frequency_penalty** (float) - Optional - Penalty for repeating tokens.
```

--------------------------------

### Build Text-Only Assistant Pipeline

Source: https://github.com/bolna-ai/bolna/blob/master/README.md

Use this snippet for a text-only conversational agent, omitting audio input and output components. It requires the OpenAI API key to be set as an environment variable.

```python
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())
```

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

--------------------------------

### Configure OpenAI TTS

Source: https://context7.com/bolna-ai/bolna/llms.txt

Configures the Synthesizer model for OpenAI TTS with streaming enabled. Specify the desired voice and model. Ensure OpenAI API key is configured.

```python
# OpenAI TTS
tts_openai = Synthesizer(
    provider="openai",
    stream=True,
    audio_format="wav",
    provider_config=OpenAIConfig(voice="alloy", model="tts-1"),
)
```

--------------------------------

### Configure AWS Polly TTS

Source: https://context7.com/bolna-ai/bolna/llms.txt

Configures the Synthesizer model for AWS Polly with non-streaming enabled. Specify the voice, engine, and language. Ensure AWS credentials are configured.

```python
# AWS Polly
tts_polly = Synthesizer(
    provider="polly",
    stream=False,
    audio_format="pcm",
    provider_config=PollyConfig(
        voice="Joanna",
        engine="neural",
        language="en-US",
    ),
)
```

--------------------------------

### Initiate Outbound Call with Twilio (Python)

Source: https://context7.com/bolna-ai/bolna/llms.txt

Equivalent Python code to initiate an outbound call using the requests library.

```python
# Equivalent Python call using requests
import requests

resp = requests.post(
    "http://localhost:8001/call",
    json={
        "agent_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "recipient_phone_number": "+14155552671",
    },
    timeout=10,
)
print(resp.status_code, resp.text)   # 200 done
```

--------------------------------

### Bilingual Agent Configuration (English/Hindi)

Source: https://context7.com/bolna-ai/bolna/llms.txt

Use this JSON configuration to set up an agent that supports both English and Hindi. The configuration specifies parallel ASR/TTS pipelines and defines multilingual models for transcription and synthesis.

```json
{
    "agent_config": {
        "agent_name": "BilingualAgent",
        "agent_type": "other",
        "agent_welcome_message": "Hello / Namaste!",
        "tasks": [
            {
                "task_type": "conversation",
                "toolchain": {
                    "execution": "parallel",
                    "pipelines": [["transcriber", "llm", "synthesizer"]]
                },
                "tools_config": {
                    "input":  { "format": "wav", "provider": "twilio" },
                    "output": { "format": "wav", "provider": "twilio" },
                    "transcriber": {
                        "provider": "deepgram",
                        "model": "nova-2",
                        "stream": True,
                        "active": "en",             # default active language
                        "multilingual": {
                            "en": { "provider": "deepgram", "model": "nova-2", "language": "en" },
                            "hi": { "provider": "deepgram", "model": "nova-2", "language": "hi" },
                        },
                    },
                    "llm_agent": {
                        "agent_type": "simple_llm_agent",
                        "agent_flow_type": "streaming",
                        "llm_config": {
                            "provider": "openai", "model": "gpt-4o-mini", "temperature": 0.3
                        },
                    },
                    "synthesizer": {
                        "provider": "elevenlabs",
                        "stream": True,
                        "audio_format": "wav",
                        "active": "en",
                        "multilingual": {
                            "en": {
                                "provider": "elevenlabs",
                                "provider_config": {
                                    "voice": "George",
                                    "voice_id": "JBFqnCBsd6RMkjVDRZzb",
                                    "model": "eleven_turbo_v2_5"
                                },
                            },
                            "hi": {
                                "provider": "elevenlabs",
                                "provider_config": {
                                    "voice": "Priya",
                                    "voice_id": "...",
                                    "model": "eleven_turbo_v2_5"
                                },
                            },
                        },
                        "provider_config": {
                            "voice": "George", "voice_id": "JBFqnCBsd6RMkjVDRZzb",
                            "model": "eleven_turbo_v2_5"
                        },
                    },
                    # Optional: custom handoff message when switching
                    "switch_handoff_messages": {
                        "en": "Let me connect you with our {language} agent, {agent_name}.",
```

```json
                        "hi": "मैं आपको {language} एजेंट {agent_name} से जोड़ता हूँ।",
                    },
                    "agent_names": { "en": "Alex", "hi": "Priya" },
                },
            }
        ],
    },
    "agent_prompts": {
        "task_1": {
            "system_prompt": "You are a bilingual support agent. Respond in the caller's language.",
            "multilingual_prompts": {
                "hi": "आप एक द्विभाषी सहायता एजेंट हैं। कॉलर की भाषा में उत्तर दें।"
            },
        },
    },
}
```

--------------------------------

### Retrieve Agent

Source: https://context7.com/bolna-ai/bolna/llms.txt

Fetches the complete configuration and prompts for a specific agent using its unique agent ID.

```APIDOC
## GET /agent/{agent_id} — Retrieve agent

### Description
Fetches a stored agent's full configuration and prompts by its UUID.

### Method
GET

### Endpoint
/agent/{agent_id}

### Parameters
#### Path Parameters
- **agent_id** (string) - Required - The unique identifier of the agent to retrieve.

### Response
#### Success Response (200)
- **agent_id** (string) - The unique identifier of the agent.
- **data** (object) - Contains the agent's configuration and prompts.
  - **agent_config** (object) - The agent's configuration.
  - **agent_prompts** (object) - The prompts associated with the agent's tasks.

### Response Example
```json
{
  "agent_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "data": {
    "agent_config": { "agent_name": "SupportBot", "tasks": [...] },
    "agent_prompts": { "task_1": { "system_prompt": "..." } }
  }
}
```
```

--------------------------------

### Create Agent Request Body

Source: https://github.com/bolna-ai/bolna/blob/master/API.md

Defines the structure for creating a new agent, including its name, type, tasks, and prompts. Ensure all required fields within agent_config and tasks are correctly populated.

```json
{
  "agent_config": {
    "agent_name": "Alfred",
    "agent_type": "other",
    "tasks": [
      {
        "task_type": "conversation",
        "toolchain": {
          "execution": "parallel",
          "pipelines": [["transcriber", "llm", "synthesizer"]]
        },
        "tools_config": {
          "input": { "format": "wav", "provider": "twilio" },
          "output": { "format": "wav", "provider": "twilio" },
          "transcriber": {
            "encoding": "linear16",
            "language": "en",
            "provider": "deepgram",
            "stream": true
          },
          "llm_agent": {
            "agent_type": "simple_llm_agent",
            "agent_flow_type": "streaming",
            "llm_config": {
              "provider": "openai",
              "model": "gpt-4o-mini",
              "request_json": true
            }
          },
          "synthesizer": {
            "audio_format": "wav",
            "provider": "elevenlabs",
            "stream": true,
            "provider_config": {
              "voice": "George",
              "model": "eleven_turbo_v2_5",
              "voice_id": "JBFqnCBsd6RMkjVDRZzb"
            },
            "buffer_size": 100.0
          }
        },
        "task_config": {
          "hangup_after_silence": 30.0
        }
      }
    ],
    "agent_welcome_message": "How are you doing Bruce?"
  },
  "agent_prompts": {
    "task_1": {
      "system_prompt": "Why Do We Fall, Sir? So That We Can Learn To Pick Ourselves Up."
    }
  }
}
```

--------------------------------

### Initiate Outbound Call with Twilio

Source: https://context7.com/bolna-ai/bolna/llms.txt

Initiates an outbound call using the local telephony server's /call endpoint. Twilio connects the call to the Bolna WebSocket endpoint.

```bash
# Start the local stack first:
#   cd local_setup && ./start.sh

# Initiate a call via Twilio
curl -s -X POST http://localhost:8001/call \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "recipient_phone_number": "+14155552671"
  }'

# Returns: "done"  (HTTP 200, plaintext)
```

--------------------------------

### Synthesizer Model Configuration

Source: https://context7.com/bolna-ai/bolna/llms.txt

Configure Text-to-Speech (TTS) providers and their parameters using the Synthesizer Pydantic model.

```APIDOC
## Synthesizer Model

### Description
Validates TTS provider configuration. Supported providers include `elevenlabs`, `polly`, `openai`, `deepgram`, `azuretts`, `cartesia`, `smallest`, `sarvam`, `rime`, and `pixa`.

### Usage
```python
from bolna.models import Synthesizer, ElevenLabsConfig, PollyConfig, CartesiaConfig, OpenAIConfig, AzureConfig

# Example: ElevenLabs streaming
tts_elevenlabs = Synthesizer(
    provider="elevenlabs",
    stream=True,
    audio_format="wav",
    buffer_size=100,
    caching=True,
    provider_config=ElevenLabsConfig(
        voice="George",
        voice_id="JBFqnCBsd6RMkjVDRZzb",
        model="eleven_turbo_v2_5",
        temperature=0.5,
        similarity_boost=0.75,
        speed=1.0,
    ),
)

# Example: AWS Polly
tts_polly = Synthesizer(
    provider="polly",
    stream=False,
    audio_format="pcm",
    provider_config=PollyConfig(
        voice="Joanna",
        engine="neural",
        language="en-US",
    ),
)

# Example: Cartesia with language and speed
tts_cartesia = Synthesizer(
    provider="cartesia",
    stream=True,
    audio_format="pcm",
    provider_config=CartesiaConfig(
        voice_id="a0e99841-438c-4a64-b679-ae501e7d6091",
        voice="Barbershop Man",
        model="sonic-english",
        language="en",
        speed=1.1,
    ),
)

# Example: OpenAI TTS
tts_openai = Synthesizer(
    provider="openai",
    stream=True,
    audio_format="wav",
    provider_config=OpenAIConfig(voice="alloy", model="tts-1"),
)
```

### Parameters
- **provider** (string) - Required - The TTS provider to use (e.g., `elevenlabs`, `polly`).
- **stream** (boolean) - Required - Whether to use streaming.
- **audio_format** (string) - Required - The desired audio format (e.g., `wav`, `pcm`).
- **buffer_size** (integer) - Optional - Buffer size for streaming.
- **caching** (boolean) - Optional - Whether to enable caching.
- **provider_config** (object) - Required - Configuration specific to the chosen provider.
```

--------------------------------

### Update Agent Configuration

Source: https://context7.com/bolna-ai/bolna/llms.txt

Replace an existing agent's configuration entirely with new settings. The request body schema is identical to the `POST /agent` endpoint.

```bash
AGENT_ID="3fa85f64-5717-4562-b3fc-2c963f66afa6"

curl -s -X PUT http://localhost:8000/agent/$AGENT_ID \
  -H "Content-Type: application/json" \
  -d '{
    "agent_config": {
      "agent_name": "SupportBot",
      "agent_type": "other",
      "agent_welcome_message": "Hello, updated greeting!",
      "tasks": [
        {
          "task_type": "conversation",
          "toolchain": { "execution": "parallel", "pipelines": [["transcriber", "llm", "synthesizer"]] },
          "tools_config": {
            "input":  { "format": "wav", "provider": "twilio" },
            "output": { "format": "wav", "provider": "twilio" },
            "transcriber": { "provider": "deepgram", "model": "nova-2", "language": "en", "stream": true, "encoding": "linear16" },
            "llm_agent": {
              "agent_type": "simple_llm_agent",
              "agent_flow_type": "streaming",
              "llm_config": { "provider": "openai", "model": "gpt-4o", "temperature": 0.2, "max_tokens": 300 }
            },
            "synthesizer": {
              "provider": "openai",
              "stream": true,
              "audio_format": "wav",
              "provider_config": { "voice": "alloy", "model": "tts-1" }
            }
          }
        }
      ]
    },
    "agent_prompts": {
      "task_1": { "system_prompt": "You are an updated, knowledgeable support agent." }
    }
  }'
```

--------------------------------

### Define a Graph Agent with Two Nodes

Source: https://context7.com/bolna-ai/bolna/llms.txt

Configure a conversational flow using GraphAgentConfig. Define nodes and edges to control the conversation path. Ensure routing models are fast for efficient decision-making.

```python
from bolna.models import (
    LlmAgent, GraphAgentConfig, GraphNode, GraphEdge
)
from bolna.enums import EdgeConditionType, NodeType

# Two-node flow: greeting → qualification
greeting_node = GraphNode(
    id="greeting",
    description="Greet the caller and introduce yourself",
    node_type=NodeType.LLM,
    prompt="You are a sales agent. Greet the caller warmly and ask about their interest.",
    edges=[
        GraphEdge(
            to_node_id="qualification",
            condition="User expresses interest in the product",
            condition_type=EdgeConditionType.LLM,
            function_name="go_to_qualification",
            function_description="Transition when caller shows buying intent",
        )
    ],
    repeat_after_silence_seconds=10.0,   # re-prompt after 10s silence
)

qualification_node = GraphNode(
    id="qualification",
    description="Collect budget and timeline",
    node_type=NodeType.LLM,
    prompt="Ask about budget range and preferred timeline. Be concise.",
    edges=[],  # terminal node
)

graph_llm_agent = LlmAgent(
    agent_type="graph_agent",
    agent_flow_type="streaming",
    llm_config=GraphAgentConfig(
        provider="openai",
        model="gpt-4o-mini",
        temperature=0.3,
        max_tokens=200,
        agent_information="Sales qualification bot",
        nodes=[greeting_node, qualification_node],
        current_node_id="greeting",
        # Use a fast model for routing decisions
        routing_provider="groq",
        routing_model="llama3-8b-8192",
    ),
)
```

--------------------------------

### Execute External API Calls with `trigger_api`

Source: https://context7.com/bolna-ai/bolna/llms.txt

Use `trigger_api` to integrate with external services via HTTP requests. Supports parameter substitution and various HTTP methods. Ensure the tool definition matches the function signature.

```python
import asyncio
from bolna.helpers.function_calling_helpers import trigger_api

# Tool definition registered with the agent:
# {
#   "type": "function",
#   "function": {
#     "name": "check_availability",
#     "description": "Check slot availability for a given date",
#     "parameters": {
#       "type": "object",
#       "properties": { "date": { "type": "string" } },
#       "required": ["date"]
#     }
#   }
# }

async def demo_tool_call():
    response = await trigger_api(
        url="https://api.example.com/availability",
        method="post",
        param='{"date": "% (date)s"}',          # legacy template format
        api_token="Bearer my-secret-token",
        headers_data={"X-Source": "bolna"},
        meta_info={"request_id": "test-001", "sequence_id": 1},
        run_id="run-123",
        date="2024-03-15",                      # substituted into param template
    )
    print(response)   # raw JSON string from the external API

asyncio.run(demo_tool_call())
```

--------------------------------

### Configure Deepgram ASR with Keyword Boosting

Source: https://context7.com/bolna-ai/bolna/llms.txt

Configures the Transcriber model for Deepgram with streaming enabled and keyword boosting for specific terms. Ensure the 'deepgram' provider is supported and parameters like sampling rate and encoding are correctly set for your audio source.

```python
from bolna.models import Transcriber

# Streaming Deepgram with keyword boosting
transcriber = Transcriber(
    provider="deepgram",
    model="nova-2",
    stream=True,
    language="en",
    encoding="linear16",
    sampling_rate=16000,
    endpointing=500,       # ms silence for utterance-end detection
    keywords="Bolna:2",    # boost recognition of brand names
)
print(transcriber.model_dump())
# {
#   'provider': 'deepgram', 'model': 'nova-2', 'stream': True,
#   'language': 'en', 'encoding': 'linear16', 'sampling_rate': 16000,
#   'endpointing': 500, 'keywords': 'Bolna:2', ...
# }
```

--------------------------------

### List All Agents

Source: https://context7.com/bolna-ai/bolna/llms.txt

Retrieves a comprehensive list of all agents currently stored within the system.

```APIDOC
## GET /all — List all agents

### Description
Returns the complete list of agents stored in the system.

### Method
GET

### Endpoint
/all

### Response
#### Success Response (200)
- **agents** (array) - A list of agent objects.
  - Each object contains:
    - **agent_id** (string) - The unique identifier of the agent.
    - **data** (object) - Contains the agent's configuration and prompts.
      - **agent_config** (object) - The agent's configuration.
      - **agent_prompts** (object) - The prompts associated with the agent's tasks.

### Response Example
```json
{
  "agents": [
    {
      "agent_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "data": {
        "agent_config": { "agent_name": "SupportBot", ... },
        "agent_prompts": { "task_1": { "system_prompt": "..." } }
      }
    }
  ]
}
```
```

--------------------------------

### Configure Conversation Behavior

Source: https://context7.com/bolna-ai/bolna/llms.txt

Tune conversation dynamics using `ConversationConfig`. Adjust parameters for hangup timing, interruption sensitivity, backchanneling, and more. Apply these settings per task via `task_config`.

```python
from bolna.models import ConversationConfig

config = ConversationConfig(
    hangup_after_silence=20,          # hang up after 20s of mutual silence
    number_of_words_for_interruption=2, # 2+ words triggers barge-in
    backchanneling=True,              # emit "mm-hmm" while user speaks
    backchanneling_start_delay=5,     # wait 5s before first backchannel
    backchanneling_message_gap=4,     # gap between backchannels (s)
    use_fillers=True,                 # inject filler phrases
    optimize_latency=True,           # use interim ASR results to cut latency
    voicemail=True,                   # enable voicemail detection
    voicemail_detection_duration=30.0,
    dtmf_enabled=False,
    call_terminate=300,              # hard cap for web calls (s)
    check_if_user_online=True,
    check_user_online_message="Hey, are you still there?",
    trigger_user_online_message_after=12,
)
print(config.model_dump())
```

--------------------------------

### Configure Azure Speech ASR (Non-Streaming)

Source: https://context7.com/bolna-ai/bolna/llms.txt

Configures the Transcriber model for Azure Speech, disabling streaming for non-streaming ASR. Ensure the 'azure' provider is supported and the language code is correct.

```python
# Azure Speech (HTTP, non-streaming)
azure_transcriber = Transcriber(
    provider="azure",
    model="azure",
    stream=False,
    language="en-US",
)
```