# Update an agent

> PATCH /v2/agents/{agentId}

`PATCH https://api.zavu.dev/v2/agents/{agentId}`

## Parameters

- `agentId` (path, string, required)

## Body

- `name` (string)
- `enabled` (boolean)
- `provider` (string): LLM provider for the AI agent. One of: `openai`, `anthropic`, `google`, `mistral`, `zavu`.
- `model` (string)
- `systemPrompt` (string)
- `apiKey` (string)
- `contextWindowMessages` (integer)
- `includeContactMetadata` (boolean)
- `maxTokens` (integer, nullable)
- `temperature` (number, nullable)
- `triggerOnChannels` (string[])
- `triggerOnMessageTypes` (string[])
- `voice` (object): Voice Agent configuration. Patch this object to enable voice, change the greeting, or adjust call limits. Requires the Voice Agents feature to be enabled for your team.
  - `enabled` (boolean, required): Whether the agent handles voice calls. When false, the voice agent does not answer calls and outbound calls are rejected.
  - `greeting` (string): Opening line the agent speaks when the call connects. If omitted, the agent waits for the caller to speak first.
  - `greetings` (object): Greeting per language, keyed by language code. Used when the caller's language differs from the one `greeting` is written in.
    - `{key}` (string)
  - `language` (string): BCP-47 language code used for both speech recognition and speech synthesis (e.g. `en`, `es`, `pt-BR`). Auto-detected from the recipient when omitted.
  - `model` (string): Model that runs the conversation, co-located in the voice network for lowest latency. Independent of the model used for text messaging. Derived from the agent's text model when omitted.
  - `sttProvider` (string): Speech-recognition provider. Uses the default when omitted.
  - `sttModel` (string): Speech-recognition model. Uses the default when omitted.
  - `ttsProvider` (string): Speech-synthesis provider. Uses the default when omitted.
  - `ttsVoiceId` (string): Identifier of the synthesized voice that speaks. Choose from the voices available in the dashboard. Uses a neutral default when omitted.
  - `voiceSpeed` (number): Speech rate. 1.0 is natural. Only honoured by voices that support rate control; ignored by the others.
  - `interruptible` (boolean): Whether the caller can interrupt the agent while it is speaking (barge-in). When true, the agent stops talking as soon as the caller starts.
  - `maxCallDurationMinutes` (integer): Hard limit on call length in minutes. The call ends automatically when reached.
  - `maxIdleSeconds` (integer): How long the agent waits during silence before ending the call.
  - `recordCalls` (boolean): Whether the call audio is recorded.
  - `voicemailAction` (string): What the agent does when an answering machine or voicemail is detected on an outbound call. One of: `hangup`, `leave_message`.
  - `voicemailMessage` (string): Message spoken when `voicemailAction` is `leave_message`. Falls back to `greeting` when omitted.
  - `transferPhoneNumber` (string): E.164 phone number the agent can transfer the call to. When set, the agent is given a transfer tool it can use to hand the call to a human.

## Responses

### 200

Updated.

- `agent` (object, required): An AI agent. It answers on the addresses in `channels`.
  - `id` (string, required)
  - `name` (string, required)
  - `enabled` (boolean, required): Whether the agent is active.
  - `provider` (string, required): LLM provider for the AI agent. One of: `openai`, `anthropic`, `google`, `mistral`, `zavu`.
  - `model` (string, required): Model ID (e.g., gpt-4o-mini, claude-3-5-sonnet).
  - `systemPrompt` (string, required): System prompt for the agent.
  - `contextWindowMessages` (integer): Number of previous messages to include as context.
  - `includeContactMetadata` (boolean): Whether to include contact metadata in context.
  - `maxTokens` (integer, nullable): Maximum tokens for LLM response.
  - `temperature` (number, nullable): LLM temperature (0-2).
  - `triggerOnChannels` (string[]): Channels that trigger the agent.
  - `triggerOnMessageTypes` (string[]): Message types that trigger the agent.
  - `stats` (object)
    - `totalInvocations` (integer)
    - `totalTokensUsed` (integer)
    - `totalCost` (number): Total cost in USD.
  - `createdAt` (string<date-time>, required)
  - `updatedAt` (string<date-time>, required)
  - `voice` (object): Voice Agent configuration. When present and enabled, the agent can answer inbound phone calls and place outbound calls with Zavu's managed voice pipeline. Requires the Voice Agents feature to be enabled for your team.
    - `enabled` (boolean, required): Whether the agent handles voice calls. When false, the voice agent does not answer calls and outbound calls are rejected.
    - `greeting` (string): Opening line the agent speaks when the call connects. If omitted, the agent waits for the caller to speak first.
    - `greetings` (object): Greeting per language, keyed by language code. Used when the caller's language differs from the one `greeting` is written in.
      - `{key}` (string)
    - `language` (string): BCP-47 language code used for both speech recognition and speech synthesis (e.g. `en`, `es`, `pt-BR`). Auto-detected from the recipient when omitted.
    - `model` (string): Model that runs the conversation, co-located in the voice network for lowest latency. Independent of the model used for text messaging. Derived from the agent's text model when omitted.
    - `sttProvider` (string): Speech-recognition provider. Uses the default when omitted.
    - `sttModel` (string): Speech-recognition model. Uses the default when omitted.
    - `ttsProvider` (string): Speech-synthesis provider. Uses the default when omitted.
    - `ttsVoiceId` (string): Identifier of the synthesized voice that speaks. Choose from the voices available in the dashboard. Uses a neutral default when omitted.
    - `voiceSpeed` (number): Speech rate. 1.0 is natural. Only honoured by voices that support rate control; ignored by the others.
    - `interruptible` (boolean): Whether the caller can interrupt the agent while it is speaking (barge-in). When true, the agent stops talking as soon as the caller starts.
    - `maxCallDurationMinutes` (integer): Hard limit on call length in minutes. The call ends automatically when reached.
    - `maxIdleSeconds` (integer): How long the agent waits during silence before ending the call.
    - `recordCalls` (boolean): Whether the call audio is recorded.
    - `voicemailAction` (string): What the agent does when an answering machine or voicemail is detected on an outbound call. One of: `hangup`, `leave_message`.
    - `voicemailMessage` (string): Message spoken when `voicemailAction` is `leave_message`. Falls back to `greeting` when omitted.
    - `transferPhoneNumber` (string): E.164 phone number the agent can transfer the call to. When set, the agent is given a transfer tool it can use to hand the call to a human.
  - `channels` (object[], required): The (address, type) entries this agent answers on: every transport of the addresses it is connected to that its `triggerOnChannels` allows. Connect one with `POST /v2/agents/{agentId}/channels`.
    - `address` (string, required)
    - `type` (string, required): A transport a message travels on. One of: `sms`, `sms_oneway`, `whatsapp`, `telegram`, `email`, `instagram`, `messenger`, `voice`.
    - `active` (boolean, required)

