# Gestionar agentes

Lista tus agentes de voz, cambia su configuración (voz, idioma, comportamiento, extractores…) y publica los cambios, sin entrar al panel.

> 💡 La gestión por API está disponible para los agentes del **motor de voz VPower**. Si un agente todavía no pasó a VPower ([qué cambia](migrar-a-vpower.md)), estas operaciones responden `409` con `"code": "agent_not_migrated"`.

**Cómo funcionan los cambios:** igual que en la ficha del panel. Cada cambio se guarda en un **borrador**; las llamadas siguen usando la versión publicada hasta que llamas a [Publicar agente](#publicar-agente). Así puedes hacer varios cambios y probarlos antes de ponerlos en uso.

---

## Listar agentes

**GET** `/list-agents`

Devuelve los agentes de tu cuenta (y los de tus clientes, si eres partner). Los agentes del motor de voz VPower vienen con su configuración completa (la misma forma que [Obtener agente](obtener-agente.md)); los que todavía no se migraron vienen con `agent_id`, `agent_name` y `"manageable": false`.

```bash
curl --request GET \
     --url https://calls.anunzi.net/list-agents \
     --header 'Authorization: Bearer anz_live_TU_API_KEY'
```

---

## Actualizar agente

**PATCH** `/update-agent/{agent_id}`

Cambia campos de la configuración del agente. Envía solo los que quieras cambiar.

### Campos que puedes cambiar

| Campo | Tipo | Descripción |
|-------|------|-------------|
| `agent_name` | string | Nombre del agente. |
| `voice_id` | string | Voz. Usa un `voice_id` de [Listar voces](voces-y-numeros.md#listar-voces). |
| `language` | string | Idioma, por ejemplo `es-419`, `es-ES`, `en-US`. |
| `voice_speed` | number | Velocidad de la voz (0,5 a 2). |
| `voice_temperature` | number | Variación de la voz (0 a 2). |
| `volume` | number | Volumen (0 a 2). |
| `voice_emotion` | string | Emoción de la voz, si la voz la admite. |
| `responsiveness` | number | Qué tan rápido responde (0 a 1). |
| `interruption_sensitivity` | number | Qué tan fácil lo interrumpen (0 a 1). |
| `enable_backchannel` | boolean | Que diga «ajá», «claro» mientras la persona habla. |
| `backchannel_frequency` | number | Frecuencia del backchannel (0 a 1). |
| `ambient_sound` | string | Sonido de ambiente (`coffee-shop`, `call-center`, etc.) o `null`. |
| `ambient_sound_volume` | number | Volumen del ambiente. |
| `begin_message_delay_ms` | integer | Espera antes del saludo. |
| `ring_duration_ms` | integer | Cuánto suena antes de cortar en salientes. |
| `end_call_after_silence_ms` | integer | Corta tras este silencio. |
| `max_call_duration_ms` | integer | Duración máxima de la llamada. |
| `reminder_trigger_ms` | integer | Silencio antes de preguntar «¿sigues ahí?». |
| `reminder_max_count` | integer | Cuántas veces pregunta antes de cortar. |
| `allow_user_dtmf` | boolean | Que el agente reciba las teclas que marca la persona. |
| `voicemail_option` | object | Qué hacer si atiende un buzón de voz. |
| `ivr_option` | object | Qué hacer si atiende un menú automático. |
| `boosted_keywords` | array | Palabras que la transcripción debe reconocer mejor (nombres, marcas). Hasta 100. |
| `stt_mode` | string | Modo de transcripción. |
| `post_call_analysis_data` | array | Extractores: datos a sacar de cada llamada al terminar. |
| `post_call_analysis_model` | string | Modelo del análisis post-llamada. |
| `guardrail_config`, `pii_config`, `handbook_config` | object | Seguridad, datos personales y presets de comportamiento. |
| `data_storage_setting`, `data_storage_retention_days` | string / integer | Qué se guarda y por cuántos días. |

El prompt, el mensaje inicial, el modelo y las funciones se cambian con [Prompt, modelo y funciones](prompt-y-funciones.md).

### Ejemplo

```bash
curl --request PATCH \
     --url https://calls.anunzi.net/update-agent/agent_3f9c1a7b2e4d5c6f \
     --header 'Authorization: Bearer anz_live_TU_API_KEY' \
     --header 'Content-Type: application/json' \
     --data '{
  "voice_speed": 1.1,
  "enable_backchannel": true,
  "post_call_analysis_data": [
    { "type": "string", "name": "motivo", "description": "Motivo principal del llamado" }
  ]
}'
```

Responde `200` con el agente actualizado (el borrador): `version` es el número del borrador e `is_published` vale `false` hasta que lo publiques.

---

## Publicar agente

**POST** `/publish-agent/{agent_id}`

Pone en uso el borrador: desde ese momento, las llamadas nuevas usan esta versión.

```bash
curl --request POST \
     --url https://calls.anunzi.net/publish-agent/agent_3f9c1a7b2e4d5c6f \
     --header 'Authorization: Bearer anz_live_TU_API_KEY'
```

```json
{ "agent_id": "agent_3f9c1a7b2e4d5c6f", "version": 7, "is_published": true }
```

Si no hay cambios sin publicar responde `409`.

---

## Versiones del agente

**GET** `/get-agent-versions/{agent_id}`

Historial de versiones: número, si es la que está en uso (`is_published`), título y fecha de la última modificación (en milisegundos).

```json
[
  { "version": 7, "is_published": true,  "version_title": "Publicado por API", "last_modification_timestamp": 1791230400000 },
  { "version": 6, "is_published": false, "version_title": "", "last_modification_timestamp": 1791144000000 }
]
```

---

## Códigos de estado

| Código | Descripción |
|--------|-------------|
| `200` | Correcto. |
| `400` | Campo no permitido o valor inválido (la respuesta indica cuál). |
| `401` | API Key ausente o inválida. |
| `403` | El agente no pertenece a tu cuenta. |
| `409` | El agente todavía no fue migrado al motor de voz VPower, o no hay borrador para publicar. |