> ## 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. # Update an agent ## OpenAPI ````yaml specs/agents.yaml PUT /v1/agents/{agent_id} openapi: 3.0.3 info: title: AssemblyAI Voice Agents API description: > REST API for creating and managing reusable voice agents. An agent stores its system prompt, greeting, voice, and tools server-side, so you can deploy the same agent across the WebSocket API, a browser, or Twilio by referencing its `id`. See [Create an agent](/voice-agents/voice-agent-api/create-agent) for a guided walkthrough. version: 1.0.0 termsOfService: https://www.assemblyai.com/legal/terms-of-service contact: name: API Support email: support@assemblyai.com url: https://www.assemblyai.com/docs/ servers: - url: https://agents.assemblyai.com description: Production server x-fern-server-name: Default security: [] paths: /v1/agents/{agent_id}: parameters: - name: agent_id in: path required: true description: The agent's unique ID. schema: type: string example: 7ad24396-b822-4dca-871a-be9cc4781cf9 put: summary: Update an agent description: > Update an agent. Every field is optional. Send only the fields you want to change. Returns the updated record. operationId: updateAgent requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/AgentUpdateRequest' responses: '200': description: The updated agent record. content: application/json: schema: $ref: '#/components/schemas/Agent' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' '422': $ref: '#/components/responses/UnprocessableEntity' security: - apiKey: [] components: schemas: AgentUpdateRequest: type: object description: >- Same shape as the create request, but every field is optional. Send only what changes. properties: name: type: string system_prompt: type: string voice: $ref: '#/components/schemas/VoiceConfig' greeting: type: string nullable: true input: $ref: '#/components/schemas/AudioInput' output: $ref: '#/components/schemas/AudioOutput' tools: type: array items: $ref: '#/components/schemas/ToolDefinition' llm: type: array maxItems: 1 items: $ref: '#/components/schemas/LlmConfig' Agent: type: object description: A stored voice agent. properties: id: type: string example: 7ad24396-b822-4dca-871a-be9cc4781cf9 name: type: string example: Support Assistant system_prompt: type: string greeting: type: string nullable: true voice: $ref: '#/components/schemas/VoiceConfig' input: $ref: '#/components/schemas/AudioInput' output: $ref: '#/components/schemas/AudioOutput' tools: type: array items: $ref: '#/components/schemas/ToolResponse' llm: type: array description: Connected LLM, if any. The api_key is write-only and never returned. items: $ref: '#/components/schemas/LlmConfigResponse' created_at: type: string format: date-time updated_at: type: string format: date-time VoiceConfig: type: object required: - voice_id properties: voice_id: type: string description: >- A voice from the voice catalog. An invalid id returns 400 with the list of valid voices. example: ivy AudioInput: type: object description: Audio input configuration. Defaults to PCM at 24 kHz if omitted. properties: type: type: string default: audio format: $ref: '#/components/schemas/AudioFormat' turn_detection: type: object nullable: true description: VAD tuning, or null for adaptive defaults. keyterms: type: array nullable: true description: Up to 100 transcription-bias strings, or null. items: type: string AudioOutput: type: object description: >- Audio output configuration. Defaults to PCM at 24 kHz with the agent's voice. properties: type: type: string default: audio voice: type: string example: ivy format: $ref: '#/components/schemas/AudioFormat' volume: type: number nullable: true description: Playback volume 0–100, or null for native level. ToolDefinition: type: object required: - name - description properties: name: type: string description: Tool name the model calls. example: get_weather description: type: string description: When to call the tool. The model's main signal. example: >- Get current weather for a location. Use whenever the user asks about weather. parameters: $ref: '#/components/schemas/ToolParameters' http: $ref: '#/components/schemas/HttpToolConfig' timeout_seconds: type: integer minimum: 1 maximum: 300 default: 120 execution_mode: type: string enum: - interactive - hold default: interactive description: How the agent behaves while the tool runs. LlmConfig: type: object required: - base_url - model - api_key description: | An OpenAI-compatible chat-completions endpoint used as the agent's conversational LLM in place of AssemblyAI's managed model. properties: base_url: type: string description: >- HTTPS base URL of the OpenAI-compatible endpoint. Must be https and resolve to a public host. example: https://api.openai.com/v1 model: type: string description: Model name sent in the chat-completions request body. example: gpt-4o-mini api_key: type: string description: >- API key for the endpoint. Write-only — encrypted at rest and never returned in any response. ToolResponse: type: object description: A tool as returned in an agent record. Header values are masked. properties: id: type: string name: type: string description: type: string http: $ref: '#/components/schemas/HttpToolConfigResponse' parameters: $ref: '#/components/schemas/ToolParameters' timeout_seconds: type: integer execution_mode: type: string enum: - interactive - hold LlmConfigResponse: type: object description: >- A connected LLM as returned in an agent record. The api_key is never included. properties: base_url: type: string example: https://api.openai.com/v1 model: type: string example: gpt-4o-mini Error: type: object properties: detail: type: string description: Error message describing what went wrong. example: Unauthorized AudioFormat: type: object properties: encoding: type: string enum: - audio/pcm - audio/pcmu - audio/pcma default: audio/pcm sample_rate: type: integer example: 24000 ToolParameters: type: object description: > A JSON Schema describing the tool's arguments. The same form for HTTP and client-side tools. Each property accepts standard JSON-Schema keywords; beyond `type` and `description`, use `enum`, `examples`, `pattern`, and `format` to sharpen tool-calling and turn-detection accuracy. properties: type: type: string enum: - object default: object properties: type: object description: Map of argument name to its JSON-Schema definition. additionalProperties: true required: type: array description: Names of the required arguments. items: type: string example: 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 HttpToolConfig: type: object required: - url description: >- Makes the tool a server-side HTTP tool. AssemblyAI calls this endpoint when the model invokes the tool. properties: url: type: string description: Must be https and resolve to a public host. Max 2048 chars. example: https://api.example.com/weather http_method: type: string enum: - GET - POST - PUT - PATCH - DELETE default: POST description: >- GET/DELETE send arguments as query params; POST/PUT/PATCH send them as a JSON body. headers: type: object nullable: true description: >- Sent on every call. Values are encrypted at rest and write-only (masked as "***" in responses). additionalProperties: type: string HttpToolConfigResponse: type: object properties: url: type: string http_method: type: string enum: - GET - POST - PUT - PATCH - DELETE headers: type: object description: Header names with values masked as "***". additionalProperties: type: string example: Authorization: '***' responses: BadRequest: description: >- Bad request. A field failed validation (e.g. invalid voice, non-https tool URL, timeout out of range). content: application/json: schema: $ref: '#/components/schemas/Error' Unauthorized: description: >- Unauthorized. Invalid or missing API key, or the key is not entitled for Voice Agents. content: application/json: schema: $ref: '#/components/schemas/Error' NotFound: description: The agent was not found. content: application/json: schema: $ref: '#/components/schemas/Error' UnprocessableEntity: description: Unprocessable entity. Malformed JSON or a field of the wrong type. content: application/json: schema: $ref: '#/components/schemas/Error' securitySchemes: apiKey: type: apiKey in: header name: Authorization description: >- Your AssemblyAI API key in the `Authorization` header. The raw key works directly; a `Bearer ` prefix is also accepted. ````