---
id: retell-sdk
version: "5.61.0"
license: Apache-2.0
license_treatment: permissive
maintenance: active
---

# retell-sdk — The official Python library for the retell API

License: permissive · Maintenance: active · Downloads: 577.1K/mo

## What it is and what it does

Retell-sdk is the official Python client for the Retell REST API, a service for building and managing voice agents. It wraps the Retell API endpoints with typed request and response models, automatic retries, and configurable timeouts. The library supports both synchronous (Retell) and asynchronous (AsyncRetell) clients, both powered by httpx by default, with an optional aiohttp backend for async workloads.

The package is designed for developers building voice-based conversational AI applications. It handles authentication, error mapping (distinguishing connection errors, rate limits, and HTTP status codes), and provides Pydantic models for responses with helper methods like to_json() and to_dict(). Type hints throughout enable IDE autocomplete and type checking, and the library includes automatic retry logic for transient failures.

Use it for:

- Create and configure voice agents with custom LLM backends and voice settings via the agent.create() endpoint.
- Build async applications that manage multiple concurrent voice agent interactions without blocking.
- Integrate Retell voice capabilities into existing Python applications with full type safety and IDE support.
- Handle API errors gracefully by catching specific exception types (RateLimitError, AuthenticationError, etc.).
- Use the optional aiohttp backend to optimize concurrency performance in high-throughput async scenarios.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

Provides a Python client library for the Retell REST API, offering synchronous and asynchronous access to voice agent creation and management with full type hints.

Yes. The package is actively maintained, has no known vulnerabilities, installs with low friction, uses a permissive license, and provides a well-typed, production-ready client for the Retell API. Install it if you are building voice agent applications with Retell.

## Install

pip install retell-sdk
uv add retell-sdk
poetry add retell-sdk

## Installing retell-sdk

Before you install: Low friction installation with a pure-Python wheel and no compiled dependencies. Active maintenance with a release 4 days ago and recent commits. Supports Python 3.9 through 3.14.

License in practice: Apache-2.0 is permissive; you can use, modify, and distribute this library freely in commercial and private projects with minimal restrictions.

Quickstart:

pip install retell-sdk

import os
from retell import Retell

client = Retell(api_key=os.environ.get("RETELL_API_KEY"))
agent_response = client.agent.create(
    response_engine={"llm_id": "llm_234sdertfsdsfsdf", "type": "retell-llm"},
    voice_id="retell-Cimo",
)
print(agent_response.agent_id)

Requires RETELL_API_KEY environment variable or explicit api_key parameter to authenticate with the Retell service.

Verify before relying:

- Whether the MCP Server feature is production-ready or experimental.
- Performance characteristics and rate-limit behavior under high concurrency.
- Whether aiohttp backend provides measurable concurrency improvements over httpx in typical workloads.

## Package facts

- License: Apache-2.0 (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 577.1K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

retell api client python, voice agent sdk, async http client library, typed rest api wrapper, retell ai integration, python api client generator, conversation ai sdk, voice-ai, async-http, typed-client

[View on SkillFed](https://skillfed.io/packages/retell-sdk) · [View on PyPI](https://pypi.org/project/retell-sdk/)