> ## Documentation Index
> Fetch the complete documentation index at: https://assemblyai.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Create an agent
> Create a reusable voice agent with a single REST call.
Your agent — its prompt, voice, and tools — is one JSON object AssemblyAI stores for you. Create it once, then [deploy](/voice-agents/voice-agent-api/deploy) it by referencing its `agent_id` from your server, a browser, or a phone call.
**Configure once, deploy anywhere.** You can also configure an agent inline at connect-time over the WebSocket via [`session.update`](/voice-agents/voice-agent-api/session-configuration), which is handy for one-off or fully dynamic agents. But for anything you reuse, a stored agent is simpler: the config lives on the server, secrets stay off the client, and HTTP tools run server-side.
## Create an agent
`POST https://agents.assemblyai.com/v1/agents` with your API key in the `Authorization` header. Only `name`, `system_prompt`, and `voice` are required:
```bash cURL theme={null}
curl -X POST https://agents.assemblyai.com/v1/agents \
-H "Authorization: $ASSEMBLYAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Support Assistant",
"system_prompt": "You are a friendly support agent. Keep responses under two sentences.",
"greeting": "Hi, how can I help?",
"voice": { "voice_id": "ivy" }
}'
```
```python Python theme={null}
# pip install requests
import os
import requests
resp = requests.post(
"https://agents.assemblyai.com/v1/agents",
headers={"Authorization": os.environ["ASSEMBLYAI_API_KEY"]},
json={
"name": "Support Assistant",
"system_prompt": "You are a friendly support agent. Keep responses under two sentences.",
"greeting": "Hi, how can I help?",
"voice": {"voice_id": "ivy"},
},
)
resp.raise_for_status()
print(resp.json())
```
```javascript Node.js theme={null}
// Node 18+ has fetch built in
const res = await fetch("https://agents.assemblyai.com/v1/agents", {
method: "POST",
headers: {
Authorization: process.env.ASSEMBLYAI_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.",
greeting: "Hi, how can I help?",
voice: { voice_id: "ivy" },
}),
});
const data = await res.json();
console.log(data);
```
The response includes a generated `id`, which is what you deploy with:
```json theme={null}
{ "id": "7ad24396-b822-4dca-871a-be9cc4781cf9", "name": "Support Assistant", "...": "..." }
```
Use that id to [deploy your agent](/voice-agents/voice-agent-api/deploy): bind it by `agent_id` over the WebSocket, from a browser, or on a phone number.
## A complete agent
An agent is one JSON object. Here's **every field** in a single create call — copy it and delete what you don't need. Only `name`, `system_prompt`, and `voice` are required; everything else has a sensible default. Use Python or Node to skip cURL's quote-escaping when you edit longer fields like `system_prompt`:
```bash cURL expandable theme={null}
curl -X POST https://agents.assemblyai.com/v1/agents \
-H "Authorization: $ASSEMBLYAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Support Assistant",
"system_prompt": "You are a friendly support agent. Keep replies under two sentences.",
"greeting": "Hi, how can I help?",
"voice": { "voice_id": "ivy" },
"input": {
"format": { "encoding": "audio/pcm", "sample_rate": 24000 },
"keyterms": ["AssemblyAI", "Universal-3"],
"turn_detection": { "vad_threshold": 0.5, "min_silence": 1000, "max_silence": 3000, "interrupt_response": true }
},
"output": {
"voice": "ivy",
"format": { "encoding": "audio/pcm", "sample_rate": 24000 },
"volume": 100
},
"tools": [
{
"name": "get_weather",
"description": "Get current weather for a location.",
"parameters": {
"type": "object",
"properties": { "latitude": { "type": "number" }, "longitude": { "type": "number" } },
"required": ["latitude", "longitude"]
},
"http": { "url": "https://api.example.com/weather", "http_method": "GET" }
}
],
"llm": [
{ "base_url": "https://llm-gateway.assemblyai.com/v1", "model": "claude-sonnet-4-6", "api_key": "'"$ASSEMBLYAI_API_KEY"'" }
]
}'
```
```python Python expandable theme={null}
# pip install requests
import os
import requests
resp = requests.post(
"https://agents.assemblyai.com/v1/agents",
headers={"Authorization": os.environ["ASSEMBLYAI_API_KEY"]},
json={
"name": "Support Assistant",
"system_prompt": "You are a friendly support agent. Keep replies under two sentences.",
"greeting": "Hi, how can I help?",
"voice": {"voice_id": "ivy"},
"input": {
"format": {"encoding": "audio/pcm", "sample_rate": 24000},
"keyterms": ["AssemblyAI", "Universal-3"],
"turn_detection": {
"vad_threshold": 0.5, "min_silence": 1000,
"max_silence": 3000, "interrupt_response": True,
},
},
"output": {
"voice": "ivy",
"format": {"encoding": "audio/pcm", "sample_rate": 24000},
"volume": 100,
},
"tools": [
{
"name": "get_weather",
"description": "Get current weather for a location.",
"parameters": {
"type": "object",
"properties": {
"latitude": {"type": "number"},
"longitude": {"type": "number"},
},
"required": ["latitude", "longitude"],
},
"http": {"url": "https://api.example.com/weather", "http_method": "GET"},
}
],
"llm": [
{
"base_url": "https://llm-gateway.assemblyai.com/v1",
"model": "claude-sonnet-4-6",
"api_key": os.environ["ASSEMBLYAI_API_KEY"],
}
],
},
)
resp.raise_for_status()
print(resp.json()["id"]) # the agent_id you connect with
```
```javascript Node.js expandable theme={null}
// Node 18+ has fetch built in
const res = await fetch("https://agents.assemblyai.com/v1/agents", {
method: "POST",
headers: {
Authorization: process.env.ASSEMBLYAI_API_KEY,
"Content-Type": "application/json",
},
body: JSON.stringify({
name: "Support Assistant",
system_prompt: "You are a friendly support agent. Keep replies under two sentences.",
greeting: "Hi, how can I help?",
voice: { voice_id: "ivy" },
input: {
format: { encoding: "audio/pcm", sample_rate: 24000 },
keyterms: ["AssemblyAI", "Universal-3"],
turn_detection: {
vad_threshold: 0.5, min_silence: 1000,
max_silence: 3000, interrupt_response: true,
},
},
output: {
voice: "ivy",
format: { encoding: "audio/pcm", sample_rate: 24000 },
volume: 100,
},
tools: [
{
name: "get_weather",
description: "Get current weather for a location.",
parameters: {
type: "object",
properties: { latitude: { type: "number" }, longitude: { type: "number" } },
required: ["latitude", "longitude"],
},
http: { url: "https://api.example.com/weather", http_method: "GET" },
},
],
llm: [
{
base_url: "https://llm-gateway.assemblyai.com/v1",
model: "claude-sonnet-4-6",
api_key: process.env.ASSEMBLYAI_API_KEY,
},
],
}),
});
const agent = await res.json();
console.log(agent.id); // the agent_id you connect with
```
Defaults if omitted: `input`/`output` use PCM at 24 kHz, `tools` and `llm` are empty (managed model), and `greeting` is none (the agent listens first). Go deeper on each field:
* `system_prompt` — [Prompting guide](/voice-agents/voice-agent-api/prompting-guide)
* `voice` / `output.volume` — [Voices](/voice-agents/voice-agent-api/voices), [Volume](/voice-agents/voice-agent-api/volume)
* `greeting` — [Greeting](/voice-agents/voice-agent-api/greeting)
* `input`/`output.format` — [Audio encoding](/voice-agents/voice-agent-api/encoding)
* `input.turn_detection` — [Turn detection](/voice-agents/voice-agent-api/turn-detection-and-interruptions)
* `input.keyterms` — [Keyterms](/voice-agents/voice-agent-api/keyterms)
* `tools` — [Tools](/voice-agents/voice-agent-api/tools/overview)
* `llm` — [Connect your own LLM](/voice-agents/voice-agent-api/connect-your-own-llm)
For exact types, defaults, and validation, see the [create-agent API reference](/api-reference/voice-agent-api/create-agent) (generated from the spec, always in sync).
## Manage and deploy
* **Update** with `PUT /v1/agents/{id}` (send only the fields that change); also list, retrieve, and delete. See the [Manage agents reference](/voice-agents/voice-agent-api/manage-agents).
* **Deploy** by `agent_id` over the API, a browser, or a phone number. See [Deploy your agent](/voice-agents/voice-agent-api/deploy).
## Next steps
Server-side HTTP tools and client-side function tools.
Connect by `agent_id` over the API, a browser, or a phone number.
Write system prompts that sound human and follow instructions.
Every endpoint, field, and validation rule.