Create an agent

Your agent — its prompt, voice, and tools — is one JSON object AssemblyAI stores for you. Create it once, then 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, 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.

POST https://agents.assemblyai.com/v1/agents with your API key in the Authorization header. Only name, system_prompt, and voice are required:

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" }
  }'

# 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())

// 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:

{ "id": "7ad24396-b822-4dca-871a-be9cc4781cf9", "name": "Support Assistant", "...": "..." }

Use that id to deploy your agent: 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:

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"'" }
    ]
  }'

# 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

// 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 / output.volume — Voices, Volume
greeting — Greeting
input/output.format — Audio encoding
input.turn_detection — Turn detection
input.keyterms — Keyterms
tools — Tools
llm — Connect your own LLM

For exact types, defaults, and validation, see the create-agent API reference (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.
Deploy by agent_id over the API, a browser, or a phone number. See Deploy your agent.

Next steps

Add tools

Server-side HTTP tools and client-side function tools.

Deploy your agent

Connect by agent_id over the API, a browser, or a phone number.

Prompting guide

Write system prompts that sound human and follow instructions.

Manage agents (REST)

Every endpoint, field, and validation rule.

Getting started

Create & manage agents

Agent behavior

Conversational experience

Deploy

After a session

Reference

API reference

Create an agent

Create an agent

A complete agent

Manage and deploy

Next steps

Add tools

Deploy your agent

Prompting guide

Manage agents (REST)

​Create an agent

​A complete agent

​Manage and deploy

​Next steps

Add tools

Deploy your agent

Prompting guide

Manage agents (REST)

Create an agent

A complete agent

Manage and deploy

Next steps