# Agents: Update an agent (https://docs.envocal.ai/api-reference/agents/update-an-agent/)

> Replaces the agent's settings. Send the version you read; it changes on every update. Voice settings left null keep their current value. knowledgeBaseIds: null keeps the current links, [] removes all, a list replaces them. The tenant cannot be changed.

## PUT `/v1/tenants/{tenantId}/agents/{id}`

Replaces the agent's settings. Send the `version` you read; it changes on every update.
Voice settings left null keep their current value. `knowledgeBaseIds`: null keeps the current links,
`[]` removes all, a list replaces them. The tenant cannot be changed.

**Required permission:** `agents:write`

### Parameters

| Name | In | | Type | Description |
| --- | --- | --- | --- | --- |
| `tenantId` | path | required | string | Tenant id, or `current` for the key's own tenant. Must be the key's tenant or one of its sub-tenants. |
| `id` | path | required | string | Agent id. |

### Request body

`application/json`: AgentUpdateDto

| Field | Type | | Description |
| --- | --- | --- | --- |
| `version` | integer |  | The `version` you read. A stale version gives 409. |
| `name` | string | required | Display name. |
| `description` | string | nullable | Internal description; not given to the AI. |
| `instructions` | string | nullable | System prompt. |
| `variableDefinitionsJson` | string | nullable | Prompt variables as a JSON-encoded string (see Agent.variableDefinitionsJson). |
| `status` | `draft` \| `active` \| `archived` | nullable | Lifecycle status; null keeps the current value. |
| `model` | string | nullable | Realtime model; null keeps the current value. |
| `voice` | `alloy` \| `ash` \| `ballad` \| `coral` \| `echo` \| `sage` \| `shimmer` \| `verse` \| `marin` \| `cedar` | nullable | Voice; null keeps the current value. |
| `knowledgeBaseIds` | string[] | nullable | null keeps the current links, `[]` removes all, a list replaces them. |
| `allowFollowUpEmail` | boolean |  | Give the AI a `send_email` tool for follow-up emails. |
| `followUpEmailAddress` | string | nullable | Follow-up email recipient; required when `allowFollowUpEmail` is true. |
| `allowCallTransfer` | boolean |  | Give the AI a `transfer_call` tool on phone calls. |
| `callTransferType` | CallTransferType | nullable | How calls are transferred; null keeps the current value. |
| `isTemplate` | boolean |  | Whether the agent is a template. |
| `type` | string | nullable | Optional free-text label. |
| `allowEndCall` | boolean |  | Give the AI an `end_call` tool. |
| `turnDetectionType` | `server_vad` \| `semantic_vad` \| `none` | nullable | `server_vad`, `semantic_vad` or `none`. |
| `turnDetectionEagerness` | `auto` \| `low` \| `medium` \| `high` | nullable | `semantic_vad` only. |
| `turnDetectionThreshold` | number (double) | nullable | `server_vad` only, 0.0–1.0. |
| `turnDetectionPrefixPadding` | integer | nullable | `server_vad` only, milliseconds. |
| `turnDetectionSilenceDuration` | integer | nullable | `server_vad` only, milliseconds. |
| `turnDetectionTimeout` | boolean | nullable | `server_vad` only: speak up after user silence. |
| `turnDetectionTimeoutTime` | integer | nullable | Idle timeout in milliseconds. |
| `turnDetectionInterruptResponse` | boolean | nullable | Let the user interrupt the AI. |
| `transcriptionModel` | string | nullable | `gpt-4o-transcribe`, `gpt-4o-mini-transcribe` or `off`. |
| `transcriptionLanguage` | string | nullable | ISO 639-1 code or `auto`. |
| `transcriptionInstructions` | string | nullable | Hints for the transcriber. Replaced as given (null clears). |
| `noiseReductionType` | `none` \| `near_field` \| `far_field` | nullable | `near_field`, `far_field` or `none`. |
| `toolAssignments` | AgentToolsConfigDto | nullable | Ignored; use `PUT /v1/tenants/{tenantId}/agents/{id}/tools`. |

### Responses

**204**: Updated.

**400**: Invalid follow-up email, or knowledge bases not in the agent's tenant.

**401**: Missing, invalid, revoked or expired API key.

**403**: The key lacks the required permission, or the tenant/resource is outside its reach.

**404**: Not found.

**409**: `version` is stale: the agent was changed in the meantime. Reload and retry.

**429**: Rate limit exceeded. Retry after the number of seconds in the Retry-After header.

### Example

```bash
curl -X PUT "https://api.envocal.ai/v1/tenants/current/agents/{id}" \
  -H "Authorization: Bearer evk_eu_..." \
  -H "Content-Type: application/json" \
  -d '{"name":"string"}'
```