Retell AI

Save your Retell AI API key. Call this when the user provides their key. WHERE TO GET A KEY: 1. Go to https://www.retellai.com/dashboard 2. Navigate to API Keys in settings 3. Create and copy your API key All other Retell AI tools require a valid API key to work.

Create a new voice agent with specified voice, LLM, and language settings. WHEN TO USE: - Setting up a new voice agent from scratch - No existing agent fits the use case WORKFLOW: 1. list_voices → choose voice_id 2. create_retell_llm → create prompt/model config 3. create_agent → point response_engine.llm_id at that LLM 4. publish_agent → make the version live 5. update_phone_number → bind the agent for calls EXAMPLE: { "agent_name": "Sales qualifier", "voice_id": "11labs-Adrian", "response_engine": { "type": "retell-llm", "llm_id": "llm_xxx" }, "language": "en-US" } COMMON MISTAKES: - Creating the agent before creating/selecting a Retell LLM - Forgetting to publish and bind the agent to a phone number before create_phone_call ERROR RECOVERY: - 401: API key is missing or invalid → configure_retell_api_key - 404: voice_id or llm_id not found → list_voices/list_retell_llms and retry - 422: invalid config → verify response_engine is { "type": "retell-llm", "llm_id": "..." } RELATED TOOLS: - list_voices: Choose a voice_id - create_retell_llm/list_retell_llms: Choose or create the LLM - publish_agent: Make the new version live - update_phone_number: Bind for inbound/outbound calls RETURNS: agent_id, agent_name, voice_id, response_engine, language, version fields.

Create an outbound phone call using a Retell AI voice agent. WHEN TO USE: User asks you to make, place, or initiate a phone call. WORKFLOW (typical sequence): 1. list_agents → find the right agent, note its agent_id 2. get_agent → check config, get its retell_llm_id 3. update_retell_llm → set the conversation prompt/instructions 4. Wait 2-3 seconds (let config propagate) 5. create_phone_call → initiate the call 6. Poll get_call every 5-10s until status is "ended" EXAMPLE: { "from_number": "+14155551234", "to_number": "+14155559876", "override_agent_id": "agent_xxx", "override_agent_version": 2 } COMMON MISTAKES: - Skipping update_retell_llm first: the agent will use the previous call's prompt - Passing override_agent_id without override_agent_version: Retell may route to the wrong or unpublished version - Assuming the phone number is already bound: check list_phone_numbers/get_phone_number - Updating the agent or LLM but not publishing the version before calling ERROR RECOVERY: - 401: API key is missing or invalid → ask the user for the key, then configure_retell_api_key - 404: resource/version/binding not found → check phone number outbound_agents, get_agent_versions, then publish_agent or pass override_agent_version - 422: bad parameter shape/value → verify E.164 phone numbers and valid agent/version IDs CRITICAL: If the call returns 404, the most common causes are: - The phone number has no outbound agent bound → use update_phone_number to bind one - The agent version is unpublished → use publish_agent first, or pass override_agent_version - Always pass override_agent_id AND override_agent_version for reliable routing RELATED TOOLS: - update_retell_llm: Set the prompt before placing the call - get_phone_number/list_phone_numbers: Verify outbound bindings and from_number - publish_agent/get_agent_versions: Confirm the version is live - get_call: Monitor status and retrieve transcript/recording RETURNS: call_id, status, agent_id, from_number, to_number, st…

