{"id":8594,"library":"retell-sdk","title":"Retell AI Python SDK","description":"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.","status":"active","version":"5.25.1","language":"en","source_language":"en","source_url":"https://github.com/RetellAI/retell-python-sdk","tags":["AI","voice","realtime","conversation","LLM","speech","API client"],"install":[{"cmd":"pip install retell-sdk","lang":"bash","label":"Install latest version"}],"dependencies":[],"imports":[{"symbol":"RetellClient","correct":"from retell_sdk import RetellClient"},{"note":"Common models are found in `retell_sdk.models`.","symbol":"AgentResponse","correct":"from retell_sdk.models import AgentResponse"}],"quickstart":{"code":"import os\nfrom retell_sdk import RetellClient\nfrom retell_sdk.models import AgentResponse\n\n# Ensure your Retell API key is set as an environment variable or passed directly.\n# It's recommended to set RETELL_API_KEY in your environment.\napi_key = os.environ.get(\"RETELL_API_KEY\", \"YOUR_RETELL_API_KEY\")\n\nif api_key == \"YOUR_RETELL_API_KEY\":\n    print(\"WARNING: Please set the RETELL_API_KEY environment variable or replace 'YOUR_RETELL_API_KEY' with your actual key.\")\n\ntry:\n    client = RetellClient(api_key=api_key)\n\n    # Example: List all agents\n    print(\"\\nListing agents...\")\n    agents_list_response = client.agent.list_all(limit=5)\n    \n    if agents_list_response and agents_list_response.data:\n        for agent in agents_list_response.data:\n            print(f\"  - Agent ID: {agent.agent_id}, LLM URL: {agent.llm_websocket_url}\")\n    else:\n        print(\"No agents found or an error occurred.\")\n\n    # Example: Retrieve a specific agent (replace with an actual agent_id if available)\n    # agent_id_to_retrieve = \"your_agent_id_here\"\n    # try:\n    #     agent: AgentResponse = client.agent.get(agent_id=agent_id_to_retrieve)\n    #     print(f\"\\nRetrieved Agent ID: {agent.agent_id}, Voice: {agent.voice_id}\")\n    # except Exception as e:\n    #     print(f\"Error retrieving agent {agent_id_to_retrieve}: {e}\")\n\nexcept Exception as e:\n    print(f\"An error occurred: {e}\")","lang":"python","description":"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."},"warnings":[{"fix":"Regularly upgrade your `retell-sdk` package (`pip install --upgrade retell-sdk`) and consult the official Retell AI documentation for the latest API specifications.","message":"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.","severity":"gotcha","affected_versions":">=5.0.0"},{"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\")`.","message":"Authentication requires a valid `RETELL_API_KEY`. Without it, all API calls will fail with an authentication error.","severity":"gotcha","affected_versions":"All"},{"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.","message":"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`.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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\")`.","cause":"The `RETELL_API_KEY` environment variable is not set, or an invalid key was passed to the `RetellClient`.","error":"retell_sdk.AuthenticationError: Missing or invalid API key."},{"fix":"Upgrade the SDK to the latest version: `pip install --upgrade retell-sdk`.","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.","error":"AttributeError: 'Client' object has no attribute 'some_new_method'"},{"fix":"Install the library using pip: `pip install retell-sdk`. Ensure your import statement is `from retell_sdk import RetellClient`.","cause":"The `retell-sdk` library is not installed in your current Python environment, or you are attempting to import it incorrectly.","error":"ModuleNotFoundError: No module named 'retell_sdk'"},{"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.","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.","error":"pydantic.ValidationError: 1 validation error for AgentCreateRequest ..."}]}