Skip to main content
The Voice Agent API lets you configure a reusable voice agent with a single REST call: its personality, voice, and tools. You create it once and AssemblyAI stores the configuration. After that you deploy the same agent across any channel (a phone number, a browser, or your own app) by referencing its agent_id.
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.

​
What’s in an agent

An agent bundles everything that shapes how it sounds and behaves. Each piece has its own guide:
  • system_prompt: the agent’s instructions and personality. See the Prompting guide.
  • voice: the TTS voice, e.g. { "voice_id": "ivy" }. See Voices.
  • greeting: the exact words spoken on connect (sent straight to TTS). Omit to listen first.
  • tools: actions the agent can take. HTTP tools run server-side. See Add tools below.
  • input / output: audio format, turn detection, keyterms, and volume. Default to PCM at 24 kHz; the fields are identical whether stored on an agent or sent inline, and are documented in Session configuration.
For the complete request and response schema, defaults, and validation rules, see the Manage agents reference.

​
Add a tool

Add a tools array and the agent can take actions and fetch live data. With an HTTP tool, you give a URL and a JSON-Schema parameter spec, and AssemblyAI calls your endpoint whenever the model invokes the tool, and your client never sees it: 
{
  "name": "get_weather",
  "description": "Get current weather for a location. Use whenever the user asks about weather.",
  "parameters": {
    "type": "object",
    "properties": {
      "latitude":  { "type": "number", "description": "Latitude in decimal degrees." },
      "longitude": { "type": "number", "description": "Longitude in decimal degrees." }
    },
    "required": ["latitude", "longitude"]
  },
  "http": { "url": "https://api.example.com/weather", "http_method": "GET" }
}
See Add tools for the full tool model: HTTP vs. client-side tools, how arguments map to the request, parameter hints, execution modes, and security.

​
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.