Create a new Retell LLM response engine with prompt and model settings. WHEN TO USE: - Creating a new agent that needs its own prompt/model config - Separating a new call workflow from an existing agent's LLM - Testing a new prompt without overwriting a production LLM WORKFLOW: Create the LLM first, then create_agent with response_engine: { "type": "retell-llm", "llm_id": "<returned llm_id>" }. EXAMPLE: { "general_prompt": "You confirm appointment times and answer basic scheduling questions.", "begin_message": "Hi, I'm calling to confirm your appointment.", "model": "gpt-5.5" } MODEL OPTIONS: gpt-4.1, gpt-4.1-mini, gpt-5, gpt-5-mini, gpt-5.5, claude-4.5-sonnet, claude-4.6-sonnet, claude-4.5-haiku, gemini-2.5-flash-lite, gemini-3.0-flash, gemini-3.1-flash-lite. COMMON MISTAKES: - Creating multiple near-identical LLMs instead of updating the existing one - Creating the LLM but never attaching it to an agent ERROR RECOVERY: - 401: API key is missing or invalid → configure_retell_api_key - 422: invalid model/prompt → use a listed model and non-empty prompt RELATED TOOLS: - list_retell_llms/get_retell_llm: Reuse or inspect existing configs - create_agent/update_agent: Attach the new llm_id to an agent - update_retell_llm: Modify this config later RETURNS: llm_id, general_prompt, begin_message, model, model_temperature, general_tools, timestamps.

Create a browser-based voice call session. Returns a web_call_link the user can open to talk to a Retell agent. WHEN TO USE: - User wants a voice call in their browser instead of their phone - Phone call route is blocked (e.g. phone number binding issue) - Testing or demoing an agent without using phone minutes EXAMPLE: { "agent_id": "agent_xxx", "agent_version": "latest", "retell_llm_dynamic_variables": { "customer_name": "Jane" } } COMMON MISTAKES: - Forgetting agent_version when testing a specific published version - Sharing an old web_call_link instead of creating a fresh session ERROR RECOVERY: - 401: API key is missing or invalid → configure_retell_api_key - 404: agent/version not found → list_agents, get_agent_versions, then publish_agent if needed - 422: bad dynamic variable shape → send a plain JSON object RELATED TOOLS: - list_agents/get_agent: Find the agent_id and response engine - update_retell_llm: Set the prompt before creating the test session - get_call: Retrieve transcript, analysis, and recording after the session RETURNS: call_id, web_call_link, status, agent_id, access_token. Share web_call_link with the user.

Get full configuration of a voice agent including voice, LLM, language, and versioning info. WHEN TO USE: - Before making a call, to check the agent's retell_llm_id (needed for update_retell_llm) - To verify which voice, language, or phone number an agent uses - To check the agent's current version and published state COMMON MISTAKES: - Updating the wrong LLM: use response_engine.llm_id from this tool before update_retell_llm - Assuming draft changes are live: use get_agent_versions/publish_agent to confirm ERROR RECOVERY: - 401: API key is missing or invalid → configure_retell_api_key - 404: agent_id not found → list_agents and retry with the returned ID RELATED TOOLS: - list_agents: Discover agent IDs - get_agent_versions: Inspect draft/published versions - update_retell_llm: Update the linked response_engine.llm_id - create_phone_call: Use this agent after validating config RETURNS: agent_id, agent_name, voice_id, response_engine.llm_id, language, version, published/versioning fields, phone number bindings when available.

List all versions of an agent, including draft and published versions. WHEN TO USE: - To check which version is currently published/live - To find the version number of a draft before publishing - To debug version mismatch issues causing 404 errors on calls COMMON MISTAKES: - Using override_agent_id without checking the matching override_agent_version here - Publishing/calling a stale version after updating the draft ERROR RECOVERY: - 401: API key is missing or invalid → configure_retell_api_key - 404: agent_id not found → list_agents and retry RELATED TOOLS: - publish_agent: Publish a draft version returned here - create_phone_call: Pass override_agent_version from this list - get_agent: Inspect the agent tied to these versions RETURNS: versions, count. Each version includes version number, published/live status, creation/update timestamps, and description when available.

Get details of a specific call including status, transcript, recording URL, and duration. WHEN TO USE: - After create_phone_call or create_web_call to monitor progress - To retrieve the full transcript after a call ends - To check call status: "registered" (queued), "ongoing" (live), "ended" (complete), "error" (failed) WORKFLOW: Poll every 5-10 seconds after creating a call until status is "ended" or "error". ERROR RECOVERY: - 401: API key is missing or invalid → configure_retell_api_key - 404: call_id not found → check the ID returned by create_phone_call/create_web_call or use list_calls RELATED TOOLS: - create_phone_call/create_web_call: Source of call_id - list_calls: Find recent call IDs if call_id is unknown - stop_call: End an ongoing call RETURNS: call_id, status, transcript, transcript_object, recording_url, call_analysis, duration_ms, disconnection_reason.

