Skip to main content
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": "ivy"
  },
  "greeting": "Hi, how can I help?",
  "input": {
    "type": "audio",
    "format": {
      "encoding": "audio/pcm",
      "sample_rate": 24000
    },
    "turn_detection": {},
    "keyterms": [
      "<string>"
    ]
  },
  "output": {
    "type": "audio",
    "voice": "ivy",
    "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>"
    }
  ]
}
EOF
{
  "id": "7ad24396-b822-4dca-871a-be9cc4781cf9",
  "name": "Support Assistant",
  "system_prompt": "<string>",
  "greeting": "<string>",
  "voice": {
    "voice_id": "ivy"
  },
  "input": {
    "type": "audio",
    "format": {
      "encoding": "audio/pcm",
      "sample_rate": 24000
    },
    "turn_detection": {},
    "keyterms": [
      "<string>"
    ]
  },
  "output": {
    "type": "audio",
    "voice": "ivy",
    "format": {
      "encoding": "audio/pcm",
      "sample_rate": 24000
    },
    "volume": 123
  },
  "tools": [
    {
      "id": "<string>",
      "name": "<string>",
      "description": "<string>",
      "http": {
        "url": "<string>",
        "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
    }
  ],
  "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"
}

Authorizations

Authorization
string
header
required

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
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.

output
object

Audio output configuration. Defaults to PCM at 24 kHz with the agent's voice.

tools
object[]

Tools the agent can call.

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

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
input
object

Audio input configuration. Defaults to PCM at 24 kHz if omitted.

output
object

Audio output configuration. Defaults to PCM at 24 kHz with the agent's voice.

tools
object[]
llm
object[]

Connected LLM, if any. The api_key is write-only and never returned.

created_at
string<date-time>
updated_at
string<date-time>