### 400

Invalid request.

- `code` (string, required)
- `message` (string, required)
- `details` (object): Machine-readable context. Keys that mean the same thing everywhere: - `errors`: present on every `400 invalid_request` for an invalid body or query parameter, `[{path, message, ...}]`, `path` naming the field (`["to"]`, `["contacts", 2, "recipient"]`, `["limit"]`). - `recommendation`: one sentence saying what to do next. - `dashboardUrl`: the dashboard screen that fixes it. - `connect`: on `409 no_channel`, the channels this project can connect to reach the recipient, each `{type, request, note, available, dashboardUrl?}`; `request` is the exact call (`POST /v2/channels` with its body, or `POST /v2/numbers`), or null for a channel connected from the dashboard (WhatsApp, Instagram, Messenger). `available: false` says why in `note` (one-way SMS closed until business verification is approved). - `address` / `from`: the address the error is about, under the name the request used for it.
  - `errors` (object[])
    - `path` (object[], required)
    - `message` (string, required)
    - `code` (string)

### 401

Unauthorized.

- `code` (string, required)
- `message` (string, required)
- `details` (object): Machine-readable context. Keys that mean the same thing everywhere: - `errors`: present on every `400 invalid_request` for an invalid body or query parameter, `[{path, message, ...}]`, `path` naming the field (`["to"]`, `["contacts", 2, "recipient"]`, `["limit"]`). - `recommendation`: one sentence saying what to do next. - `dashboardUrl`: the dashboard screen that fixes it. - `connect`: on `409 no_channel`, the channels this project can connect to reach the recipient, each `{type, request, note, available, dashboardUrl?}`; `request` is the exact call (`POST /v2/channels` with its body, or `POST /v2/numbers`), or null for a channel connected from the dashboard (WhatsApp, Instagram, Messenger). `available: false` says why in `note` (one-way SMS closed until business verification is approved). - `address` / `from`: the address the error is about, under the name the request used for it.
  - `errors` (object[])
    - `path` (object[], required)
    - `message` (string, required)
    - `code` (string)

### 404

Agent not found, or it belongs to another project.

- `code` (string, required)
- `message` (string, required)
- `details` (object): Machine-readable context. Keys that mean the same thing everywhere: - `errors`: present on every `400 invalid_request` for an invalid body or query parameter, `[{path, message, ...}]`, `path` naming the field (`["to"]`, `["contacts", 2, "recipient"]`, `["limit"]`). - `recommendation`: one sentence saying what to do next. - `dashboardUrl`: the dashboard screen that fixes it. - `connect`: on `409 no_channel`, the channels this project can connect to reach the recipient, each `{type, request, note, available, dashboardUrl?}`; `request` is the exact call (`POST /v2/channels` with its body, or `POST /v2/numbers`), or null for a channel connected from the dashboard (WhatsApp, Instagram, Messenger). `available: false` says why in `note` (one-way SMS closed until business verification is approved). - `address` / `from`: the address the error is about, under the name the request used for it.
  - `errors` (object[])
    - `path` (object[], required)
    - `message` (string, required)
    - `code` (string)

## Example

```bash
curl -X PATCH "https://api.zavu.dev/v2/agents/agent_abc123" \
  -H "Authorization: Bearer $ZAVUDEV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "string"
}'
```

```typescript
import Zavudev from "@zavudev/sdk";

const zavu = new Zavudev({ apiKey: process.env.ZAVUDEV_API_KEY });

const result = await zavu.v2.agents.update("agent_abc123", {
  name: "string",
});

console.log(result);
```