Get details of a specific phone number including its agent bindings. WHEN TO USE: - To check which agents are bound (inbound and outbound) to a specific number - To diagnose why create_phone_call returns 404 (missing outbound agent binding) - To confirm the bound agent_version before overriding call routing COMMON MISTAKES: - Checking only that the number exists; outbound calls require outbound_agents - Missing that the bound agent_version differs from the version you intend to use ERROR RECOVERY: - 401: API key is missing or invalid → configure_retell_api_key - 404: phone number not found → list_phone_numbers and use the exact E.164 value RELATED TOOLS: - list_phone_numbers: Discover available numbers - update_phone_number: Add/fix inbound or outbound bindings - get_agent_versions: Verify bound agent versions - create_phone_call: Use this phone_number as from_number RETURNS: phone_number, nickname, inbound_agents, outbound_agents, phone number config fields.

Get details of a Retell LLM response engine (prompt, model, tools). WHEN TO USE: - Inspect current prompt/model before update_retell_llm - Confirm which prompt an agent will use before a call - Debug why an agent said the wrong thing COMMON MISTAKES: - Looking at the agent only; the actual call instructions live in the Retell LLM - Editing a different LLM than the one returned by get_agent.response_engine.llm_id ERROR RECOVERY: - 401: API key is missing or invalid → configure_retell_api_key - 404: llm_id not found → get_agent/list_retell_llms and retry RELATED TOOLS: - get_agent: Find response_engine.llm_id for an agent - update_retell_llm: Change the prompt/model - list_retell_llms: Browse available LLM configs RETURNS: llm_id, general_prompt, begin_message, model, model_temperature, general_tools, timestamps.

List all configured voice agents in your Retell account. WHEN TO USE: - Discover available agents before making calls - Find agent IDs by name - Inventory check COMMON MISTAKES: - Guessing agent IDs from names; use the returned agent_id exactly - Choosing an agent without checking its response_engine.llm_id and versions via get_agent ERROR RECOVERY: - 401: API key is missing or invalid → configure_retell_api_key RELATED TOOLS: - get_agent: Inspect full config for a returned agent_id - get_agent_versions: Check published versions - create_phone_call/create_web_call: Use a verified agent_id RETURNS: agents, count. Each agent usually includes agent_id, agent_name, voice_id, response_engine, and timestamps.

List calls with filtering and pagination. Returns recent calls by default (newest first). WHEN TO USE: - Browse call history - Find calls by agent, date range, or status - Verify recent call activity FILTERING: - agent_id accepts an array of one or more agent IDs - filter_criteria timestamps accept Unix milliseconds (number) or a parseable date string (e.g. "2026-01-01"); date strings are converted to milliseconds before the API call - Example: { "limit": 20, "agent_id": ["agent_xxx"], "filter_criteria": { "after_start_timestamp": 1735689600000 } } COMMON MISTAKES: - Passing one agent_id as a string instead of an array - Using seconds for numeric timestamps; Retell expects milliseconds ERROR RECOVERY: - 401: API key is missing or invalid → configure_retell_api_key - 422: invalid filter shape → check agent_id is an array and numeric timestamps are milliseconds RELATED TOOLS: - get_call: Get transcript/recording/analysis for a returned call_id - list_agents: Find agent IDs for filtering - stop_call: End an ongoing call RETURNS: calls, count, pagination_key, has_more. Each call includes call_id, status, agent_id, timestamps, and call metadata.

