> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vatel.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Python SDK

> Use the Vatel REST and WebSocket APIs from Python. Run real-time voice sessions and access the API with async support.

Use the **Vatel Python SDK** to call the REST and WebSocket APIs from Python. The REST client exposes the API for your organization; the WebSocket connection is async-only for real-time sessions; you receive events and send input audio and tool results.

<Card title="Session token" icon="key" href="/api-reference/session/session-token">
  REST endpoint used to obtain a short-lived JWT for the WebSocket connection.
</Card>

<Card title="Connection" icon="radio" href="/api-reference/session/connection">
  WebSocket channel, message types, and request/response flow.
</Card>

## Prerequisites

* **Python** 3.9+
* **Organization API key** from the Vatel dashboard
* **Agent ID** (agent UUID) for the agent you want to run the call with

## Walkthrough

<Steps>
  <Step title="Install the SDK">
    Install from the repository:

    ```bash theme={null}
    pip install git+https://github.com/Devpro-Software/vatel-py-sdk.git
    ```
  </Step>

  <Step title="Create a client">
    Create a `Client` with your organization API key. Optionally set a different host:

    ```python theme={null}
    from vatel import Client

    client = Client(api_key="your-organization-api-key")
    ```
  </Step>

  <Step title="Get a session token">
    Generate a short-lived token for the WebSocket. Pass the **agent UUID** you want to run the call with:

    ```python theme={null}
    resp = client.session.generate_token(agent_id="agent-uuid-here")
    token = resp.token
    ```

    Async: `resp = await client.session.generate_token_async(agent_id="...")`.
  </Step>

  <Step title="Connect and stream messages">
    Connect with the token and iterate over incoming messages. Handle events and send tool results as needed:

    ```python theme={null}
    import asyncio
    from vatel import Client
    from vatel.models.ws import ToolCall

    async def main():
        client = Client(api_key="your-api-key")
        token = (await client.session.generate_token_async(agent_id="agent-uuid")).token
        conn = await client.connect(token=token)

        async for msg in conn.stream_messages():
            if getattr(msg, "type", None) == "session_started":
                print("Call started:", msg.data.id)
            elif getattr(msg, "type", None) == "response_text":
                print("Agent:", msg.data.text)
            elif getattr(msg, "type", None) == "input_audio_transcript":
                print("You:", msg.data.transcript)
            elif getattr(msg, "type", None) == "response_audio":
                # Base64 PCM 16-bit 24 000 Hz mono - decode and play or process
                pass
            elif getattr(msg, "type", None) == "session_ended":
                break
            elif isinstance(msg, ToolCall):
                await conn.send_tool_call_output(msg.data.toolCallId, "your-result")

        await conn.close()
        await client.aclose()

    asyncio.run(main())
    ```
  </Step>

  <Step title="Send audio">
    Send captured audio as base64-encoded **PCM 16-bit, 24 000 Hz, mono**:

    ```python theme={null}
    await conn.send_input_audio(audio_base64="...")
    ```
  </Step>
</Steps>

## REST API

The client exposes the REST API; see the [API reference](/api-reference) for all endpoints. Examples:

**List agents** (sync and async):

```python theme={null}
agents = client.agents.list()
for agent in agents:
    print(agent.id, agent.name)
# Async: agents = await client.agents.list_async()
```

**Session token** (required for the WebSocket):

```python theme={null}
resp = client.session.generate_token(agent_id="agent-uuid-here")
token = resp.token
# Async: resp = await client.session.generate_token_async(agent_id="...")
```

## Tool calls

When the server sends a `tool_call` message, run your logic and send the result back:

```python theme={null}
await conn.send_tool_call_output(tool_call_id=msg.data.toolCallId, output="result string")
```

## Message types (server → client)

| Type                                | Description                                                |
| ----------------------------------- | ---------------------------------------------------------- |
| `session_started`                   | Call started; `data.id` is session ID                      |
| `session_ended`                     | Call ended                                                 |
| `response_audio`                    | Agent TTS chunk; `data.audio` base64, `data.turn_id`       |
| `response_text`                     | Agent text for the turn                                    |
| `input_audio_transcript`            | Your speech (STT)                                          |
| `speech_started` / `speech_stopped` | VAD events                                                 |
| `interruption`                      | You interrupted the agent                                  |
| `tool_call`                         | Server requests a tool; reply with `send_tool_call_output` |

## Example app

The repo includes a full-duplex demo (mic → server, agent audio → speaker):

```bash theme={null}
pip install -r examples/requirements-optional.txt
python examples/run_session.py --api-key YOUR_KEY --agent-id AGENT_UUID
```