Create Agent | Resemble | Documentation

Create a new voice agent with ASR, TTS, LLM, and turn-taking configurations.

HTTP Request

$ POST https://app.resemble.ai/api/v2/agents

Request Body

Attribute	Type	Required	Description
name	string	Yes	Name of the agent
voice_uuid	string	Yes	UUID of the voice to use for TTS
phone_number_id	integer	No	ID of phone number to link to this agent
languages	array	No	Supported languages (default: [“en-US”])
dynamic_variables	object	No	Key-value pairs for runtime variable substitution
asr	object	No	ASR configuration
turn	object	No	Turn-taking configuration
llm	object	No	LLM configuration
webhooks	array	No	Array of webhook configurations
system_tools	object	No	System tool configurations

ASR Configuration

Attribute	Type	Required	Default	Description
model	string	Yes	-	ASR model to use
provider	string	No	”deepgram”	ASR provider
user_input_audio_format	string	No	”pcm_16000”	Audio format: pcm_8000, pcm_16000, pcm_22050, pcm_24000, pcm_44100, pcm_48000, ulaw_8000
keywords	array	No	[]	Keywords for improved recognition

Turn Configuration

Attribute	Type	Required	Default	Description
turn_timeout	integer	No	7	Seconds before turn ends (≥ 0)
silence_end_call_timeout	integer	No	-1	Seconds of silence before ending call (-1 = disabled, ≥ 0 = enabled)
mode	string	No	”silence”	Turn detection mode (currently only “silence” supported)

LLM Configuration

Attribute	Type	Required	Default	Description
prompt	string	No	null	System prompt for the LLM
provider	string	No	null	LLM provider (e.g., “openai”, “anthropic”)
model	string	No	null	LLM model (e.g., “gpt-4o”, “claude-3-5-sonnet-20241022”)
reasoning_effort	string	No	null	Reasoning effort level (model-specific)
temperature	float	No	0.3	Temperature for response generation
timezone	string	No	null	Timezone for date/time operations
built_in_tools	object	No		Built-in tool configurations

Webhooks Configuration

Each webhook object requires:

Attribute	Type	Required	Description
webhook_type	string	Yes	Type: “pre_call” or “post_call”
webhook_config	object	Yes	Webhook configuration (see webhook section)

System Tools Configuration

System tools are automatically created for each agent. You can configure them:

Tool Name	Description
end_call	Ends the current call
transfer_to_number	Transfers call to another number
voicemail_detection	Detects voicemail

Each system tool accepts:

Attribute	Type	Default	Description
active	boolean	true	Whether the tool is enabled
disable_interruptions	boolean	false	Prevent user interruptions during tool use
force_pre_tool_speech	boolean	false	Force agent to speak before using tool

Example Request

$ curl --request POST "https://app.resemble.ai/api/v2/agents" \
>   -H "Authorization: Bearer YOUR_API_TOKEN" \
>   -H "Content-Type: application/json" \
>   --data '{
>     "name": "Customer Support Agent",
>     "voice_uuid": "abc123",
>     "phone_number_id": 1,
>     "languages": ["en-US"],
>     "dynamic_variables": {
>       "customer_name": "{{customer_name}}",
>       "account_id": "{{account_id}}"
>     },
>     "asr": {
>       "provider": "deepgram",
>       "model": "nova-2",
>       "user_input_audio_format": "pcm_16000",
>       "keywords": ["resemble", "account"]
>     },
>     "turn": {
>       "turn_timeout": 7,
>       "silence_end_call_timeout": -1,
>       "mode": "silence"
>     },
>     "llm": {
>       "prompt": "You are a helpful customer support agent.",
>       "provider": "openai",
>       "model": "gpt-4o",
>       "temperature": 0.3,
>       "timezone": "America/New_York"
>     },
>     "webhooks": [
>       {
>         "webhook_type": "pre_call",
>         "webhook_config": {
>           "api_schema": {
>             "url": "https://example.com/pre-call",
>             "method": "POST"
>           },
>           "assignments": []
>         }
>       }
>     ],
>     "system_tools": {
>       "end_call": {
>         "active": true,
>         "disable_interruptions": false,
>         "force_pre_tool_speech": false
>       }
>     }
>   }'