List all phone numbers in your Retell account with their agent bindings. WHEN TO USE: - Before create_phone_call, to find available from_numbers - To check which agents are bound to which numbers - To verify outbound agent configuration TIP: The phone_number field (E.164 format) is what you pass as from_number in create_phone_call. The outbound_agents array shows which agent(s) are bound for outbound calls from this number. Check each outbound agent's agent_version before calling; version mismatches are a common 404 cause. COMMON MISTAKES: - Using a number that exists but has no outbound_agents binding - Ignoring agent_version on the binding and then overriding only agent_id during create_phone_call ERROR RECOVERY: - 401: API key is missing or invalid → configure_retell_api_key - 422: invalid pagination params → keep limit between 1 and 1000 RELATED TOOLS: - get_phone_number: Inspect one number's bindings - update_phone_number: Bind or rebind agents - create_phone_call: Use returned phone_number as from_number - get_agent_versions: Verify bound versions RETURNS: phone_numbers, count, pagination_key, has_more. Each number includes phone_number, inbound_agents, outbound_agents, nickname/config when available.

List all Retell LLM response engine configurations. WHEN TO USE: - Find llm_id values before get_retell_llm/update_retell_llm - Inventory prompt/model configurations - Decide whether to reuse an LLM or create a new one COMMON MISTAKES: - Updating an arbitrary llm_id without checking which agent uses it - Assuming list order implies which LLM is active; use get_agent to confirm bindings ERROR RECOVERY: - 401: API key is missing or invalid → configure_retell_api_key - 422: invalid pagination params → keep limit between 1 and 1000 RELATED TOOLS: - get_retell_llm: Inspect one returned llm_id - update_retell_llm: Change prompt/model - get_agent/list_agents: See which agents reference each LLM - create_retell_llm: Create a separate config when reuse is unsafe RETURNS: llms, count, pagination_key, has_more. Each LLM includes llm_id, prompt/model fields, and timestamps when available.

Browse all available TTS voices in Retell. WHEN TO USE: - Find voice IDs when creating or updating an agent - Compare providers/voice names before selecting a voice - Verify a voice_id still exists after a 404 from create_agent/update_agent COMMON MISTAKES: - Passing the display name instead of the exact voice_id - Reusing an old voice_id without checking it still exists ERROR RECOVERY: - 401: API key is missing or invalid → configure_retell_api_key RELATED TOOLS: - create_agent: Use a returned voice_id for a new agent - update_agent: Change an existing agent's voice_id RETURNS: voices, count. Each voice includes voice_id, voice_name/name, provider, accent/language/gender, and preview metadata when available.

Publish a specific agent version, making it the active/live version. WHEN TO USE: - After updating an agent's config or LLM, to make changes live - When create_phone_call returns 404 because the agent version is unpublished - When you need to activate a specific version CRITICAL: Agent updates go to the latest DRAFT version. They are NOT live until published. If calls fail with 404, check get_agent_versions and publish the correct version. WORKFLOW: 1. update_agent or update_retell_llm → changes the draft 2. get_agent_versions → find the version number of the draft 3. publish_agent → make it live COMMON MISTAKES: - Publishing the wrong version number; call get_agent_versions immediately before this - Assuming update_retell_llm alone publishes changes ERROR RECOVERY: - 401: API key is missing or invalid → configure_retell_api_key - 404: agent/version not found → list_agents/get_agent_versions - 422: version is invalid or not publishable → verify the draft version number RELATED TOOLS: - get_agent_versions: Find the version number to publish - update_agent/update_retell_llm: Make draft changes first - create_phone_call: Use the published version afterward RETURNS: ok, message confirming the agent_id and published version.

Stop an ongoing call immediately. WHEN TO USE: - User wants to end a call in progress - Call is stuck or behaving unexpectedly - Emergency stop COMMON MISTAKES: - Calling this on an already ended call; use get_call first if unsure ERROR RECOVERY: - 401: API key is missing or invalid → configure_retell_api_key - 404: call_id not found or no longer active → verify with list_calls/get_call RELATED TOOLS: - get_call: Check whether status is "ongoing" before stopping - list_calls: Find the active call_id RETURNS: ok, message. Retell returns HTTP 204 on success.

