Skip to main content
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.

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