Response (Success)

1 {
2   "success": true,
3   "item": {
4     "agent": {
5       "name": "Customer Support Agent",
6       "uuid": "550e8400-e29b-41d4-a716-446655440000",
7       "languages": ["en-US"],
8       "dynamic_variables": {
9         "customer_name": "{{customer_name}}",
10         "account_id": "{{account_id}}"
11       },
12       "created_at": "2025-01-27T10:00:00Z",
13       "updated_at": "2025-01-27T10:00:00Z",
14       "last_active_at": null,
15       "calls_today": 0,
16       "status": "inactive"
17     },
18     "asr": {
19       "provider": "deepgram",
20       "model": "nova-2",
21       "user_input_audio_format": "pcm_16000",
22       "keywords": ["resemble", "account"]
23     },
24     "tts": {
25       "voice_uuid": "abc123",
26       "voice_name": "Professional Voice"
27     },
28     "turn": {
29       "turn_timeout": 7,
30       "silence_end_call_timeout": -1,
31       "mode": "silence"
32     },
33     "llm": {
34       "prompt": "You are a helpful customer support agent.",
35       "provider": "openai",
36       "model": "gpt-4o",
37       "reasoning_effort": null,
38       "temperature": 0.3,
39       "timezone": "America/New_York",
40       "built_in_tools": {}
41     },
42     "phone_numbers": [
43       {
44         "id": 1,
45         "phone_number": "+14155551234",
46         "label": "Support Line",
47         "supports_inbound": true,
48         "supports_outbound": false,
49         "provider": "twilio",
50         "outbound_trunk": {},
51         "inbound_trunk": {},
52         "created_at": "2025-01-15T10:30:00Z",
53         "updated_at": "2025-01-15T10:30:00Z"
54       }
55     ],
56     "tools_count": 3,
57     "webhooks_count": 1
58   },
59   "message": "Agent created successfully"
60 }

Response (Error)

1 {
2   "success": false,
3   "errors": {
4     "name": ["can't be blank"],
5     "voice_uuid": ["Voice not found or not accessible"],
6     "phone_number_id": ["Phone number is already linked to agent 'Other Agent'"],
7     "dynamic_variables": ["Dynamic variables must be a flat hash. Key 'nested' contains a nested object or array."],
8     "asr.model": ["ASR provider/model combination 'deepgram/invalid-model' is not supported"],
9     "turn.turn_timeout": ["must be greater than or equal to 0"],
10     "llm.temperature": ["is not a number"]
11   },
12   "message": "Failed to create agent"
13 }

Validation Rules

Agent Validations

name: Required, cannot be empty
voice_uuid: Required, must reference an existing voice in your team
languages: Must be one of: “en-US” (currently only language supported)
phone_number_id: If provided, must reference an existing phone number that is not already linked to another agent
dynamic_variables:
- Keys: Max 64 characters, cannot be reserved words (proto, constructor, prototype)
- Values: Max 2048 characters, must be scalar (string, number, boolean, or null)
- Must be a flat hash (no nested objects or arrays)

ASR Validations

provider + model combination: Must be a supported ASR capability (check /agents/capabilities endpoint)
user_input_audio_format: Must be one of the supported formats
keywords: Array of strings

LLM Validations

provider + model combination: Must be a supported LLM capability (check /agents/capabilities endpoint)
temperature: Must be a float value
timezone: Must be a valid timezone string or null

Turn Validations

turn_timeout: Must be ≥ 0
silence_end_call_timeout: Must be ≥ -1 (where -1 = disabled)
mode: Must be “silence”

Interoperability Validations

The system validates that all components (ASR, LLM, Turn, TTS) are compatible with each other.