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"
]
}
]
}
EOFimport 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": "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"]
}
]
}
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: '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']
}
]
})
};
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' => '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'
]
]
]
]),
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\": \"alba\"\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\": \"alba\",\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 \"pre_connect_requests\": [\n {\n \"http\": {\n \"url\": \"https://api.example.com/weather\",\n \"http_method\": \"POST\",\n \"headers\": {}\n },\n \"sends\": [\n \"caller_number\"\n ],\n \"returns\": [\n {\n \"name\": \"patient_name\",\n \"path\": \"patient.first_name\",\n \"default\": \"there\"\n }\n ],\n \"timeout_ms\": 600,\n \"allow_overrides\": [\n \"greeting\"\n ]\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\": \"alba\"\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\": \"alba\",\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 \"pre_connect_requests\": [\n {\n \"http\": {\n \"url\": \"https://api.example.com/weather\",\n \"http_method\": \"POST\",\n \"headers\": {}\n },\n \"sends\": [\n \"caller_number\"\n ],\n \"returns\": [\n {\n \"name\": \"patient_name\",\n \"path\": \"patient.first_name\",\n \"default\": \"there\"\n }\n ],\n \"timeout_ms\": 600,\n \"allow_overrides\": [\n \"greeting\"\n ]\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\": \"alba\"\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\": \"alba\",\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 \"pre_connect_requests\": [\n {\n \"http\": {\n \"url\": \"https://api.example.com/weather\",\n \"http_method\": \"POST\",\n \"headers\": {}\n },\n \"sends\": [\n \"caller_number\"\n ],\n \"returns\": [\n {\n \"name\": \"patient_name\",\n \"path\": \"patient.first_name\",\n \"default\": \"there\"\n }\n ],\n \"timeout_ms\": 600,\n \"allow_overrides\": [\n \"greeting\"\n ]\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": "alba"
},
"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": [
{
"id": "<string>",
"name": "<string>",
"description": "<string>",
"http": {
"url": "<string>",
"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": "<string>",
"http_method": "GET",
"headers": {
"Authorization": "***"
}
},
"sends": [
"<string>"
],
"returns": [
{
"name": "patient_name",
"path": "patient.first_name",
"default": "there"
}
],
"timeout_ms": 123,
"allow_overrides": [
"<string>"
]
}
]
}{
"detail": "Unauthorized"
}{
"detail": "Unauthorized"
}{
"detail": "Unauthorized"
}Endpoints
Create an agent
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"
]
}
]
}
EOFimport 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": "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"]
}
]
}
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: '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']
}
]
})
};
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' => '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'
]
]
]
]),
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\": \"alba\"\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\": \"alba\",\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 \"pre_connect_requests\": [\n {\n \"http\": {\n \"url\": \"https://api.example.com/weather\",\n \"http_method\": \"POST\",\n \"headers\": {}\n },\n \"sends\": [\n \"caller_number\"\n ],\n \"returns\": [\n {\n \"name\": \"patient_name\",\n \"path\": \"patient.first_name\",\n \"default\": \"there\"\n }\n ],\n \"timeout_ms\": 600,\n \"allow_overrides\": [\n \"greeting\"\n ]\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\": \"alba\"\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\": \"alba\",\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 \"pre_connect_requests\": [\n {\n \"http\": {\n \"url\": \"https://api.example.com/weather\",\n \"http_method\": \"POST\",\n \"headers\": {}\n },\n \"sends\": [\n \"caller_number\"\n ],\n \"returns\": [\n {\n \"name\": \"patient_name\",\n \"path\": \"patient.first_name\",\n \"default\": \"there\"\n }\n ],\n \"timeout_ms\": 600,\n \"allow_overrides\": [\n \"greeting\"\n ]\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\": \"alba\"\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\": \"alba\",\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 \"pre_connect_requests\": [\n {\n \"http\": {\n \"url\": \"https://api.example.com/weather\",\n \"http_method\": \"POST\",\n \"headers\": {}\n },\n \"sends\": [\n \"caller_number\"\n ],\n \"returns\": [\n {\n \"name\": \"patient_name\",\n \"path\": \"patient.first_name\",\n \"default\": \"there\"\n }\n ],\n \"timeout_ms\": 600,\n \"allow_overrides\": [\n \"greeting\"\n ]\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": "alba"
},
"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": [
{
"id": "<string>",
"name": "<string>",
"description": "<string>",
"http": {
"url": "<string>",
"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": "<string>",
"http_method": "GET",
"headers": {
"Authorization": "***"
}
},
"sends": [
"<string>"
],
"returns": [
{
"name": "patient_name",
"path": "patient.first_name",
"default": "there"
}
],
"timeout_ms": 123,
"allow_overrides": [
"<string>"
]
}
]
}{
"detail": "Unauthorized"
}{
"detail": "Unauthorized"
}{
"detail": "Unauthorized"
}Authorizations
Your AssemblyAI API key in the Authorization header. The raw key works directly; a Bearer prefix is also accepted.
Body
application/json
Display name for the agent.
Example:
"Support Assistant"
The agent's instructions. Write voice-first.
Example:
"You are a friendly support agent. Keep responses under two sentences."
Show child attributes
Show child attributes
Spoken on connect; sent straight to TTS. Omit to listen first.
Example:
"Hi, how can I help?"
Audio input configuration. Defaults to PCM at 24 kHz if omitted.
Show child attributes
Show child attributes
Audio output configuration. Defaults to PCM at 24 kHz with the agent's voice.
Show child attributes
Show child attributes
Tools the agent can call.
Show child attributes
Show child attributes
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:
1Show child attributes
Show child attributes
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:
2Show child attributes
Show child attributes
Response
Agent created.
A stored voice agent.
Example:
"7ad24396-b822-4dca-871a-be9cc4781cf9"
Example:
"Support Assistant"
Show child attributes
Show child attributes
Audio input configuration. Defaults to PCM at 24 kHz if omitted.
Show child attributes
Show child attributes
Audio output configuration. Defaults to PCM at 24 kHz with the agent's voice.
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Connected LLM, if any. The api_key is write-only and never returned.
Show child attributes
Show child attributes
The declared pre-connect requests. Header values are never returned.
Show child attributes
Show child attributes
Was this page helpful?