Update an existing agent's configuration (voice, name, response engine, language, etc.). WHEN TO USE: - Change voice, language, response engine, responsiveness, or backchannel behavior - Point an agent at a different Retell LLM NOTE: This updates the agent's latest DRAFT version. To make changes live, call publish_agent afterward. COMMON MISTAKES: - Updating the agent and immediately calling without publish_agent - Switching response_engine.llm_id without checking the LLM config first ERROR RECOVERY: - 401: API key is missing or invalid → configure_retell_api_key - 404: agent_id/voice_id/llm_id not found → use list_agents/list_voices/list_retell_llms - 422: invalid setting range → check numeric ranges on speed/responsiveness/sensitivity RELATED TOOLS: - get_agent: Inspect current config before changing - publish_agent/get_agent_versions: Publish and verify draft changes - update_retell_llm: Change prompt/model without replacing the response engine RETURNS: Updated agent object including agent_id, agent_name, voice_id, response_engine, language, draft/version fields.

Update agent bindings and settings for a phone number. WHEN TO USE: - To bind an agent to a phone number for outbound/inbound calls - To fix "404 Not Found" errors on create_phone_call (the number needs an outbound agent) - To change which agent handles calls on a number CRITICAL: After Retell's March 2026 update, phone numbers use weighted agent lists. Each binding needs agent_id, weight (must sum to 1), and optionally agent_version. EXAMPLE — bind agent to outbound calls: { "phone_number": "+14155551234", "outbound_agents": [{ "agent_id": "agent_xxx", "agent_version": 1, "weight": 1 }] } COMMON MISTAKES: - Omitting agent_version and accidentally binding the wrong/latest version - Setting weights that do not sum to 1 - Updating inbound_agents when the failure is outbound calling ERROR RECOVERY: - 401: API key is missing or invalid → configure_retell_api_key - 404: phone_number or agent_id not found → list_phone_numbers/list_agents - 422: invalid binding → include agent_id + weight, ensure weights sum to 1, verify agent_version RELATED TOOLS: - get_phone_number/list_phone_numbers: Inspect current bindings first - get_agent_versions: Choose a valid agent_version - publish_agent: Make the desired version live before binding - create_phone_call: Test outbound routing after updating RETURNS: phone_number, nickname, inbound_agents, outbound_agents, updated config fields.

Update a Retell LLM response engine's prompt, model, or behavior settings. WHEN TO USE: - Before making a call, to set the conversation instructions/prompt - To change the LLM model or temperature - To update the agent's opening message CRITICAL: This is the #1 most important step before any phone call. The general_prompt controls what the agent says. If you skip this, the agent will use the PREVIOUS call's prompt. WORKFLOW: 1. get_agent → find the agent's retell_llm_id (in response_engine.llm_id) 2. update_retell_llm → set the prompt and behavior 3. get_agent_versions/publish_agent if the agent version needs publishing 4. Wait 2-3 seconds for propagation 5. create_phone_call MODEL OPTIONS: gpt-4.1, gpt-4.1-mini, gpt-5, gpt-5-mini, gpt-5.5, claude-4.5-sonnet, claude-4.6-sonnet, claude-4.5-haiku, gemini-2.5-flash-lite, gemini-3.0-flash, gemini-3.1-flash-lite. EXAMPLE: { "llm_id": "llm_xxx", "general_prompt": "You are calling to confirm tomorrow's appointment. Be concise and polite.", "begin_message": "Hi, this is Alex calling to confirm your appointment.", "model": "gpt-5.5" } COMMON MISTAKES: - Skipping this before create_phone_call, causing the previous call's prompt to run - Updating the wrong llm_id; get it from get_agent.response_engine.llm_id - Forgetting to publish the agent/version after changing call behavior ERROR RECOVERY: - 401: API key is missing or invalid → configure_retell_api_key - 404: llm_id not found → get_agent or list_retell_llms - 422: invalid model/prompt/tools → use a listed model and valid JSON tool config RELATED TOOLS: - get_agent: Find the linked response_engine.llm_id - get_retell_llm: Inspect current prompt/model before changing - publish_agent/get_agent_versions: Make agent changes live - create_phone_call/create_web_call: Test the updated behavior RETURNS: llm_id, general_prompt, begin_message, model, model_temperature, general_tools, updated timestamps.