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"
    }
  ]
}
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
    }
  ],
  "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.

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[]
created_at
string<date-time>
updated_at
string<date-time>