> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.agentphone.ai/documentation/guides/agents/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.agentphone.ai/_mcp/server. # Agents > Create and manage AI agent personas with phone numbers, voice modes, and system prompts Agents represent AI personas (e.g., Support Bot, Sales Agent) that can have phone numbers attached to them. Each agent can be configured with a voice mode, system prompt, greeting message, and voice selection. ## Voice modes Agents support two voice modes for handling calls: * **`webhook`** (default) -- Forwards call transcripts to your configured webhook URL. You process the transcript with your own AI backend and return a response. * **`hosted`** -- Uses a built-in LLM with the agent's `systemPrompt`. No webhook is needed for voice conversations; the platform handles the AI interaction directly. ## Voice tuning Beyond the voice mode, a handful of agent fields shape how a call actually sounds and behaves. They apply to both `webhook` and `hosted` modes (the [Calls](/documentation/guides/calls#voice-capabilities) guide describes the underlying engine). Set them on `POST /v1/agents` or change them anytime with `PATCH /v1/agents/{id}` — voice infrastructure re-provisions with no downtime. | Goal | Field(s) | Notes | | --------------------- | ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | | Pick the voice | `voice` | A TTS voice identifier. List options with [`GET /v1/agents/voices`](#list-available-voices). | | Pace the speech | `voiceSpeed` | `1.0` normal, `0.5` slow, `2.0` fast. Slower can improve clarity for older callers or noisy lines. | | Control interruptions | `interruptionSensitivity` | Higher = the agent yields to the caller faster (more natural, but cuts off on background noise). Lower = the agent holds the floor. Default `0.8`. | | Backchanneling | `enableBackchannel` | Natural "uh-huh"/"mhmm" cues while the caller talks. Turn off for IVR-style or read-only flows. | | Transcription quality | `sttMode` | `"fast"` (default) for lowest latency, `"accurate"` when names, addresses, or numbers must be exact (\~200 ms slower). | | Noisy callers | `denoisingMode` | `"noise-and-background-speech-cancellation"` for callers in cars, cafes, or near a TV. | | Ambience | `ambientSound` | Subtle background (`office`, `coffee-shop`, `outdoor`) so silence between turns feels less synthetic. | | Patience | `maxSilenceMs` | How long to wait on a silent line before hanging up. Raise for hold-music/IVR navigation. | | Texting mid-call | `enableMessaging` | Lets a hosted agent send a follow-up text during the call (e.g. a confirmation link). | | Voicemail | `voicemailMessage` | Spoken if an outbound call lands in voicemail. | | Transfers | `transferNumber` | Where a `transfer` action routes the call. See [Calls](/documentation/guides/calls#webhook-response-format). | > **Tip** > > Good defaults for a natural-sounding assistant: leave `interruptionSensitivity` near `0.8`, keep `enableBackchannel` on, and use `sttMode: "accurate"` only when you need exact capture of spelled-out details. Tune one field at a time and listen back with [call recordings](/documentation/guides/calls#call-recording). ### Language Set `language` to a BCP-47 locale to run recognition and synthesis in that language. AgentPhone supports 63 locales, including: | Locale | Language | Locale | Language | | ------- | ------------------- | -------- | ----------------------- | | `en-US` | English (US) | `es-ES` | Spanish (Spain) | | `en-GB` | English (UK) | `es-419` | Spanish (Latin America) | | `en-AU` | English (Australia) | `fr-FR` | French (France) | | `en-IN` | English (India) | `pt-BR` | Portuguese (Brazil) | | `de-DE` | German | `it-IT` | Italian | | `ja-JP` | Japanese | `ko-KR` | Korean | | `zh-CN` | Chinese (Mandarin) | `hi-IN` | Hindi | Pick a `voice` that matches the locale for the most natural result. The full list of accepted locale codes is in the [API Reference](/api-reference) under the agent `language` field. ## Create agent Create a new agent. ``` POST /v1/agents ``` ### Request body | Field | Type | Required | Description | | ------------------------- | --------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `name` | string | Yes | Name of the agent | | `description` | string or null | No | Description of what the agent does | | `voiceMode` | string or null | No | Voice handling mode: `"webhook"` (default) or `"hosted"` | | `systemPrompt` | string or null | No | System prompt for the built-in LLM (used when `voiceMode` is `"hosted"`) | | `beginMessage` | string or null | No | Initial greeting message spoken when a call connects | | `voice` | string or null | No | Voice identifier for text-to-speech. List valid IDs with [`GET /v1/agents/voices`](#list-available-voices); the platform default voice is used if omitted. | | `modelTier` | string or null | No | Quality/latency tradeoff for hosted-mode agents: `"turbo"` (lowest latency, best for simple tasks), `"balanced"` (default, good mix of speed and quality), or `"max"` (highest quality, best for complex reasoning) | | `sttMode` | string or null | No | Speech-to-text mode: `"fast"` (default) optimizes for latency, `"accurate"` optimizes for transcription accuracy (\~200ms additional latency) | | `ambientSound` | string or null | No | Background ambience to mask synthetic silence between turns: `"none"` (default), `"office"`, `"coffee-shop"`, or `"outdoor"` | | `denoisingMode` | string or null | No | Audio denoising level: `"noise-cancellation"` (default) or `"noise-and-background-speech-cancellation"` (more aggressive, for callers in cars, cafes, or near TVs). | | `transferNumber` | string or null | No | Phone number to transfer calls to when the agent triggers a transfer action | | `voicemailMessage` | string or null | No | Message to play when a call goes to voicemail | | `voiceSpeed` | number or null | No | Speech speed multiplier. `1.0` is normal pace, `0.5` is half speed, `2.0` is double. Range 0.5–2.0. | | `interruptionSensitivity` | number or null | No | How easily callers can interrupt (barge in). `0` means the agent is never interrupted, `1` stops at the first sound. Default `0.8`. Range 0.0–1.0. | | `enableBackchannel` | boolean or null | No | When `true`, the agent interjects short cues like "uh-huh" while the caller is speaking. Set `false` to stay silent until the caller finishes. Default `true`. | | `maxSilenceMs` | integer or null | No | Hang up after this many milliseconds of caller silence. Default `600000` (10 min). Raise for IVR/hold-music flows, lower to fail fast on dead lines. Range 10000–3600000. | | `enableMessaging` | boolean or null | No | When `true`, hosted-mode agents can send and read SMS/iMessage during a call. Default `true`. | | `language` | string or null | No | BCP-47 locale for speech recognition and synthesis, e.g. `"en-US"`, `"es-ES"`, `"ja-JP"`. See [Language](#language). | See [Voice tuning](#voice-tuning) below for how the voice-related fields shape a call. ### Example ```bash curl -X POST "https://api.agentphone.ai/v1/agents" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "Support Bot", "description": "Handles customer support inquiries", "voiceMode": "hosted", "systemPrompt": "You are a helpful customer support agent for Acme Corp.", "beginMessage": "Hello! Thanks for calling Acme Corp. How can I help you today?" }' ``` ```json { "id": "agt_abc123", "name": "Support Bot", "description": "Handles customer support inquiries", "voiceMode": "hosted", "systemPrompt": "You are a helpful customer support agent for Acme Corp.", "beginMessage": "Hello! Thanks for calling Acme Corp. How can I help you today?", "voice": "custom_voice_ea22ba5fdfaa18f39c274851c1", "createdAt": "2025-01-15T10:30:00Z", "numbers": [] } ``` ## List agents List all agents for this project. ``` GET /v1/agents ``` ### Query parameters | Parameter | Type | Required | Default | Description | | --------- | ------- | -------- | ------- | ------------------------------------- | | `limit` | integer | No | 20 | Number of results to return (max 100) | | `offset` | integer | No | 0 | Number of results to skip (min 0) | ### Example ```bash curl -X GET "https://api.agentphone.ai/v1/agents?limit=10&offset=0" \ -H "Authorization: Bearer YOUR_API_KEY" ``` ## Get agent Get a single agent with its attached numbers. ``` GET /v1/agents/{agent_id} ``` ### Example ```bash curl -X GET "https://api.agentphone.ai/v1/agents/agt_abc123" \ -H "Authorization: Bearer YOUR_API_KEY" ``` ## Update agent Update an agent's configuration. Use this to change voice mode, system prompt, greeting, or voice. ``` PATCH /v1/agents/{agent_id} ``` All fields are optional. Only include the fields you want to update. ### Example ```bash curl -X PATCH "https://api.agentphone.ai/v1/agents/agt_abc123" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "systemPrompt": "You are a friendly sales assistant for Acme Corp.", "voiceMode": "hosted" }' ``` ## Delete agent Delete an agent. Phone numbers, conversations, and calls associated with the agent will have their agent reference cleared but will **not** be deleted. ``` DELETE /v1/agents/{agent_id} ``` ### Example ```bash curl -X DELETE "https://api.agentphone.ai/v1/agents/agt_abc123" \ -H "Authorization: Bearer YOUR_API_KEY" ``` ## Attach number to agent Attach an existing phone number to an agent. The number must belong to the same project and must not be released. ``` POST /v1/agents/{agent_id}/numbers ``` ### Request body | Field | Type | Required | Description | | ---------- | ------ | -------- | ------------------------------------ | | `numberId` | string | Yes | The ID of the phone number to attach | ### Example ```bash curl -X POST "https://api.agentphone.ai/v1/agents/agt_abc123/numbers" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"numberId": "num_xyz789"}' ``` ## List agent conversations List all conversations for a specific agent. ``` GET /v1/agents/{agent_id}/conversations ``` ### Example ```bash curl -X GET "https://api.agentphone.ai/v1/agents/agt_abc123/conversations?limit=10" \ -H "Authorization: Bearer YOUR_API_KEY" ``` ## List agent calls List all calls for a specific agent. ``` GET /v1/agents/{agent_id}/calls ``` ### Example ```bash curl -X GET "https://api.agentphone.ai/v1/agents/agt_abc123/calls?limit=5" \ -H "Authorization: Bearer YOUR_API_KEY" ``` ## List available voices List all available TTS voices that can be used with the `voice` field when creating or updating agents. ``` GET /v1/agents/voices ``` ### Example ```bash curl -X GET "https://api.agentphone.ai/v1/agents/voices" \ -H "Authorization: Bearer YOUR_API_KEY" ``` The response is `{"data": [...]}` where each entry includes `voice_id`, `voice_name`, `gender`, `accent`, and a `preview_audio_url`. Use a returned `voice_id` in the `voice` field when creating agents, updating agents, or making outbound calls. Unknown IDs are rejected with a validation error when creating or updating agents; the per-call `voice` override is not validated against the catalog, so always pass an ID from this list. > Create and manage AI agent personas with phone numbers, voice modes, and system prompts