---
title: "Update one agent"
method: PATCH
path: "/v1/agents/{agent_id}"
---

# Update one agent

`PATCH /v1/agents/{agent_id}`

## Request

- Base URL: `https://api.skysay.ai`
- URL: `https://api.skysay.ai/v1/agents/{agent_id}`
- Auth: none declared

The authenticated workspace is resolved from the target agent. For an attached Integration Action, send a connection tool attachment; the model sees only the resolved action name and input schema, never the Integration endpoint or signing secret.

## Path parameters

- `agent_id` string, required

## Request body

- AgentUpdate: Mutable agent configuration. The target agent, rather than organization_id or project_id in this body, defines the authenticated workspace boundary. Voice-stack settings are not part of this payload: opening, turn_taking, voice_polish, answer_detection, navigation, audio_environment, follow_caller, languages and language_profiles are saved by PATCH /v1/agents/{agent_id}/voice-stack, and sending one here is refused with 400 naming that route rather than accepted and dropped.
  - `audio_stream_url` string
  - `begin_message` string
  - `expected_tools` AgentTool[]: Optional previously read complete tools array, including read-only refs. With a tools replacement, a mismatch returns 409 with error AgentToolsChangedError and writes nothing. Workspace editors and calendar attachment send it to avoid lost changes.
    - union: A legacy string placeholder, a built-in tool, a signed webhook tool, or an attached Integration Action. The names `press_digits`, `wait_on_hold` and `abandon_navigation` are reserved for phone-menu navigation and refused with 400.
      - string: Legacy tool placeholder.
      - BuiltinAgentTool: A built-in tool the AI agent can invoke during a call. `phone_number` is conditionally required: see its own description.
        - `connection_id` string: Required for calendar builtins: one active, owner-configured calendar connection in the AI agent's organization/project. The model cannot select it.
        - `country` string
        - `name` 'end_call' | 'send_sms' | 'transfer_to_human' | 'request_callback' | 'set_call_disposition' | 'calendar_check_availability' | 'calendar_book_appointment', required
        - `phone_number` string: Destination for `transfer_to_human`, and required when that tool is enabled. Must be full E.164 including the leading `+` and country code (for example `+12025550100`); a blank, partial, or non-dialable number is rejected when the agent is created or updated, rather than failing mid-call. Ignored by `end_call` and `send_sms`.
        - `ref` string: Read-only, server-issued. A stable opaque identifier for this configured tool, used to name the tool on a call's transcript rows without storing the tool's own name with them. Ignored if you send it: the value is taken from what is already stored, so it cannot be chosen. It survives any edit that keeps the tool's `name` and `type`; renaming, retyping or removing a tool retires its identifier, and transcript rows recorded before that show the tool's kind instead of a name.
        - `type` 'builtin', required
      - WebhookAgentTool
        - `description` string
        - `name` string, required
        - `parameters` object
        - `ref` string: Read-only, server-issued. A stable opaque identifier for this configured tool, used to name the tool on a call's transcript rows without storing the tool's own name with them. Ignored if you send it: the value is taken from what is already stored, so it cannot be chosen. It survives any edit that keeps the tool's `name` and `type`; renaming, retyping or removing a tool retires its identifier, and transcript rows recorded before that show the tool's kind instead of a name.
        - `type` 'webhook', required
        - `url` string, uri, required
      - IntegrationActionAttachment: Explicitly attaches one existing Integration Action to this agent. The model cannot choose another action or endpoint.
        - `connection_id` string, required
        - `name` string, required
        - `ref` string: Read-only, server-issued. A stable opaque identifier for this configured tool, used to name the tool on a call's transcript rows without storing the tool's own name with them. Ignored if you send it: the value is taken from what is already stored, so it cannot be chosen. It survives any edit that keeps the tool's `name` and `type`; renaming, retyping or removing a tool retires its identifier, and transcript rows recorded before that show the tool's kind instead of a name.
        - `tool_id` string, required
        - `type` 'connection', required
  - `first_message` string
  - `language` string
  - `metadata` object: Replaces the agent's free-form metadata. The sections the voice-stack route owns are kept as stored when you leave them out, and a different value for one of them is refused with 400 naming PATCH /v1/agents/{agent_id}/voice-stack: `follow_caller`, `opening` and `navigation` (so a phone-menu navigation choice, including an explicit off, survives any metadata replacement).
  - `mode` 'external_audio' | 'external_text' | 'hosted'
  - `name` string
  - `recording_enabled` boolean
  - `status` 'active' | 'inactive': Whether this agent is offered to callers. `inactive` stops it being admitted on every call path -- inbound and outbound telephony, the browser test, and the public homepage demo -- while keeping the agent, its configuration and its number attachments intact; a call already in progress is not torn down. `active` removes that gate and nothing else: no configuration is snapshotted or restored, so the agent is then admitted on its CURRENT published configuration and readiness, which may have changed while it was inactive. Accepts these two values only; any other is refused with 400, as is any change to an agent whose stored status is not already one of them (an operator-suspended agent is reinstated by an operator only).
  - `system_prompt` string
  - `tools` AgentTool[]: Complete agent tool allowlist. To attach an Integration Action, use an AgentTool object whose type is connection.
    - union: A legacy string placeholder, a built-in tool, a signed webhook tool, or an attached Integration Action. The names `press_digits`, `wait_on_hold` and `abandon_navigation` are reserved for phone-menu navigation and refused with 400.
      - string: Legacy tool placeholder.
      - BuiltinAgentTool: A built-in tool the AI agent can invoke during a call. `phone_number` is conditionally required: see its own description.
        - `connection_id` string: Required for calendar builtins: one active, owner-configured calendar connection in the AI agent's organization/project. The model cannot select it.
        - `country` string
        - `name` 'end_call' | 'send_sms' | 'transfer_to_human' | 'request_callback' | 'set_call_disposition' | 'calendar_check_availability' | 'calendar_book_appointment', required
        - `phone_number` string: Destination for `transfer_to_human`, and required when that tool is enabled. Must be full E.164 including the leading `+` and country code (for example `+12025550100`); a blank, partial, or non-dialable number is rejected when the agent is created or updated, rather than failing mid-call. Ignored by `end_call` and `send_sms`.
        - `ref` string: Read-only, server-issued. A stable opaque identifier for this configured tool, used to name the tool on a call's transcript rows without storing the tool's own name with them. Ignored if you send it: the value is taken from what is already stored, so it cannot be chosen. It survives any edit that keeps the tool's `name` and `type`; renaming, retyping or removing a tool retires its identifier, and transcript rows recorded before that show the tool's kind instead of a name.
        - `type` 'builtin', required
      - WebhookAgentTool
        - `description` string
        - `name` string, required
        - `parameters` object
        - `ref` string: Read-only, server-issued. A stable opaque identifier for this configured tool, used to name the tool on a call's transcript rows without storing the tool's own name with them. Ignored if you send it: the value is taken from what is already stored, so it cannot be chosen. It survives any edit that keeps the tool's `name` and `type`; renaming, retyping or removing a tool retires its identifier, and transcript rows recorded before that show the tool's kind instead of a name.
        - `type` 'webhook', required
        - `url` string, uri, required
      - IntegrationActionAttachment: Explicitly attaches one existing Integration Action to this agent. The model cannot choose another action or endpoint.
        - `connection_id` string, required
        - `name` string, required
        - `ref` string: Read-only, server-issued. A stable opaque identifier for this configured tool, used to name the tool on a call's transcript rows without storing the tool's own name with them. Ignored if you send it: the value is taken from what is already stored, so it cannot be chosen. It survives any edit that keeps the tool's `name` and `type`; renaming, retyping or removing a tool retires its identifier, and transcript rows recorded before that show the tool's kind instead of a name.
        - `tool_id` string, required
        - `type` 'connection', required
  - `translation` TranslationPolicy
    - `enabled` boolean
    - `target_languages` string[]
  - `voice` union
    - string: Legacy pinned voice identifier.
    - object: Exact selected TTS provider/model/voice inventory item.
      - `model` string, required
      - `provider` string, required
      - `voice_id` string: Provider inventory id, when the selected provider exposes voices.
  - `webhook_url` string

## Response `200`

Agent

## Other responses

- `400`: Invalid field value, a voice-stack setting sent to this route, or a status this route may not write
- `409`: Concurrent tool-list replacement is refused with error AgentToolsChangedError; reload the AI agent before saving. Other conflicts retain their own error code.

---

[API](https://skmtc.dev/skysay/apis/skysay-api.md) · [All operations](https://skmtc.dev/skysay/apis/skysay-api/llms.txt) · [OpenAPI document](https://skmtc.dev/skysay/apis/skysay-api/revisions/148c7e111260?raw)