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
import requests

url = "https://agents.assemblyai.com/v1/agents"

payload = {
    "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>"
        }
    ]
}
headers = {
    "Authorization": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)
const options = {
  method: 'POST',
  headers: {Authorization: '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    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>'
      }
    ]
  })
};

fetch('https://agents.assemblyai.com/v1/agents', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));
<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://agents.assemblyai.com/v1/agents",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    '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>'
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: <api-key>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://agents.assemblyai.com/v1/agents"

	payload := strings.NewReader("{\n  \"name\": \"Support Assistant\",\n  \"system_prompt\": \"You are a friendly support agent. Keep responses under two sentences.\",\n  \"voice\": {\n    \"voice_id\": \"ivy\"\n  },\n  \"greeting\": \"Hi, how can I help?\",\n  \"input\": {\n    \"type\": \"audio\",\n    \"format\": {\n      \"encoding\": \"audio/pcm\",\n      \"sample_rate\": 24000\n    },\n    \"turn_detection\": {},\n    \"keyterms\": [\n      \"<string>\"\n    ]\n  },\n  \"output\": {\n    \"type\": \"audio\",\n    \"voice\": \"ivy\",\n    \"format\": {\n      \"encoding\": \"audio/pcm\",\n      \"sample_rate\": 24000\n    },\n    \"volume\": 123\n  },\n  \"tools\": [\n    {\n      \"name\": \"get_weather\",\n      \"description\": \"Get current weather for a location. Use whenever the user asks about weather.\",\n      \"parameters\": {\n        \"type\": \"object\",\n        \"properties\": {\n          \"order_id\": {\n            \"type\": \"string\",\n            \"description\": \"The customer's order ID.\",\n            \"examples\": [\n              \"AB-12345\"\n            ],\n            \"pattern\": \"[A-Z]{2}-\\\\d{5}\"\n          }\n        },\n        \"required\": [\n          \"order_id\"\n        ]\n      },\n      \"timeout_seconds\": 120,\n      \"execution_mode\": \"interactive\"\n    }\n  ],\n  \"llm\": [\n    {\n      \"base_url\": \"https://api.openai.com/v1\",\n      \"model\": \"gpt-4o-mini\",\n      \"api_key\": \"<string>\"\n    }\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}
HttpResponse<String> response = Unirest.post("https://agents.assemblyai.com/v1/agents")
  .header("Authorization", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"Support Assistant\",\n  \"system_prompt\": \"You are a friendly support agent. Keep responses under two sentences.\",\n  \"voice\": {\n    \"voice_id\": \"ivy\"\n  },\n  \"greeting\": \"Hi, how can I help?\",\n  \"input\": {\n    \"type\": \"audio\",\n    \"format\": {\n      \"encoding\": \"audio/pcm\",\n      \"sample_rate\": 24000\n    },\n    \"turn_detection\": {},\n    \"keyterms\": [\n      \"<string>\"\n    ]\n  },\n  \"output\": {\n    \"type\": \"audio\",\n    \"voice\": \"ivy\",\n    \"format\": {\n      \"encoding\": \"audio/pcm\",\n      \"sample_rate\": 24000\n    },\n    \"volume\": 123\n  },\n  \"tools\": [\n    {\n      \"name\": \"get_weather\",\n      \"description\": \"Get current weather for a location. Use whenever the user asks about weather.\",\n      \"parameters\": {\n        \"type\": \"object\",\n        \"properties\": {\n          \"order_id\": {\n            \"type\": \"string\",\n            \"description\": \"The customer's order ID.\",\n            \"examples\": [\n              \"AB-12345\"\n            ],\n            \"pattern\": \"[A-Z]{2}-\\\\d{5}\"\n          }\n        },\n        \"required\": [\n          \"order_id\"\n        ]\n      },\n      \"timeout_seconds\": 120,\n      \"execution_mode\": \"interactive\"\n    }\n  ],\n  \"llm\": [\n    {\n      \"base_url\": \"https://api.openai.com/v1\",\n      \"model\": \"gpt-4o-mini\",\n      \"api_key\": \"<string>\"\n    }\n  ]\n}")
  .asString();
require 'uri'
require 'net/http'

url = URI("https://agents.assemblyai.com/v1/agents")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"Support Assistant\",\n  \"system_prompt\": \"You are a friendly support agent. Keep responses under two sentences.\",\n  \"voice\": {\n    \"voice_id\": \"ivy\"\n  },\n  \"greeting\": \"Hi, how can I help?\",\n  \"input\": {\n    \"type\": \"audio\",\n    \"format\": {\n      \"encoding\": \"audio/pcm\",\n      \"sample_rate\": 24000\n    },\n    \"turn_detection\": {},\n    \"keyterms\": [\n      \"<string>\"\n    ]\n  },\n  \"output\": {\n    \"type\": \"audio\",\n    \"voice\": \"ivy\",\n    \"format\": {\n      \"encoding\": \"audio/pcm\",\n      \"sample_rate\": 24000\n    },\n    \"volume\": 123\n  },\n  \"tools\": [\n    {\n      \"name\": \"get_weather\",\n      \"description\": \"Get current weather for a location. Use whenever the user asks about weather.\",\n      \"parameters\": {\n        \"type\": \"object\",\n        \"properties\": {\n          \"order_id\": {\n            \"type\": \"string\",\n            \"description\": \"The customer's order ID.\",\n            \"examples\": [\n              \"AB-12345\"\n            ],\n            \"pattern\": \"[A-Z]{2}-\\\\d{5}\"\n          }\n        },\n        \"required\": [\n          \"order_id\"\n        ]\n      },\n      \"timeout_seconds\": 120,\n      \"execution_mode\": \"interactive\"\n    }\n  ],\n  \"llm\": [\n    {\n      \"base_url\": \"https://api.openai.com/v1\",\n      \"model\": \"gpt-4o-mini\",\n      \"api_key\": \"<string>\"\n    }\n  ]\n}"

response = http.request(request)
puts response.read_body
{
  "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"
}
{
  "detail": "Unauthorized"
}
{
  "detail": "Unauthorized"
}
{
  "detail": "Unauthorized"
}

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>