Retell AI Python SDK

5.25.1 · active · verified Thu Apr 16

The official Python library for the Retell API, designed to simplify building AI voice agents. It enables real-time, bidirectional voice conversations with LLMs. The library is actively maintained with frequent updates, often reflecting changes and new features in the core Retell API.

Common errors

```
retell_sdk.AuthenticationError: Missing or invalid API key.
```
cause The `RETELL_API_KEY` environment variable is not set, or an invalid key was passed to the `RetellClient`.

fix Set your environment variable: `export RETELL_API_KEY="YOUR_API_KEY"` (Linux/macOS) or `$env:RETELL_API_KEY="YOUR_API_KEY"` (PowerShell), or initialize the client with `client = RetellClient(api_key="YOUR_API_KEY")`.
```
AttributeError: 'Client' object has no attribute 'some_new_method'
```
cause You are using an older version of the `retell-sdk` while the Retell API has introduced new endpoints or features not present in your SDK version.

fix Upgrade the SDK to the latest version: `pip install --upgrade retell-sdk`.
```
ModuleNotFoundError: No module named 'retell_sdk'
```
cause The `retell-sdk` library is not installed in your current Python environment, or you are attempting to import it incorrectly.

fix Install the library using pip: `pip install retell-sdk`. Ensure your import statement is `from retell_sdk import RetellClient`.
```
pydantic.ValidationError: 1 validation error for AgentCreateRequest ...
```
cause An API call was made with incorrect parameter types, missing a required field, or providing an invalid value according to the Retell API schema.

fix Check the official Retell API documentation or the SDK's model definitions (e.g., `retell_sdk.models.AgentCreateRequest`) to ensure all parameters are correctly typed and present.

Warnings

gotcha The Retell API and its Python SDK are under active development, with frequent 'api update' releases. While explicit breaking changes are not always tagged as such in the SDK changelog, underlying API changes can lead to new required parameters, renamed fields, or altered data structures. Always review release notes and keep your SDK updated.
Fix: Regularly upgrade your `retell-sdk` package (`pip install --upgrade retell-sdk`) and consult the official Retell AI documentation for the latest API specifications.
gotcha Authentication requires a valid `RETELL_API_KEY`. Without it, all API calls will fail with an authentication error.
Fix: Ensure the `RETELL_API_KEY` environment variable is set, or pass your API key directly to the `RetellClient` constructor: `RetellClient(api_key="YOUR_API_KEY")`.
gotcha The SDK is automatically generated from the Retell OpenAPI specification. This means that type hints and data models are strictly enforced. Incorrect parameter types or missing required fields will result in `pydantic.ValidationError`.
Fix: Refer to the official Retell API documentation or the SDK's generated model definitions (e.g., `retell_sdk.models.AgentCreateRequest`) for exact parameter types and requirements.

Install

pip install retell-sdk Install latest version

Imports

RetellClient
```
from retell_sdk import RetellClient
```
AgentResponse
```
from retell_sdk.models import AgentResponse
```
Common models are found in `retell_sdk.models`.

Quickstart

Initializes the RetellClient using an API key from an environment variable and demonstrates listing existing agents. Remember to replace 'YOUR_RETELL_API_KEY' or set the `RETELL_API_KEY` environment variable.

import os
from retell_sdk import RetellClient
from retell_sdk.models import AgentResponse

# Ensure your Retell API key is set as an environment variable or passed directly.
# It's recommended to set RETELL_API_KEY in your environment.
api_key = os.environ.get("RETELL_API_KEY", "YOUR_RETELL_API_KEY")

if api_key == "YOUR_RETELL_API_KEY":
    print("WARNING: Please set the RETELL_API_KEY environment variable or replace 'YOUR_RETELL_API_KEY' with your actual key.")

try:
    client = RetellClient(api_key=api_key)

    # Example: List all agents
    print("\nListing agents...")
    agents_list_response = client.agent.list_all(limit=5)
    
    if agents_list_response and agents_list_response.data:
        for agent in agents_list_response.data:
            print(f"  - Agent ID: {agent.agent_id}, LLM URL: {agent.llm_websocket_url}")
    else:
        print("No agents found or an error occurred.")

    # Example: Retrieve a specific agent (replace with an actual agent_id if available)
    # agent_id_to_retrieve = "your_agent_id_here"
    # try:
    #     agent: AgentResponse = client.agent.get(agent_id=agent_id_to_retrieve)
    #     print(f"\nRetrieved Agent ID: {agent.agent_id}, Voice: {agent.voice_id}")
    # except Exception as e:
    #     print(f"Error retrieving agent {agent_id_to_retrieve}: {e}")

except Exception as e:
    print(f"An error occurred: {e}")

view raw JSON →