Create a reusable voice agent. Returns the full agent record, including a
generated id you use to connect over the WebSocket (session.update with
agent_id).
POST
/
v1
/
agents
Create an agent
curl --request POST \ --url https://agents.assemblyai.com/v1/agents \ --header 'Authorization: <api-key>' \ --header 'Content-Type: application/json' \ --data @- <<EOF{ "name": "Support Assistant", "system_prompt": "You are a friendly support agent. Keep responses under two sentences.", "voice": { "voice_id": "alba" }, "greeting": "Hi, how can I help?", "input": { "type": "audio", "format": { "encoding": "audio/pcm", "sample_rate": 24000 }, "turn_detection": {}, "keyterms": [ "<string>" ] }, "output": { "type": "audio", "voice": "alba", "format": { "encoding": "audio/pcm", "sample_rate": 24000 }, "volume": 123 }, "tools": [ { "name": "get_weather", "description": "Get current weather for a location. Use whenever the user asks about weather.", "parameters": { "type": "object", "properties": { "order_id": { "type": "string", "description": "The customer's order ID.", "examples": [ "AB-12345" ], "pattern": "[A-Z]{2}-\\d{5}" } }, "required": [ "order_id" ] }, "timeout_seconds": 120, "execution_mode": "interactive" } ], "llm": [ { "base_url": "https://api.openai.com/v1", "model": "gpt-4o-mini", "api_key": "<string>" } ], "pre_connect_requests": [ { "http": { "url": "https://api.example.com/weather", "http_method": "POST", "headers": {} }, "sends": [ "caller_number" ], "returns": [ { "name": "patient_name", "path": "patient.first_name", "default": "there" } ], "timeout_ms": 600, "allow_overrides": [ "greeting" ] } ]}EOF
Your AssemblyAI API key in the Authorization header. The raw key works directly; a Bearer prefix is also accepted.
Body
application/json
name
string
required
Display name for the agent.
Example:
"Support Assistant"
system_prompt
string
required
The agent's instructions. Write voice-first.
Example:
"You are a friendly support agent. Keep responses under two sentences."
voice
object
required
Show child attributes
greeting
string | null
Spoken on connect; sent straight to TTS. Omit to listen first.
Example:
"Hi, how can I help?"
input
object
Audio input configuration. Defaults to PCM at 24 kHz if omitted.
Show child attributes
output
object
Audio output configuration. Defaults to PCM at 24 kHz with the agent's voice.
Show child attributes
tools
object[]
Tools the agent can call.
Show child attributes
llm
object[]
Connect your own OpenAI-compatible LLM instead of AssemblyAI's
managed model. Provide at most one config; omit to use the managed
LLM. Multiple configs (fallbacks) are not yet supported.
Maximum array length: 1
Show child attributes
pre_connect_requests
object[]
HTTPS lookups the platform runs, in order, before answering an inbound
phone call. Each can send the call's facts (such as the caller's
number) and values an earlier entry captured, and captures values from
its JSON response for the greeting and the conversation. Telephony
only; ignored on WebSocket sessions. See
Pre-connect requests.
Maximum array length: 2
Show child attributes
Response
Agent created.
A stored voice agent.
id
string
Example:
"7ad24396-b822-4dca-871a-be9cc4781cf9"
name
string
Example:
"Support Assistant"
system_prompt
string
greeting
string | null
voice
object
Show child attributes
input
object
Audio input configuration. Defaults to PCM at 24 kHz if omitted.
Show child attributes
output
object
Audio output configuration. Defaults to PCM at 24 kHz with the agent's voice.
Show child attributes
tools
object[]
Show child attributes
llm
object[]
Connected LLM, if any. The api_key is write-only and never returned.
Show child attributes
created_at
string<date-time>
updated_at
string<date-time>
pre_connect_requests
object[]
The declared pre-connect requests. Header values are never returned.
Show child attributes
Was this page helpful?
{"docsConfig":{"theme":"aspen","$schema":"https://mintlify.com/docs.json","name":"AssemblyAI","description":"AssemblyAI provides production-ready Voice AI models for speech-to-text, speaker detection, sentiment analysis, and more. Build with pre-recorded or streaming audio using REST APIs and WebSockets.","colors":{"primary":"#614fd2","light":"#887bdd","dark":"#614fd2"},"logo":{"light":"https://mintcdn.com/assemblyai-fff14a6f/vMuNaI_PbWUbVeV0/assets/assemblyai-lockup-primary.svg?fit=max\u0026auto=format\u0026n=vMuNaI_PbWUbVeV0\u0026q=85\u0026s=808d2a677e2536423045d44b3f330ac2","dark":"https://mintcdn.com/assemblyai-fff14a6f/vMuNaI_PbWUbVeV0/assets/assemblyai-lockup-secondary.svg?fit=max\u0026auto=format\u0026n=vMuNaI_PbWUbVeV0\u0026q=85\u0026s=065ec1618693f8650241242ec62ed0ad","href":"https://www.assemblyai.com"},"favicon":"https://mintcdn.com/assemblyai-fff14a6f/6OQYF4QMRVQRoCb1/assets/favicon.png?fit=max\u0026auto=format\u0026n=6OQYF4QMRVQRoCb1\u0026q=85\u0026s=74b6b6a7321938bd113d4a271e06068d","api":{"openapi":["openapi.yaml","api-reference/specs/llm-gateway.yaml","api-reference/specs/streaming-token.yaml"],"asyncapi":["api-reference/specs/streaming.yaml","api-reference/specs/streaming-tts.yaml"]},"background":{"color":{"light":"#fdfcf8","dark":"#1d1b16"}},"navbar":{"links":[{"href":"https://www.assemblyai.com/playground","label":"Playground"},{"href":"https://www.assemblyai.com/changelog","label":"Changelog"}],"primary":{"type":"button","label":"Sign In","href":"https://www.assemblyai.com/dashboard/login"}},"footer":{"socials":{"x":"https://x.com/AssemblyAI","github":"https://github.com/AssemblyAI","linkedin":"https://www.linkedin.com/company/assemblyai"},"links":[{"header":"Legal","items":[{"label":"Terms of Service","href":"https://www.assemblyai.com/legal/terms-of-service"},{"label":"Privacy Policy","href":"https://www.assemblyai.com/legal/privacy-policy"},{"label":"Trust Center","href":"https://app.vanta.com/assemblyai/trust/7n80syl8zln1bn1qm3x8eg"},{"label":"Subprocessors","href":"https://app.vanta.com/assemblyai/trust/7n80syl8zln1bn1qm3x8eg/subprocessors"},{"label":"Do not sell my Personal Information","href":"#privacy-choices"}]}]},"seo":{"metatags":{"canonical":"https://www.assemblyai.com/docs"}},"fonts":{"heading":{"family":"GT Standard","weight":600,"source":"https://www.assemblyai.com/_aai/fonts/rebrand/GT-Standard-M-Semibold.woff2","format":"woff2"},"body":{"family":"GT Standard","weight":400,"source":"https://www.assemblyai.com/_aai/fonts/rebrand/GT-Standard-M-Regular.woff2","format":"woff2"}},"icons":{"library":"fontawesome"},"banner":{"content":"**New** AssemblyAI-TTS-1: Text-to-speech for voice agents. [Learn more](https://www.assemblyai.com/docs/tts/getting-started/quickstart)","dismissible":true},"contextual":{"options":["copy","view","chatgpt","claude","download-spec"],"display":"header"},"styling":{"latex":true},"navigation":{"pages":[]}},"deployment":{"deploymentMetadataValue":{"subdomain":"assemblyai-fff14a6f","hasAudioNarration":false,"actualSubdomain":"assemblyai-fff14a6f","customDomains":["assemblyai.com"],"gitSource":{"type":"github","owner":"assemblyai","repo":"assemblyai-docs","deployBranch":"master","contentDirectory":"","isPrivate":true,"mountPath":"","label":""},"feedback":{"thumbs":true,"agentFeedback":true},"entitlements":{"AI_CHAT":{"status":"ENABLED"},"REMOVE_BRANDING":{"status":"ENABLED"},"CONTEXTUAL_FEEDBACK":{"status":"ENABLED"},"CODE_SNIPPET_FEEDBACK":{"status":"ENABLED"},"WEB_MCP":{"status":"ENABLED"},"NARRATION":{"status":"ENABLED"}},"buildId":"6b011db2c8c6952b3aeeff7a","clientVersion":"0.0.4270","searchFilterCounts":[{"language":"default","tag":"Overview","count":121},{"language":"default","tag":"FAQ","count":97},{"language":"default","tag":"Pre-recorded STT","count":75},{"language":"default","tag":"Guides","count":60},{"language":"default","tag":"Real-time STT","count":50},{"language":"default","tag":"Tutorials","count":48},{"language":"default","tag":"Pre-recorded audio","count":47},{"language":"default","tag":"LLM Gateway","count":45},{"language":"default","tag":"API reference","count":36},{"language":"default","tag":"Features","count":35}]},"assistantConfig":{"enableAskAiButton":false,"enableStarterQuestions":false,"enableContextualStarterQuestions":false,"enableAskAiSearchBar":true,"attachments":{"status":"DISABLED"}},"basePath":"/docs","hasChatPermissions":true,"hasWebMcpPermissions":true,"toggles":[{"name":"kill-isr","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"custom-rbac-roles","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"agent-mintlify-slack","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"agent-integrations-settings","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"rbac-expansion","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automations-pr-grouping","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"custom-prefix","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"analytics-v7","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"user-flows-analytics","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"no-publish-flow","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-onboarding","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"snapshot-serving-live","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"stripTemperatureMiddleware","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"support-platform-pylon-zendesk","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"snapshot-serving","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"instant-rollback","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"granular-notifications-server","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"granular-notifications","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automations-fable","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"fixed-ai-action-pricing","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"site-roles","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automation-resolve-merge-conflict","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"scoped-publishing","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"mintql","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"page-level-analytics","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-version-history-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"billing-page-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"full-page-search","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workspace-projects","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"assistant-v5","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"fork-pr-previews","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"revalidation-jwt","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-sso-scim","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"hobby-abuse-scan","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"dashboard-inbox","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-signup","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"turbopuffer-dual-write","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-enabled","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"approve-review-flow","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-metadata","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"sso-setup-deadline-banner","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"turbopuffer-serve","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"live-agents","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"starter-pricing","enabled":true,"variant":{"name":"control","enabled":true,"payload":{"type":"string","value":"control"},"feature_enabled":true},"impressionData":false},{"name":"llms-txt-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"wildcard-email-auth","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false}],"googleFontsInlined":false},"customCss":[{"filePath":"style.css","content":"@font-face{font-family:\"GT Standard\";src:url(\"https://www.assemblyai.com/_aai/fonts/rebrand/GT-Standard-M-Regular.woff2\")\n format(\"woff2\"),\n url(\"https://www.assemblyai.com/docs/assets/GT-Standard-M-Regular.woff2\")\n format(\"woff2\"),\n url(\"/assets/GT-Standard-M-Regular.woff2\") format(\"woff2\");font-weight:400;font-style:normal;font-display:swap}@font-face{font-family:\"GT Standard\";src:url(\"https://www.assemblyai.com/_aai/fonts/rebrand/GT-Standard-M-Medium.woff2\")\n format(\"woff2\"),\n url(\"https://www.assemblyai.com/docs/assets/GT-Standard-M-Medium.woff2\")\n format(\"woff2\"),\n url(\"/assets/GT-Standard-M-Medium.woff2\") format(\"woff2\");font-weight:500;font-style:normal;font-display:swap}@font-face{font-family:\"GT Standard\";src:url(\"https://www.assemblyai.com/_aai/fonts/rebrand/GT-Standard-M-Semibold.woff2\")\n format(\"woff2\"),\n url(\"https://www.assemblyai.com/docs/assets/GT-Standard-M-Semibold.woff2\")\n format(\"woff2\"),\n url(\"/assets/GT-Standard-M-Semibold.woff2\") format(\"woff2\");font-weight:600;font-style:normal;font-display:swap}@font-face{font-family:\"Modern Gothic Mono\";src:url(\"https://www.assemblyai.com/_aai/fonts/rebrand/ModernGothicMono-Light.woff2\")\n format(\"woff2\");font-weight:300;font-style:normal;font-display:swap}@font-face{font-family:\"Modern Gothic Mono\";src:url(\"https://www.assemblyai.com/_aai/fonts/rebrand/ModernGothicMono-Regular.woff2\")\n format(\"woff2\");font-weight:400;font-style:normal;font-display:swap}@font-face{font-family:\"Modern Gothic Mono\";src:url(\"https://www.assemblyai.com/_aai/fonts/rebrand/ModernGothicMono-Medium.woff2\")\n format(\"woff2\");font-weight:500;font-style:normal;font-display:swap}@font-face{font-family:\"Modern Gothic Mono\";src:url(\"https://www.assemblyai.com/_aai/fonts/rebrand/ModernGothicMono-Italic.woff2\")\n format(\"woff2\");font-weight:400;font-style:italic;font-display:swap}html:root{--font-family-body-custom: \"GT Standard\", -apple-system, BlinkMacSystemFont,\n \"Segoe UI\", sans-serif;--font-family-headings-custom: \"GT Standard\", -apple-system, BlinkMacSystemFont,\n \"Segoe UI\", sans-serif}code,kbd,samp,pre,pre code,pre code span{font-family:\"Modern Gothic Mono\", \"JetBrains Mono\", ui-monospace, SFMono-Regular,\n Menlo, Consolas, monospace!important}html{overflow-y:scroll;scrollbar-gutter:stable}pre,pre code,pre code span{font-size:0.75rem!important;line-height:1.5!important}:not(pre)>code{font-size:0.75rem!important;line-height:inherit!important}[data-nav-tag=\"WSS\"]{color:#614fd2!important;background-color:rgba(136, 123, 221, 0.14)!important;font-size:0.55rem!important}:is(.dark) [data-nav-tag=\"WSS\"]{color:#887bdd!important}div:has(>.nav-tag-pill>[data-nav-tag=\"WSS\"]){order:-1}.nav-tag-pill:has(>[data-nav-tag=\"WSS\"]){width:2.375rem;justify-content:flex-start}.ws-endpoint{display:flex;align-items:center;gap:0.625rem;margin:1rem 0 1.75rem;padding:0.5rem 0.75rem;border:1px solid rgba(0, 0, 0, 0.08);border-radius:0.5rem;background:rgba(0, 0, 0, 0.02);font-size:0.875rem;overflow-x:auto}:is(.dark) .ws-endpoint{border-color:rgba(255, 255, 255, 0.1);background:rgba(255, 255, 255, 0.03)}.ws-endpoint-badge{flex:none;font-weight:700;font-size:0.75rem;letter-spacing:0.02em;color:#614fd2;background:rgba(136, 123, 221, 0.14);padding:0.1875rem 0.5rem;border-radius:0.375rem}:is(.dark) .ws-endpoint-badge{color:#887bdd}.ws-endpoint-url{font-family:ui-monospace, SFMono-Regular, \"SF Mono\", Menlo, Consolas, monospace;white-space:nowrap}#assistant-entry,:is(.dark) #assistant-entry{background-color:#614fd2!important;filter:none!important}#assistant-entry:hover,:is(.dark) #assistant-entry:hover{background-color:#614fd2!important;opacity:0.9;filter:none!important}#assistant-entry span,#assistant-entry svg,:is(.dark) #assistant-entry span,:is(.dark) #assistant-entry svg{color:#ffffff!important}.callout strong{font-weight:700}*{-webkit-font-smoothing:antialiased;-moz-osx-font-smoothing:grayscale;-o-font-smoothing:antialiased}.katex-display{overflow-x:visible!important;overflow-y:visible!important}.katex-display>.katex{display:flex!important;justify-content:center;width:100%!important;overflow-x:visible!important;overflow-y:visible!important}.katex-display>.katex>.katex-html{display:inline-block!important;width:auto!important;max-width:100%;overflow-x:visible!important;overflow-y:visible!important}.card-logo-icon{display:block;width:1.5rem!important;height:1.5rem!important;min-width:1.5rem;max-width:1.5rem;max-height:1.5rem;margin:0!important;object-fit:contain;object-position:center;vertical-align:middle}.card-logo-icon-livekit{transform:scale(0.9)}.card-logo-icon-pipecat{transform:scale(1.12)}.card-logo-icon-livekit,.card-logo-icon-pipecat,.card-logo-icon-vercel{color:#614fd2}:is(.dark) .card-logo-icon-livekit,:is(.dark) .card-logo-icon-pipecat,:is(.dark) .card-logo-icon-vercel{color:#887bdd}.recommended-pill{background:#614fd2;color:#fff;padding:2px 8px;border-radius:9999px;font-size:0.7rem;font-weight:600;margin-left:6px;vertical-align:middle;white-space:nowrap}:is(.dark) .recommended-pill{background:#614fd2}.preview-pill{background:#b45309;color:#fff;padding:2px 8px;border-radius:9999px;font-size:0.7rem;font-weight:600;margin-left:6px;vertical-align:middle;white-space:nowrap}:is(.dark) .preview-pill{background:#b45309}table code{white-space:nowrap}"}]}
{"page":{"pagePath":"voice-agents/voice-agent-api/api-spec/create-agent","slug":"/voice-agents/voice-agent-api/api-spec/create-agent","pageMetadata":{"title":"Create an agent","og.description":"Create a reusable voice agent.","openapi":"api-reference/specs/agents.yaml POST /v1/agents","description":"Create a reusable voice agent. Returns the full agent record, including a\ngenerated `id` you use to connect over the WebSocket (`session.update` with\n`agent_id`).\n","href":"/voice-agents/voice-agent-api/api-spec/create-agent","hidden":true},"description":{"compiledSource":"\"use strict\";\nconst {jsx: _jsx, jsxs: _jsxs} = arguments[0];\nconst {useMDXComponents: _provideComponents} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n code: \"code\",\n p: \"p\",\n ..._provideComponents(),\n ...props.components\n };\n return _jsxs(_components.p, {\n children: [\"Create a reusable voice agent. Returns the full agent record, including a\\ngenerated \", _jsx(_components.code, {\n children: \"id\"\n }), \" you use to connect over the WebSocket (\", _jsx(_components.code, {\n children: \"session.update\"\n }), \" with\\n\", _jsx(_components.code, {\n children: \"agent_id\"\n }), \").\"]\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = {\n ..._provideComponents(),\n ...props.components\n };\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\n","frontmatter":{},"scope":{}},"pageType":"default","mdx":{"mdxSource":{"compiledSource":"\"use strict\";const{Fragment:_Fragment,jsx:_jsx}=arguments[0];const{useMDXComponents:_provideComponents}=arguments[0];function _createMdxContent(props){return _jsx(_Fragment,{})}function MDXContent(props={}){const{wrapper:MDXLayout}={..._provideComponents(),...props.components};return MDXLayout?_jsx(MDXLayout,{...props,children:_jsx(_createMdxContent,{...props})}):_createMdxContent(props)}return{default:MDXContent}","frontmatter":{},"scope":{"config":{},"pageMetadata":{"title":"Create an agent","og.description":"Create a reusable voice agent.","openapi":"api-reference/specs/agents.yaml POST /v1/agents","description":"Create a reusable voice agent. Returns the full agent record, including a\ngenerated `id` you use to connect over the WebSocket (`session.update` with\n`agent_id`).\n","href":"/voice-agents/voice-agent-api/api-spec/create-agent","hidden":true}}},"mdxSourceWithNoJs":null},"mdxExtracts":{"tableOfContents":[],"codeExamples":{}},"jsLinks":["/docs/_mintlify/custom/assemblyai-fff14a6f/c705301dcef66bf6/rudderstack.js","/docs/_mintlify/custom/assemblyai-fff14a6f/700d2574de973df9/chat-widget.js","/docs/_mintlify/custom/assemblyai-fff14a6f/33c4022d4e30e01c/ketch.js"],"openApiReferenceData":{"operation":{"summary":"Create an agent","description":"Create a reusable voice agent. Returns the full agent record, including a\ngenerated `id` you use to connect over the WebSocket (`session.update` with\n`agent_id`).\n","operationId":"createAgent","x-fern-sdk-group-name":"Voice Agent API","x-fern-sdk-method-name":"createAgent","security":["00b61d11-9652-4ad6-aa20-f2b6e8cc9d10"],"requestBody":"33b92484-cbec-48fb-a52c-864183af6a4c","responses":{"201":"e35990ee-77ef-478d-8972-990655ac5581","400":"e1750d5e-8bc2-47ee-b992-58d1231313f4","401":"3c2cc9da-6f8d-43a3-b498-0d035411558e","422":"e454eb9c-c885-4e97-8e2b-d4a44c7630e5"},"method":"post","type":"path","servers":["5b07da07-156f-4fd7-b7ff-1aefbf72a9b4"],"path":"/v1/agents","baseUrlOptions":["https://agents.assemblyai.com"],"title":"Create an agent","codeSamples":[],"requiredOnlyExamples":false,"requestExampleType":"generated","responseExampleType":"generated"},"dependencies":{"parameters":{},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","system_prompt","voice"],"properties":{"name":{"type":"string","description":"Display name for the agent.","example":"Support Assistant","isRequired":true,"uniqueKey":"name","typeLabel":"string"},"system_prompt":{"type":"string","description":"The agent's instructions. Write voice-first.","example":"You are a friendly support agent. Keep responses under two sentences.","isRequired":true,"uniqueKey":"system_prompt","typeLabel":"string"},"voice":{"type":"object","required":["voice_id"],"properties":{"voice_id":{"type":"string","description":"A voice from the voice catalog. An invalid id returns 400 with the list of valid voices.","example":"alba","isRequired":true,"uniqueKey":"voice.voice_id","typeLabel":"string"}},"isRequired":true,"uniqueKey":"voice","typeLabel":"object"},"greeting":{"oneOf":[{"type":"string","description":"Spoken on connect; sent straight to TTS. Omit to listen first.","example":"Hi, how can I help?","uniqueKey":"greeting.oneOf.0","typeLabel":"string"},{"type":"null","description":"Spoken on connect; sent straight to TTS. Omit to listen first.","example":"Hi, how can I help?","uniqueKey":"greeting.oneOf.1","typeLabel":"null"}],"uniqueKey":"greeting","typeLabel":"string | null"},"input":{"type":"object","description":"Audio input configuration. Defaults to PCM at 24 kHz if omitted.","properties":{"type":{"type":"string","default":"audio","uniqueKey":"input.type","typeLabel":"string"},"format":{"type":"object","properties":{"encoding":{"type":"string","enum":["audio/pcm","audio/pcmu","audio/pcma"],"default":"audio/pcm","uniqueKey":"input.format.encoding","typeLabel":"enum\u003cstring>"},"sample_rate":{"type":"integer","example":24000,"uniqueKey":"input.format.sample_rate","typeLabel":"integer"}},"uniqueKey":"input.format","typeLabel":"object"},"turn_detection":{"oneOf":[{"type":"object","description":"VAD tuning, or null for adaptive defaults.","uniqueKey":"input.turn_detection.oneOf.0","typeLabel":"object"},{"type":"null","description":"VAD tuning, or null for adaptive defaults.","uniqueKey":"input.turn_detection.oneOf.1","typeLabel":"null"}],"uniqueKey":"input.turn_detection","typeLabel":"object | null"},"keyterms":{"oneOf":[{"type":"array","description":"Up to 100 transcription-bias strings, or null.","items":{"type":"string","uniqueKey":"input.keyterms.oneOf.0.items.[INDEX]","typeLabel":"string"},"uniqueKey":"input.keyterms.oneOf.0","typeLabel":"string[]"},{"type":"null","description":"Up to 100 transcription-bias strings, or null.","items":{"type":"string"},"uniqueKey":"input.keyterms.oneOf.1","typeLabel":"null"}],"uniqueKey":"input.keyterms","typeLabel":"string[] | null"}},"uniqueKey":"input","typeLabel":"object"},"output":{"type":"object","description":"Audio output configuration. Defaults to PCM at 24 kHz with the agent's voice.","properties":{"type":{"type":"string","default":"audio","uniqueKey":"output.type","typeLabel":"string"},"voice":{"type":"string","example":"alba","uniqueKey":"output.voice","typeLabel":"string"},"format":{"type":"object","properties":{"encoding":{"type":"string","enum":["audio/pcm","audio/pcmu","audio/pcma"],"default":"audio/pcm","uniqueKey":"output.format.encoding","typeLabel":"enum\u003cstring>"},"sample_rate":{"type":"integer","example":24000,"uniqueKey":"output.format.sample_rate","typeLabel":"integer"}},"uniqueKey":"output.format","typeLabel":"object"},"volume":{"oneOf":[{"type":"number","description":"Playback volume 0–100, or null for native level.","uniqueKey":"output.volume.oneOf.0","typeLabel":"number"},{"type":"null","description":"Playback volume 0–100, or null for native level.","uniqueKey":"output.volume.oneOf.1","typeLabel":"null"}],"uniqueKey":"output.volume","typeLabel":"number | null"}},"uniqueKey":"output","typeLabel":"object"},"tools":{"type":"array","description":"Tools the agent can call.","items":{"type":"object","required":["name","description"],"properties":{"name":{"type":"string","description":"Tool name the model calls.","example":"get_weather","isRequired":true,"uniqueKey":"tools.items.[INDEX].name","typeLabel":"string"},"description":{"type":"string","description":"When to call the tool. The model's main signal.","example":"Get current weather for a location. Use whenever the user asks about weather.","isRequired":true,"uniqueKey":"tools.items.[INDEX].description","typeLabel":"string"},"parameters":{"type":"object","description":"A JSON Schema describing the tool's arguments. The same form for HTTP and\nclient-side tools. Each property accepts standard JSON-Schema keywords; beyond\n`type` and `description`, use `enum`, `examples`, `pattern`, and `format` to\nsharpen tool-calling and turn-detection accuracy.\n","properties":{"type":{"type":"string","enum":["object"],"default":"object","uniqueKey":"tools.items.[INDEX].parameters.type","typeLabel":"enum\u003cstring>"},"properties":{"type":"object","description":"Map of argument name to its JSON-Schema definition.","additionalProperties":true,"uniqueKey":"tools.items.[INDEX].parameters.properties","typeLabel":"object"},"required":{"type":"array","description":"Names of the required arguments.","items":{"type":"string","uniqueKey":"tools.items.[INDEX].parameters.required.items.[INDEX]","typeLabel":"string"},"uniqueKey":"tools.items.[INDEX].parameters.required","typeLabel":"string[]"}},"example":{"type":"object","properties":{"order_id":{"type":"string","description":"The customer's order ID.","examples":["AB-12345"],"pattern":"[A-Z]{2}-\\d{5}"}},"required":["order_id"]},"uniqueKey":"tools.items.[INDEX].parameters","typeLabel":"object"},"http":{"type":"object","required":["url"],"description":"Makes the tool a server-side HTTP tool. AssemblyAI calls this endpoint when the model invokes the tool.","properties":{"url":{"type":"string","description":"Must be https and resolve to a public host. Max 2048 chars.","example":"https://api.example.com/weather","isRequired":true,"uniqueKey":"tools.items.[INDEX].http.url","typeLabel":"string"},"http_method":{"type":"string","enum":["GET","POST","PUT","PATCH","DELETE"],"default":"POST","description":"GET/DELETE send arguments as query params; POST/PUT/PATCH send them as a JSON body.","uniqueKey":"tools.items.[INDEX].http.http_method","typeLabel":"enum\u003cstring>"},"headers":{"oneOf":[{"type":"object","description":"Sent on every call. Values are encrypted at rest and write-only (masked as \"***\" in responses).","additionalProperties":{"type":"string","uniqueKey":"tools.items.[INDEX].http.headers.oneOf.0.additionalProperties","typeLabel":"string"},"uniqueKey":"tools.items.[INDEX].http.headers.oneOf.0","typeLabel":"object"},{"type":"null","description":"Sent on every call. Values are encrypted at rest and write-only (masked as \"***\" in responses).","additionalProperties":{"type":"string","uniqueKey":"tools.items.[INDEX].http.headers.oneOf.1.additionalProperties","typeLabel":"string"},"uniqueKey":"tools.items.[INDEX].http.headers.oneOf.1","typeLabel":"null"}],"uniqueKey":"tools.items.[INDEX].http.headers","typeLabel":"object | null"}},"uniqueKey":"tools.items.[INDEX].http","typeLabel":"object"},"timeout_seconds":{"type":"integer","minimum":1,"maximum":300,"default":120,"uniqueKey":"tools.items.[INDEX].timeout_seconds","typeLabel":"integer"},"execution_mode":{"type":"string","enum":["interactive","hold"],"default":"interactive","description":"How the agent behaves while the tool runs.","uniqueKey":"tools.items.[INDEX].execution_mode","typeLabel":"enum\u003cstring>"}},"uniqueKey":"tools.items.[INDEX]","typeLabel":"object"},"uniqueKey":"tools","typeLabel":"object[]"},"llm":{"type":"array","maxItems":1,"description":"Connect your own OpenAI-compatible LLM instead of AssemblyAI's\nmanaged model. Provide at most one config; omit to use the managed\nLLM. Multiple configs (fallbacks) are not yet supported.\n","items":{"type":"object","required":["base_url","model","api_key"],"description":"An OpenAI-compatible chat-completions endpoint used as the agent's\nconversational LLM in place of AssemblyAI's managed model.\n","properties":{"base_url":{"type":"string","description":"HTTPS base URL of the OpenAI-compatible endpoint. Must be https and resolve to a public host.","example":"https://api.openai.com/v1","isRequired":true,"uniqueKey":"llm.items.[INDEX].base_url","typeLabel":"string"},"model":{"type":"string","description":"Model name sent in the chat-completions request body.","example":"gpt-4o-mini","isRequired":true,"uniqueKey":"llm.items.[INDEX].model","typeLabel":"string"},"api_key":{"type":"string","description":"API key for the endpoint. Write-only — encrypted at rest and never returned in any response.","isRequired":true,"uniqueKey":"llm.items.[INDEX].api_key","typeLabel":"string"}},"uniqueKey":"llm.items.[INDEX]","typeLabel":"object"},"uniqueKey":"llm","typeLabel":"object[]"},"pre_connect_requests":{"type":"array","maxItems":2,"description":"HTTPS lookups the platform runs, in order, before answering an inbound\nphone call. Each can send the call's facts (such as the caller's\nnumber) and values an earlier entry captured, and captures values from\nits JSON response for the greeting and the conversation. Telephony\nonly; ignored on WebSocket sessions. See\n[Pre-connect requests](/voice-agents/voice-agent-api/pre-connect-requests).\n","items":{"type":"object","required":["http"],"properties":{"http":{"type":"object","required":["url"],"description":"The HTTPS endpoint to call. The hostname must resolve in public DNS at create or update time.","properties":{"url":{"type":"string","description":"Must be https and resolve to a public host. Max 2048 chars.","example":"https://api.example.com/weather","isRequired":true,"uniqueKey":"pre_connect_requests.items.[INDEX].http.url","typeLabel":"string"},"http_method":{"type":"string","enum":["GET","POST","PUT","PATCH","DELETE"],"default":"POST","description":"GET/DELETE send arguments as query params; POST/PUT/PATCH send them as a JSON body.","uniqueKey":"pre_connect_requests.items.[INDEX].http.http_method","typeLabel":"enum\u003cstring>"},"headers":{"oneOf":[{"type":"object","description":"Sent on every call. Values are encrypted at rest and write-only (masked as \"***\" in responses).","additionalProperties":{"type":"string","uniqueKey":"pre_connect_requests.items.[INDEX].http.headers.oneOf.0.additionalProperties","typeLabel":"string"},"uniqueKey":"pre_connect_requests.items.[INDEX].http.headers.oneOf.0","typeLabel":"object"},{"type":"null","description":"Sent on every call. Values are encrypted at rest and write-only (masked as \"***\" in responses).","additionalProperties":{"type":"string","uniqueKey":"pre_connect_requests.items.[INDEX].http.headers.oneOf.1.additionalProperties","typeLabel":"string"},"uniqueKey":"pre_connect_requests.items.[INDEX].http.headers.oneOf.1","typeLabel":"null"}],"uniqueKey":"pre_connect_requests.items.[INDEX].http.headers","typeLabel":"object | null"}},"isRequired":true,"uniqueKey":"pre_connect_requests.items.[INDEX].http","typeLabel":"object"},"sends":{"type":"array","description":"Names to send to this endpoint, in the JSON body for POST, PUT and\nPATCH or as query parameters for GET and DELETE. Any entry may name\nthe platform's call facts `caller_number`, `dialed_number`,\n`direction`, `agent_id` and `session_id`; later entries may also name\nvalues an earlier entry captured. Opt-in per entry: nothing is sent\nunless named. A fact the platform does not have (for example a\nwithheld caller number) is omitted rather than sent blank.\n","items":{"type":"string","uniqueKey":"pre_connect_requests.items.[INDEX].sends.items.[INDEX]","typeLabel":"string"},"example":["caller_number"],"uniqueKey":"pre_connect_requests.items.[INDEX].sends","typeLabel":"string[]"},"returns":{"type":"array","description":"Values to capture from the JSON response.","items":{"type":"object","required":["name","path"],"properties":{"name":{"type":"string","description":"Name the value is captured under. Available to later entries'\n`sends`, to `{{name}}` placeholders in the agent's greeting, and to\nthe model as `aai_pre_connect_context`. Unique across all entries.\n","example":"patient_name","isRequired":true,"uniqueKey":"pre_connect_requests.items.[INDEX].returns.items.[INDEX].name","typeLabel":"string"},"path":{"type":"string","description":"Dotted path into the JSON response, e.g. `patient.first_name` or\n`results.0.id`. Segments match `[A-Za-z0-9_-]+`, at most 10 deep and\n256 characters. Shape is validated at write time; whether the path\nexists is only knowable at call time.\n","example":"patient.first_name","isRequired":true,"uniqueKey":"pre_connect_requests.items.[INDEX].returns.items.[INDEX].path","typeLabel":"string"},"default":{"oneOf":[{"type":"string","description":"Used when the path does not resolve. Without one, an unresolved\npath leaves the value unset. For greeting placeholders use a\nnon-empty default: a placeholder that resolves to nothing makes the\nplatform speak the agent's greeting as declared.\n","example":"there","uniqueKey":"pre_connect_requests.items.[INDEX].returns.items.[INDEX].default.oneOf.0","typeLabel":"string"},{"type":"null","description":"Used when the path does not resolve. Without one, an unresolved\npath leaves the value unset. For greeting placeholders use a\nnon-empty default: a placeholder that resolves to nothing makes the\nplatform speak the agent's greeting as declared.\n","example":"there","uniqueKey":"pre_connect_requests.items.[INDEX].returns.items.[INDEX].default.oneOf.1","typeLabel":"null"}],"uniqueKey":"pre_connect_requests.items.[INDEX].returns.items.[INDEX].default","typeLabel":"string | null"}},"uniqueKey":"pre_connect_requests.items.[INDEX].returns.items.[INDEX]","typeLabel":"object"},"uniqueKey":"pre_connect_requests.items.[INDEX].returns","typeLabel":"object[]"},"timeout_ms":{"oneOf":[{"type":"integer","minimum":1,"maximum":800,"description":"Lowers this entry's timeout. Every entry has its own 800 ms ceiling;\nthis can only shorten it. Omit for the full ceiling.\n","example":600,"uniqueKey":"pre_connect_requests.items.[INDEX].timeout_ms.oneOf.0","typeLabel":"integer"},{"type":"null","minimum":1,"maximum":800,"description":"Lowers this entry's timeout. Every entry has its own 800 ms ceiling;\nthis can only shorten it. Omit for the full ceiling.\n","example":600,"uniqueKey":"pre_connect_requests.items.[INDEX].timeout_ms.oneOf.1","typeLabel":"null"}],"uniqueKey":"pre_connect_requests.items.[INDEX].timeout_ms","typeLabel":"integer | null"},"allow_overrides":{"type":"array","description":"Agent fields the response may replace. Closed vocabulary; today only `greeting`.","items":{"type":"string","enum":["greeting"],"uniqueKey":"pre_connect_requests.items.[INDEX].allow_overrides.items.[INDEX]","typeLabel":"enum\u003cstring>"},"example":["greeting"],"uniqueKey":"pre_connect_requests.items.[INDEX].allow_overrides","typeLabel":"enum\u003cstring>[]"}},"uniqueKey":"pre_connect_requests.items.[INDEX]","typeLabel":"object"},"uniqueKey":"pre_connect_requests","typeLabel":"object[]"}},"uniqueKey":"","typeLabel":"object"},"examples":{"Example":{"title":"Example","value":{"name":"Support Assistant","system_prompt":"You are a friendly support agent. Keep responses under two sentences.","voice":{"voice_id":"alba"},"greeting":"Hi, how can I help?","input":{"type":"audio","format":{"encoding":"audio/pcm","sample_rate":24000},"turn_detection":{},"keyterms":["\u003cstring>"]},"output":{"type":"audio","voice":"alba","format":{"encoding":"audio/pcm","sample_rate":24000},"volume":123},"tools":[{"name":"get_weather","description":"Get current weather for a location. Use whenever the user asks about weather.","parameters":{"type":"object","properties":{"order_id":{"type":"string","description":"The customer's order ID.","examples":["AB-12345"],"pattern":"[A-Z]{2}-\\d{5}"}},"required":["order_id"]},"timeout_seconds":120,"execution_mode":"interactive"}],"llm":[{"base_url":"https://api.openai.com/v1","model":"gpt-4o-mini","api_key":"\u003cstring>"}],"pre_connect_requests":[{"http":{"url":"https://api.example.com/weather","http_method":"POST","headers":{}},"sends":["caller_number"],"returns":[{"name":"patient_name","path":"patient.first_name","default":"there"}],"timeout_ms":600,"allow_overrides":["greeting"]}]}}},"exampleType":"generated"}},"exampleType":"generated"},"responses":{"e35990ee-77ef-478d-8972-990655ac5581":{"description":"Agent created.","content":{"application/json":{"schema":{"type":"object","description":"A stored voice agent.","properties":{"id":{"type":"string","example":"7ad24396-b822-4dca-871a-be9cc4781cf9","uniqueKey":"id","typeLabel":"string"},"name":{"type":"string","example":"Support Assistant","uniqueKey":"name","typeLabel":"string"},"system_prompt":{"type":"string","uniqueKey":"system_prompt","typeLabel":"string"},"greeting":{"oneOf":[{"type":"string","uniqueKey":"greeting.oneOf.0","typeLabel":"string"},{"type":"null","uniqueKey":"greeting.oneOf.1","typeLabel":"null"}],"uniqueKey":"greeting","typeLabel":"string | null"},"voice":{"type":"object","required":["voice_id"],"properties":{"voice_id":{"type":"string","description":"A voice from the voice catalog. An invalid id returns 400 with the list of valid voices.","example":"alba","isRequired":true,"uniqueKey":"voice.voice_id","typeLabel":"string"}},"uniqueKey":"voice","typeLabel":"object"},"input":{"type":"object","description":"Audio input configuration. Defaults to PCM at 24 kHz if omitted.","properties":{"type":{"type":"string","default":"audio","uniqueKey":"input.type","typeLabel":"string"},"format":{"type":"object","properties":{"encoding":{"type":"string","enum":["audio/pcm","audio/pcmu","audio/pcma"],"default":"audio/pcm","uniqueKey":"input.format.encoding","typeLabel":"enum\u003cstring>"},"sample_rate":{"type":"integer","example":24000,"uniqueKey":"input.format.sample_rate","typeLabel":"integer"}},"uniqueKey":"input.format","typeLabel":"object"},"turn_detection":{"oneOf":[{"type":"object","description":"VAD tuning, or null for adaptive defaults.","uniqueKey":"input.turn_detection.oneOf.0","typeLabel":"object"},{"type":"null","description":"VAD tuning, or null for adaptive defaults.","uniqueKey":"input.turn_detection.oneOf.1","typeLabel":"null"}],"uniqueKey":"input.turn_detection","typeLabel":"object | null"},"keyterms":{"oneOf":[{"type":"array","description":"Up to 100 transcription-bias strings, or null.","items":{"type":"string","uniqueKey":"input.keyterms.oneOf.0.items.[INDEX]","typeLabel":"string"},"uniqueKey":"input.keyterms.oneOf.0","typeLabel":"string[]"},{"type":"null","description":"Up to 100 transcription-bias strings, or null.","items":{"type":"string"},"uniqueKey":"input.keyterms.oneOf.1","typeLabel":"null"}],"uniqueKey":"input.keyterms","typeLabel":"string[] | null"}},"uniqueKey":"input","typeLabel":"object"},"output":{"type":"object","description":"Audio output configuration. Defaults to PCM at 24 kHz with the agent's voice.","properties":{"type":{"type":"string","default":"audio","uniqueKey":"output.type","typeLabel":"string"},"voice":{"type":"string","example":"alba","uniqueKey":"output.voice","typeLabel":"string"},"format":{"type":"object","properties":{"encoding":{"type":"string","enum":["audio/pcm","audio/pcmu","audio/pcma"],"default":"audio/pcm","uniqueKey":"output.format.encoding","typeLabel":"enum\u003cstring>"},"sample_rate":{"type":"integer","example":24000,"uniqueKey":"output.format.sample_rate","typeLabel":"integer"}},"uniqueKey":"output.format","typeLabel":"object"},"volume":{"oneOf":[{"type":"number","description":"Playback volume 0–100, or null for native level.","uniqueKey":"output.volume.oneOf.0","typeLabel":"number"},{"type":"null","description":"Playback volume 0–100, or null for native level.","uniqueKey":"output.volume.oneOf.1","typeLabel":"null"}],"uniqueKey":"output.volume","typeLabel":"number | null"}},"uniqueKey":"output","typeLabel":"object"},"tools":{"type":"array","items":{"type":"object","description":"A tool as returned in an agent record. Header values are masked.","properties":{"id":{"type":"string","uniqueKey":"tools.items.[INDEX].id","typeLabel":"string"},"name":{"type":"string","uniqueKey":"tools.items.[INDEX].name","typeLabel":"string"},"description":{"type":"string","uniqueKey":"tools.items.[INDEX].description","typeLabel":"string"},"http":{"type":"object","properties":{"url":{"type":"string","uniqueKey":"tools.items.[INDEX].http.url","typeLabel":"string"},"http_method":{"type":"string","enum":["GET","POST","PUT","PATCH","DELETE"],"uniqueKey":"tools.items.[INDEX].http.http_method","typeLabel":"enum\u003cstring>"},"headers":{"type":"object","description":"Header names with values masked as \"***\".","additionalProperties":{"type":"string","uniqueKey":"tools.items.[INDEX].http.headers.additionalProperties","typeLabel":"string"},"example":{"Authorization":"***"},"uniqueKey":"tools.items.[INDEX].http.headers","typeLabel":"object"}},"uniqueKey":"tools.items.[INDEX].http","typeLabel":"object"},"parameters":{"type":"object","description":"A JSON Schema describing the tool's arguments. The same form for HTTP and\nclient-side tools. Each property accepts standard JSON-Schema keywords; beyond\n`type` and `description`, use `enum`, `examples`, `pattern`, and `format` to\nsharpen tool-calling and turn-detection accuracy.\n","properties":{"type":{"type":"string","enum":["object"],"default":"object","uniqueKey":"tools.items.[INDEX].parameters.type","typeLabel":"enum\u003cstring>"},"properties":{"type":"object","description":"Map of argument name to its JSON-Schema definition.","additionalProperties":true,"uniqueKey":"tools.items.[INDEX].parameters.properties","typeLabel":"object"},"required":{"type":"array","description":"Names of the required arguments.","items":{"type":"string","uniqueKey":"tools.items.[INDEX].parameters.required.items.[INDEX]","typeLabel":"string"},"uniqueKey":"tools.items.[INDEX].parameters.required","typeLabel":"string[]"}},"example":{"type":"object","properties":{"order_id":{"type":"string","description":"The customer's order ID.","examples":["AB-12345"],"pattern":"[A-Z]{2}-\\d{5}"}},"required":["order_id"]},"uniqueKey":"tools.items.[INDEX].parameters","typeLabel":"object"},"timeout_seconds":{"type":"integer","uniqueKey":"tools.items.[INDEX].timeout_seconds","typeLabel":"integer"},"execution_mode":{"type":"string","enum":["interactive","hold"],"uniqueKey":"tools.items.[INDEX].execution_mode","typeLabel":"enum\u003cstring>"}},"uniqueKey":"tools.items.[INDEX]","typeLabel":"object"},"uniqueKey":"tools","typeLabel":"object[]"},"llm":{"type":"array","description":"Connected LLM, if any. The api_key is write-only and never returned.","items":{"type":"object","description":"A connected LLM as returned in an agent record. The api_key is never included.","properties":{"base_url":{"type":"string","example":"https://api.openai.com/v1","uniqueKey":"llm.items.[INDEX].base_url","typeLabel":"string"},"model":{"type":"string","example":"gpt-4o-mini","uniqueKey":"llm.items.[INDEX].model","typeLabel":"string"}},"uniqueKey":"llm.items.[INDEX]","typeLabel":"object"},"uniqueKey":"llm","typeLabel":"object[]"},"created_at":{"type":"string","format":"date-time","uniqueKey":"created_at","typeLabel":"string\u003cdate-time>"},"updated_at":{"type":"string","format":"date-time","uniqueKey":"updated_at","typeLabel":"string\u003cdate-time>"},"pre_connect_requests":{"type":"array","description":"The declared pre-connect requests. Header values are never returned.","items":{"type":"object","properties":{"http":{"type":"object","properties":{"url":{"type":"string","uniqueKey":"pre_connect_requests.items.[INDEX].http.url","typeLabel":"string"},"http_method":{"type":"string","enum":["GET","POST","PUT","PATCH","DELETE"],"uniqueKey":"pre_connect_requests.items.[INDEX].http.http_method","typeLabel":"enum\u003cstring>"},"headers":{"type":"object","description":"Header names with values masked as \"***\".","additionalProperties":{"type":"string","uniqueKey":"pre_connect_requests.items.[INDEX].http.headers.additionalProperties","typeLabel":"string"},"example":{"Authorization":"***"},"uniqueKey":"pre_connect_requests.items.[INDEX].http.headers","typeLabel":"object"}},"uniqueKey":"pre_connect_requests.items.[INDEX].http","typeLabel":"object"},"sends":{"type":"array","items":{"type":"string","uniqueKey":"pre_connect_requests.items.[INDEX].sends.items.[INDEX]","typeLabel":"string"},"uniqueKey":"pre_connect_requests.items.[INDEX].sends","typeLabel":"string[]"},"returns":{"type":"array","items":{"type":"object","required":["name","path"],"properties":{"name":{"type":"string","description":"Name the value is captured under. Available to later entries'\n`sends`, to `{{name}}` placeholders in the agent's greeting, and to\nthe model as `aai_pre_connect_context`. Unique across all entries.\n","example":"patient_name","isRequired":true,"uniqueKey":"pre_connect_requests.items.[INDEX].returns.items.[INDEX].name","typeLabel":"string"},"path":{"type":"string","description":"Dotted path into the JSON response, e.g. `patient.first_name` or\n`results.0.id`. Segments match `[A-Za-z0-9_-]+`, at most 10 deep and\n256 characters. Shape is validated at write time; whether the path\nexists is only knowable at call time.\n","example":"patient.first_name","isRequired":true,"uniqueKey":"pre_connect_requests.items.[INDEX].returns.items.[INDEX].path","typeLabel":"string"},"default":{"oneOf":[{"type":"string","description":"Used when the path does not resolve. Without one, an unresolved\npath leaves the value unset. For greeting placeholders use a\nnon-empty default: a placeholder that resolves to nothing makes the\nplatform speak the agent's greeting as declared.\n","example":"there","uniqueKey":"pre_connect_requests.items.[INDEX].returns.items.[INDEX].default.oneOf.0","typeLabel":"string"},{"type":"null","description":"Used when the path does not resolve. Without one, an unresolved\npath leaves the value unset. For greeting placeholders use a\nnon-empty default: a placeholder that resolves to nothing makes the\nplatform speak the agent's greeting as declared.\n","example":"there","uniqueKey":"pre_connect_requests.items.[INDEX].returns.items.[INDEX].default.oneOf.1","typeLabel":"null"}],"uniqueKey":"pre_connect_requests.items.[INDEX].returns.items.[INDEX].default","typeLabel":"string | null"}},"uniqueKey":"pre_connect_requests.items.[INDEX].returns.items.[INDEX]","typeLabel":"object"},"uniqueKey":"pre_connect_requests.items.[INDEX].returns","typeLabel":"object[]"},"timeout_ms":{"oneOf":[{"type":"integer","description":"Null means the full 800 ms ceiling applies.","uniqueKey":"pre_connect_requests.items.[INDEX].timeout_ms.oneOf.0","typeLabel":"integer"},{"type":"null","description":"Null means the full 800 ms ceiling applies.","uniqueKey":"pre_connect_requests.items.[INDEX].timeout_ms.oneOf.1","typeLabel":"null"}],"uniqueKey":"pre_connect_requests.items.[INDEX].timeout_ms","typeLabel":"integer | null"},"allow_overrides":{"type":"array","items":{"type":"string","uniqueKey":"pre_connect_requests.items.[INDEX].allow_overrides.items.[INDEX]","typeLabel":"string"},"uniqueKey":"pre_connect_requests.items.[INDEX].allow_overrides","typeLabel":"string[]"}},"uniqueKey":"pre_connect_requests.items.[INDEX]","typeLabel":"object"},"uniqueKey":"pre_connect_requests","typeLabel":"object[]"}},"uniqueKey":"","typeLabel":"object"},"examples":{"Example":{"title":"Example","value":{"id":"7ad24396-b822-4dca-871a-be9cc4781cf9","name":"Support Assistant","system_prompt":"\u003cstring>","greeting":"\u003cstring>","voice":{"voice_id":"alba"},"input":{"type":"audio","format":{"encoding":"audio/pcm","sample_rate":24000},"turn_detection":{},"keyterms":["\u003cstring>"]},"output":{"type":"audio","voice":"alba","format":{"encoding":"audio/pcm","sample_rate":24000},"volume":123},"tools":[{"id":"\u003cstring>","name":"\u003cstring>","description":"\u003cstring>","http":{"url":"\u003cstring>","http_method":"GET","headers":{"Authorization":"***"}},"parameters":{"type":"object","properties":{"order_id":{"type":"string","description":"The customer's order ID.","examples":["AB-12345"],"pattern":"[A-Z]{2}-\\d{5}"}},"required":["order_id"]},"timeout_seconds":123,"execution_mode":"interactive"}],"llm":[{"base_url":"https://api.openai.com/v1","model":"gpt-4o-mini"}],"created_at":"2023-11-07T05:31:56Z","updated_at":"2023-11-07T05:31:56Z","pre_connect_requests":[{"http":{"url":"\u003cstring>","http_method":"GET","headers":{"Authorization":"***"}},"sends":["\u003cstring>"],"returns":[{"name":"patient_name","path":"patient.first_name","default":"there"}],"timeout_ms":123,"allow_overrides":["\u003cstring>"]}]}}},"exampleType":"generated"}},"exampleType":"generated"},"e1750d5e-8bc2-47ee-b992-58d1231313f4":{"description":"Bad request. A field failed validation (e.g. invalid voice, non-https tool URL, timeout out of range).","content":{"application/json":{"schema":{"type":"object","properties":{"detail":{"type":"string","description":"Error message describing what went wrong.","example":"Unauthorized","uniqueKey":"detail","typeLabel":"string"}},"uniqueKey":"","typeLabel":"object"},"examples":{"Example":{"title":"Example","value":{"detail":"Unauthorized"}}},"exampleType":"generated"}},"exampleType":"generated"},"3c2cc9da-6f8d-43a3-b498-0d035411558e":{"description":"Unauthorized. Invalid or missing API key, or the key is not entitled for Voice Agents.","content":{"application/json":{"schema":{"type":"object","properties":{"detail":{"type":"string","description":"Error message describing what went wrong.","example":"Unauthorized","uniqueKey":"detail","typeLabel":"string"}},"uniqueKey":"","typeLabel":"object"},"examples":{"Example":{"title":"Example","value":{"detail":"Unauthorized"}}},"exampleType":"generated"}},"exampleType":"generated"},"e454eb9c-c885-4e97-8e2b-d4a44c7630e5":{"description":"Unprocessable entity. Malformed JSON or a field of the wrong type.","content":{"application/json":{"schema":{"type":"object","properties":{"detail":{"type":"string","description":"Error message describing what went wrong.","example":"Unauthorized","uniqueKey":"detail","typeLabel":"string"}},"uniqueKey":"","typeLabel":"object"},"examples":{"Example":{"title":"Example","value":{"detail":"Unauthorized"}}},"exampleType":"generated"}},"exampleType":"generated"}},"security":{"00b61d11-9652-4ad6-aa20-f2b6e8cc9d10":{"apiKey":{"type":"apiKey","in":"header","name":"Authorization","description":"Your AssemblyAI API key in the `Authorization` header. The raw key works directly; a `Bearer ` prefix is also accepted.","scopes":[],"schemeName":"apiKey"}}},"servers":{"5b07da07-156f-4fd7-b7ff-1aefbf72a9b4":{"url":"https://agents.assemblyai.com","description":"Production server","x-fern-server-name":"Default"}},"processedSecurityOptions":[{"schemes":[{"scheme":{"type":"apiKey","in":"header","name":"Authorization","description":"Your AssemblyAI API key in the `Authorization` header. The raw key works directly; a `Bearer ` prefix is also accepted.","scopes":[],"schemeName":"apiKey"},"schema":{"title":"Authorization","type":"string","description":"Your AssemblyAI API key in the `Authorization` header. The raw key works directly; a `Bearer ` prefix is also accepted.","isRequired":true,"typeLabel":"string","deprecated":false},"schemeName":"apiKey","name":"Authorization"}],"title":"apiKey"}]},"originalFileLocation":"api-reference/specs/agents.yaml"},"subdomain":"assemblyai-fff14a6f","siteName":"AssemblyAI","title":"Create an agent - AssemblyAI","navMaps":{"firstHrefInVersion":{},"firstHrefInLanguage":{}},"lastModified":"2026-07-08T14:22:12.882Z","originalFileLocation":"voice-agents/voice-agent-api/api-spec/create-agent.mdx"},"headHtml":"\u003cscript data-mint-head>(function(){var d=document.documentElement,p=null;if(!p){try{p=localStorage.getItem(\"isDarkMode\")}catch(e){}if(p==='true')p='dark';else if(p==='false')p='light';if(p!=='light'\u0026\u0026p!=='dark'\u0026\u0026p!=='system')p=\"system\"}var r=p==='system'?(matchMedia(\"(prefers-color-scheme: dark)\").matches?'dark':'light'):p;d.classList.remove(r==='dark'?'light':'dark');d.classList.add(r);d.setAttribute(\"data-theme-preference\",p)})();\u003c/script>\u003cmeta data-mint-head name=\"description\" content=\"Create a reusable voice agent. Returns the full agent record, including a generated id you use to connect over the WebSocket (session.update with agent_id).\">\u003cmeta data-mint-head name=\"application-name\" content=\"AssemblyAI\">\u003cmeta data-mint-head name=\"generator\" content=\"Mintlify\">\u003cmeta data-mint-head name=\"robots\" content=\"noindex\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/docs/mintlify-assets/_mintlify/favicons/assemblyai-fff14a6f/IP3FX8MjuVkHah_W/_generated/favicon/android-chrome-192x192.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"apple-touch-icon\" type=\"image/png\" sizes=\"180x180\" href=\"/docs/mintlify-assets/_mintlify/favicons/assemblyai-fff14a6f/IP3FX8MjuVkHah_W/_generated/favicon/apple-touch-icon.png\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/docs/mintlify-assets/_mintlify/favicons/assemblyai-fff14a6f/IP3FX8MjuVkHah_W/_generated/favicon/favicon-16x16.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/docs/mintlify-assets/_mintlify/favicons/assemblyai-fff14a6f/IP3FX8MjuVkHah_W/_generated/favicon/favicon-32x32.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/docs/mintlify-assets/_mintlify/favicons/assemblyai-fff14a6f/IP3FX8MjuVkHah_W/_generated/favicon/favicon.ico\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/docs/mintlify-assets/_mintlify/favicons/assemblyai-fff14a6f/IP3FX8MjuVkHah_W/_generated/favicon-dark/android-chrome-192x192.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/docs/mintlify-assets/_mintlify/favicons/assemblyai-fff14a6f/IP3FX8MjuVkHah_W/_generated/favicon-dark/favicon-16x16.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/docs/mintlify-assets/_mintlify/favicons/assemblyai-fff14a6f/IP3FX8MjuVkHah_W/_generated/favicon-dark/favicon-32x32.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/docs/mintlify-assets/_mintlify/favicons/assemblyai-fff14a6f/IP3FX8MjuVkHah_W/_generated/favicon-dark/favicon.ico\" media=\"(prefers-color-scheme: dark)\">\u003cmeta data-mint-head property=\"og:title\" content=\"Create an agent - AssemblyAI\">\u003cmeta data-mint-head property=\"og:description\" content=\"Create a reusable voice agent. Returns the full agent record, including a generated id you use to connect over the WebSocket (session.update with agent_id).\">\u003cmeta data-mint-head property=\"og:site_name\" content=\"AssemblyAI\">\u003cmeta data-mint-head property=\"og:url\" content=\"https://www.assemblyai.com/docs/voice-agents/voice-agent-api/api-spec/create-agent\">\u003cmeta data-mint-head property=\"og:type\" content=\"website\">\u003cmeta data-mint-head property=\"og:image\" content=\"https://assemblyai-fff14a6f.mintlify.site/docs/_mintlify/api/og/v2?division=Endpoints\u0026amp;title=Create+an+agent\u0026amp;description=Create+a+reusable+voice+agent.+Returns+the+full+agent+record%2C+including+a%0Agenerated+%60id%60+you+use+to+connect+over+the+WebSocket+%28%60session.update%60+with%0A%60agent_id%60\u0026amp;theme=7f291be5810d1f7c5136ed41\u0026amp;signature=4caa8be8fdf9d4c8a29bc74715895565b049bb67e0566d014e7d927ed7512edc\">\u003cmeta data-mint-head property=\"og:image:width\" content=\"1200\">\u003cmeta data-mint-head property=\"og:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"twitter:card\" content=\"summary_large_image\">\u003cmeta data-mint-head name=\"twitter:title\" content=\"Create an agent - AssemblyAI\">\u003cmeta data-mint-head name=\"twitter:description\" content=\"Create a reusable voice agent. Returns the full agent record, including a generated id you use to connect over the WebSocket (session.update with agent_id).\">\u003cmeta data-mint-head name=\"twitter:image\" content=\"https://assemblyai-fff14a6f.mintlify.site/docs/_mintlify/api/og/v2?division=Endpoints\u0026amp;title=Create+an+agent\u0026amp;description=Create+a+reusable+voice+agent.+Returns+the+full+agent+record%2C+including+a%0Agenerated+%60id%60+you+use+to+connect+over+the+WebSocket+%28%60session.update%60+with%0A%60agent_id%60\u0026amp;theme=7f291be5810d1f7c5136ed41\u0026amp;signature=4caa8be8fdf9d4c8a29bc74715895565b049bb67e0566d014e7d927ed7512edc\">\u003cmeta data-mint-head name=\"twitter:image:width\" content=\"1200\">\u003cmeta data-mint-head name=\"twitter:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"msapplication-config\" content=\"/docs/mintlify-assets/_mintlify/favicons/assemblyai-fff14a6f/IP3FX8MjuVkHah_W/_generated/favicon/browserconfig.xml\">\u003cmeta data-mint-head name=\"apple-mobile-web-app-title\" content=\"AssemblyAI\">\u003cmeta data-mint-head name=\"msapplication-TileColor\" content=\"#614fd2\">\u003clink data-mint-head rel=\"canonical\" href=\"https://www.assemblyai.com/docs/voice-agents/voice-agent-api/api-spec/create-agent\">\u003clink data-mint-head rel=\"alternate\" type=\"application/xml\" href=\"/docs/sitemap.xml\">\u003clink data-mint-head rel=\"alternate\" type=\"text/markdown\" href=\"/docs/voice-agents/voice-agent-api/api-spec/create-agent.md\">\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@graph\":[{\"@type\":\"Organization\",\"@id\":\"https://www.assemblyai.com/#organization\",\"name\":\"AssemblyAI\",\"url\":\"https://www.assemblyai.com\",\"logo\":{\"@type\":\"ImageObject\",\"url\":\"https://mintcdn.com/assemblyai-fff14a6f/vMuNaI_PbWUbVeV0/assets/assemblyai-lockup-primary.svg?fit=max\u0026auto=format\u0026n=vMuNaI_PbWUbVeV0\u0026q=85\u0026s=808d2a677e2536423045d44b3f330ac2\"}},{\"@type\":\"WebSite\",\"@id\":\"https://www.assemblyai.com/docs#website\",\"name\":\"AssemblyAI\",\"url\":\"https://www.assemblyai.com/docs\",\"publisher\":{\"@id\":\"https://www.assemblyai.com/#organization\"}},{\"@type\":\"WebPage\",\"@id\":\"https://www.assemblyai.com/docs/voice-agents/voice-agent-api/api-spec/create-agent#webpage\",\"url\":\"https://www.assemblyai.com/docs/voice-agents/voice-agent-api/api-spec/create-agent\",\"name\":\"Create an agent\",\"description\":\"Create a reusable voice agent. Returns the full agent record, including a generated id you use to connect over the WebSocket (session.update with agent_id).\",\"dateModified\":\"2026-07-08T14:22:12.882Z\",\"isPartOf\":{\"@id\":\"https://www.assemblyai.com/docs#website\"},\"breadcrumb\":{\"@id\":\"https://www.assemblyai.com/docs/voice-agents/voice-agent-api/api-spec/create-agent#breadcrumb\"}},{\"@type\":\"BreadcrumbList\",\"@id\":\"https://www.assemblyai.com/docs/voice-agents/voice-agent-api/api-spec/create-agent#breadcrumb\",\"itemListElement\":[{\"@type\":\"ListItem\",\"position\":1,\"name\":\"Create \u0026 manage agents\",\"item\":\"https://www.assemblyai.com/docs/voice-agents/voice-agent-api/create-agent\"},{\"@type\":\"ListItem\",\"position\":2,\"name\":\"Create an agent\",\"item\":\"https://www.assemblyai.com/docs/voice-agents/voice-agent-api/api-spec/create-agent\"}]},{\"@type\":[\"TechArticle\",\"APIReference\"],\"@id\":\"https://www.assemblyai.com/docs/voice-agents/voice-agent-api/api-spec/create-agent#apireference\",\"headline\":\"Create an agent\",\"name\":\"Create an agent\",\"description\":\"Create a reusable voice agent. Returns the full agent record, including a generated id you use to connect over the WebSocket (session.update with agent_id).\",\"url\":\"https://www.assemblyai.com/docs/voice-agents/voice-agent-api/api-spec/create-agent\",\"mainEntityOfPage\":{\"@id\":\"https://www.assemblyai.com/docs/voice-agents/voice-agent-api/api-spec/create-agent#webpage\"},\"dateModified\":\"2026-07-08T14:22:12.882Z\",\"publisher\":{\"@id\":\"https://www.assemblyai.com/#organization\"},\"isPartOf\":{\"@id\":\"https://www.assemblyai.com/docs#website\"}}]}\u003c/script>","agentPointerHref":"/docs/voice-agents/voice-agent-api/api-spec/create-agent.md","siteName":"AssemblyAI","nav":{"global":null,"tabs":[{"tab":"Overview","pages":[{"title":"Overview","href":""}]},{"tab":"Pre-recorded STT","pages":[{"title":"Pre-recorded STT","href":"/pre-recorded-audio/getting-started/transcribe-an-audio-file"}]},{"tab":"Real-time STT","pages":[{"title":"Real-time STT","href":"/streaming/getting-started/transcribe-streaming-audio"}]},{"tab":"Sync STT","pages":[{"title":"Sync STT","href":"/sync-stt/getting-started/quickstart"}]},{"tab":"Dictation API","pages":[{"title":"Dictation API","href":"/dictation"}]},{"tab":"Text to Speech","pages":[{"title":"Text to Speech","href":"/tts/getting-started/quickstart"}]},{"tab":"Voice Agent API","hidden":true,"groups":[{"group":"Getting started","pages":[{"title":"Voice Agent API","description":"Real-time voice agents that talk and listen. Configure an agent once, then deploy it to a browser, your own app, or the phone.","sidebarTitle":"Quickstart","href":"/voice-agents/voice-agent-api"},{"title":"Build with AI coding tools","description":"Point your AI coding assistant at AssemblyAI's live docs so it writes correct, current Voice Agent code instead of guessing from stale training data.","sidebarTitle":"Build with AI coding tools","href":"/voice-agents/voice-agent-api/build-with-ai-tools"},{"title":"Supported languages","description":"Input and output languages supported by the Voice Agent API.","href":"/voice-agents/voice-agent-api/supported-languages"}]},{"group":"Create \u0026 manage agents","pages":[{"title":"Create an agent","description":"Create a reusable voice agent with a single REST call.","sidebarTitle":"Create an agent","href":"/voice-agents/voice-agent-api/create-agent"},{"title":"Manage agents","description":"REST reference for creating and managing reusable voice agents. Endpoints, request and response schemas, the HTTP tool schema, and validation rules.","sidebarTitle":"Manage agents","href":"/voice-agents/voice-agent-api/manage-agents"},{"group":"Endpoints","pages":[{"title":"Create an agent","openapi":"api-reference/specs/agents.yaml POST /v1/agents","href":"/voice-agents/voice-agent-api/api-spec/create-agent"},{"title":"List agents","openapi":"api-reference/specs/agents.yaml GET /v1/agents","description":"List the agents for the authenticated account. Returns lightweight records (no tools or prompt), newest first.","href":"/voice-agents/voice-agent-api/api-spec/list-agents"},{"title":"Retrieve an agent","openapi":"api-reference/specs/agents.yaml GET /v1/agents/{agent_id}","description":"Retrieve a single agent by ID. Tool header **values** are masked as `\"***\"` in the response.","href":"/voice-agents/voice-agent-api/api-spec/get-agent"},{"title":"Update an agent","openapi":"api-reference/specs/agents.yaml PUT /v1/agents/{agent_id}","description":"Update an agent. Every field is optional. Send only the fields you want to\nchange. Returns the updated record.\n","href":"/voice-agents/voice-agent-api/api-spec/update-agent"},{"title":"Delete an agent","openapi":"api-reference/specs/agents.yaml DELETE /v1/agents/{agent_id}","description":"Delete an agent. Returns `204` with no body.","href":"/voice-agents/voice-agent-api/api-spec/delete-agent"}]}]},{"group":"Agent behavior","pages":[{"title":"Connect your own LLM","description":"Point a voice agent at your own OpenAI-compatible LLM endpoint instead of AssemblyAI's managed model.","sidebarTitle":"Connect your own LLM","href":"/voice-agents/voice-agent-api/connect-your-own-llm"},{"title":"Prompting guide","sidebarTitle":"Write the system prompt","description":"Patterns for writing system prompts that improve instruction following, conversationality, and voice output quality.","href":"/voice-agents/voice-agent-api/prompting-guide"},{"title":"Greeting","description":"Set the exact words a voice agent speaks when a conversation starts, or omit it to listen first.","sidebarTitle":"Greeting","href":"/voice-agents/voice-agent-api/greeting"},{"group":"Tools","pages":[{"title":"Tools","description":"Give your agent tools to fetch data and take actions, plus the parameter hints, execution modes, and patterns that make tool calls and turn-taking reliable.","sidebarTitle":"Overview","href":"/voice-agents/voice-agent-api/tools/overview"},{"title":"HTTP tools","description":"Server-side tools. Give your agent a URL and a parameter list, and AssemblyAI makes the request for you when the model calls the tool.","sidebarTitle":"HTTP tools","href":"/voice-agents/voice-agent-api/tools/http-tools"},{"title":"Client-side tools","description":"Function tools your own code runs. Declare them inline, handle the tool.call, and return a tool.result without breaking turn-taking.","sidebarTitle":"Client-side tools","href":"/voice-agents/voice-agent-api/tools/client-side-tools"}]}]},{"group":"Conversational experience","pages":[{"title":"Voices","description":"Pick a voice that matches your agent's personality and language.","sidebarTitle":"Choose a voice","href":"/voice-agents/voice-agent-api/voices"},{"title":"Output volume","description":"Set how loud a voice agent's speech plays back.","sidebarTitle":"Output volume","href":"/voice-agents/voice-agent-api/volume"},{"title":"Turn detection and interruptions","sidebarTitle":"Turn-taking \u0026 interruptions","description":"How the Voice Agent API decides when the user has finished speaking and when they're interrupting. On by default, no tuning required.","href":"/voice-agents/voice-agent-api/turn-detection-and-interruptions"},{"title":"Add transcription context","description":"Improve a voice agent's transcription accuracy for domain terms with a contextual prompt and a key terms list.","sidebarTitle":"Add transcription context","href":"/voice-agents/voice-agent-api/transcription-prompt"},{"title":"Steer toward known languages","description":"Steer a voice agent's speech-to-text toward the languages you expect with language_codes, or leave it on automatic multilingual detection.","sidebarTitle":"Steer toward known languages","href":"/voice-agents/voice-agent-api/language-selection"},{"title":"Isolate the caller's voice","description":"Isolate the caller's voice and suppress background noise before it reaches the agent's speech-to-text, with voice_focus.","sidebarTitle":"Isolate the caller's voice","href":"/voice-agents/voice-agent-api/noise-suppression"}]},{"group":"Deploy","pages":[{"title":"Deploy your agent","sidebarTitle":"Overview","description":null,"href":"/voice-agents/voice-agent-api/deploy"},{"title":"Browser integration","description":"Connect browser-based apps to the Voice Agent API using a temporary token.","sidebarTitle":"From a browser","href":"/voice-agents/voice-agent-api/browser-integration"},{"title":"Set up an inbound phone agent via SIP","sidebarTitle":"Over the phone (Twilio SIP)","description":"Point a Twilio number you already own at AssemblyAI over a SIP trunk and attach a voice agent. Inbound only.","href":"/voice-agents/voice-agent-api/connect-to-twilio"},{"title":"Audio format","sidebarTitle":"Audio format","description":null,"href":"/voice-agents/voice-agent-api/audio-format"}]},{"group":"Telephony","pages":[{"title":"Pre-connect requests","description":"Look the caller up in your systems before the phone call is answered.","sidebarTitle":"Pre-connect requests","href":"/voice-agents/voice-agent-api/pre-connect-requests"}]},{"group":"Test","pages":[{"title":"Test your agent with Bluejay simulations","sidebarTitle":"Bluejay simulations","description":"Run Bluejay's simulated callers against a stored voice agent through the open-source CHIRP bridge, then review the results on both sides.","href":"/voice-agents/voice-agent-api/test-with-bluejay"},{"title":"Test your agent with Cekura simulations","sidebarTitle":"Cekura simulations","description":"Have Cekura call your phone agent with simulated callers, then review each call with AssemblyAI's own transcript and tool calls.","href":"/voice-agents/voice-agent-api/test-with-cekura"}]},{"group":"After a session","pages":[{"title":"Recordings \u0026 transcripts","sidebarTitle":"Recordings \u0026 transcripts","description":null,"href":"/voice-agents/voice-agent-api/session-history"},{"group":"Endpoints","pages":[{"title":"List sessions","openapi":"api-reference/specs/agents.yaml GET /v1/sessions","description":"List sessions for the project that owns the API key, newest first. Results are\nscoped to that project, not your whole account, so use an API key from each\nproject whose sessions you want to list. Page forward by passing the previous\nresponse's `response_metadata.next_cursor` back as `cursor`.\n","href":"/voice-agents/voice-agent-api/api-spec/list-sessions"},{"title":"Retrieve a session","openapi":"api-reference/specs/agents.yaml GET /v1/sessions/{session_id}","description":"Retrieve a single session by ID, including its artifacts (recording, conversation\ntimeline, and metadata) as short-lived pre-signed download URLs.\n","href":"/voice-agents/voice-agent-api/api-spec/get-session"},{"title":"Delete a session","openapi":"api-reference/specs/agents.yaml DELETE /v1/sessions/{session_id}","description":"Soft-delete a session. Returns `204` with no body.","href":"/voice-agents/voice-agent-api/api-spec/delete-session"}]},{"title":"Webhooks","description":"Get a signed HTTPS callback when a session or phone call starts, connects, or ends, with the recording and transcript URLs for calls.","sidebarTitle":"Webhooks","href":"/voice-agents/voice-agent-api/webhooks"},{"group":"Webhook endpoints","pages":[{"title":"Create a webhook subscription","openapi":"api-reference/specs/webhooks.yaml POST /v1/webhook-subscriptions","description":"Subscribe a URL to one or more events. Scope to a single agent with agent_id, or omit it for account-wide events.","href":"/voice-agents/voice-agent-api/api-spec/create-webhook-subscription"},{"title":"List webhook subscriptions","openapi":"api-reference/specs/webhooks.yaml GET /v1/webhook-subscriptions","description":null,"href":"/voice-agents/voice-agent-api/api-spec/list-webhook-subscriptions"},{"title":"Retrieve a webhook subscription","openapi":"api-reference/specs/webhooks.yaml GET /v1/webhook-subscriptions/{subscription_id}","description":null,"href":"/voice-agents/voice-agent-api/api-spec/get-webhook-subscription"},{"title":"Update a webhook subscription","openapi":"api-reference/specs/webhooks.yaml PATCH /v1/webhook-subscriptions/{subscription_id}","description":"Update any of url, events, secret, or enabled. Sending a new secret rotates it and increments secret_version.","href":"/voice-agents/voice-agent-api/api-spec/update-webhook-subscription"},{"title":"Delete a webhook subscription","openapi":"api-reference/specs/webhooks.yaml DELETE /v1/webhook-subscriptions/{subscription_id}","description":null,"href":"/voice-agents/voice-agent-api/api-spec/delete-webhook-subscription"}]}]},{"group":"Reference","pages":[{"title":"Inline session configuration","description":"Configure a voice agent at connect-time over the WebSocket with session.update, without storing an agent.","sidebarTitle":"Inline config (advanced)","href":"/voice-agents/voice-agent-api/session-configuration"},{"title":"Events reference","description":"Every client-to-server and server-to-client event for the Voice Agent API.","sidebarTitle":"WebSocket events","href":"/voice-agents/voice-agent-api/events-reference"},{"title":"Troubleshooting","description":"Common issues and fixes when building with the Voice Agent API.","href":"/voice-agents/voice-agent-api/troubleshooting"}]},{"group":"API reference","pages":[{"title":"Message Sequence","sidebarTitle":"Message sequence","icon":"arrow-right-arrow-left","description":null,"href":"/voice-agents/voice-agent-api/message-sequence"},{"title":"Voice Agent WebSocket API","asyncapi":"api-reference/specs/voice-agent-api.yaml voiceAgent","description":"\nConnect to the Voice Agent API to run a real-time voice conversation. The client streams\nPCM16 audio to the server and receives the agent's spoken response (also PCM16), along with\ntranscripts, tool calls, and lifecycle events.\n\nAfter the WebSocket opens, send a [`session.update`](#sendSessionUpdate) as your\nfirst message. You have two ways to configure the agent:\n\n- **Stored agent.** Send `{ \"agent_id\": \"\u003cid>\" }` as the only field in `session`\n to bind to a reusable agent created via the\n [Agents REST API](https://www.assemblyai.com/docs/api-reference/voice-agent-api/create-agent). The stored\n `system_prompt`, `greeting`, `tools`, `input`, and `output` are applied\n server-side.\n- **Inline configuration.** Omit `agent_id` and send `system_prompt`, `greeting`,\n `tools`, `input`, and `output` directly. Useful for one-off or fully dynamic\n agents.\n\nThe two modes are mutually exclusive. See\n[Deploy your agent](https://www.assemblyai.com/docs/voice-agents/voice-agent-api/deploy) and\n[Inline session configuration](https://www.assemblyai.com/docs/voice-agents/voice-agent-api/session-configuration)\nfor details, or jump to the [Voice Agent API overview](https://www.assemblyai.com/docs/voice-agents/voice-agent-api)\nfor the full event flow and a runnable quickstart.\n","href":"/voice-agents/voice-agent-api/api-spec/voice-agent-websocket"},{"title":"Generate voice agent token","openapi":"api-reference/specs/voice-agent-token.yaml POST /v1/token","description":"Generate a temporary authentication token for the Voice Agent API. Use this to\nconnect browser or other client-side applications to the Voice Agent API without\nexposing your permanent API key. See\n[Browser integration](/voice-agents/voice-agent-api/browser-integration)\nfor the full flow.\n\nEach token is one-time use and can only be used for a single session. All usage\nis attributed to the API key that generated the token.\n","href":"/voice-agents/voice-agent-api/api-spec/generate-voice-agent-token"}]}]},{"tab":"Speech Understanding","pages":[{"title":"Speech Understanding","href":"/speech-understanding/getting-started"}]},{"tab":"LLM Gateway","pages":[{"title":"LLM Gateway","href":"/llm-gateway/quickstart"}]},{"tab":"FAQ","pages":[{"title":"FAQ","href":"/faq"}]}]},"basePath":"","title":"Create an agent - AssemblyAI","deploymentId":"dpl_53YqbBPsHdrqSGqXiWPGU7csRVod","buildId":"dpl_53YqbBPsHdrqSGqXiWPGU7csRVod","dynamics":["10e4515597","c2aa737661","2b790eda92","b0f84f53ff","a9bb46feb3"],"chunks":["BannerMarkdown-Dk-T3rBp.js","dist-DYCPzQwJ.js","lib-DMeTj1gb.js","lib-B8HbPgcC.js","katex-Dbtb6Wk7.js","html-void-elements-mCSPHezU.js","marked.esm-CZWythHk.js","OpenApiReferenceProvider-Ku9dSkH0.js","snippetPresets-Cjez4eet.js","utils-BqNa-fnS.js","style-to-object-BY3JEAdk.js","utils-DiE92JCe.js","v4-DIgz8zy6.js","addUniqueKeysToSchema-Bi0DpqVf.js","conditional-requirements-CFM0id0Q.js","cloneDeep-C6xnxscF.js","_Uint8Array-B7g0OYAt.js","isObject-FP1Yky1u.js","ApiExamples-Bf8Ecb5t.js","usePlaygroundInputsStore-BA942cq6.js","shallow-D0sePNkF.js","isEqual-CnnQO8sL.js","CodeSnippets-BTANoy1T.js","CodeSnippet-CTZvgJfu.js","getApiPlaygroundDisplay-BK2o1XYu.js","Page--B9YZ09u.js","DynamicMarkdown-CsgNpZb1.js","SectionHeading-C3K437Dy.js","icon-DlxjjqnB.js","MethodPill-Cr7Ib9nN.js","getPastedJson-DXo3wtHt.js","Check2Icon-ChEI-f_B.js","axios-CsQoIw0U.js","Markdown-CH4mv0N8.js","AssistantPageLink-BHjmqccN.js"]}