> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zappway.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Habilidades del agente

> Amplíe su empleado de IA con habilidades personalizadas: instrucciones reutilizables y reglas de comportamiento que dan forma a cómo el agente responde, razona y actúa en cada conversación.

> **Lo que aprenderás:**
> Esta página explica cómo funcionan las habilidades del agente, cómo crearlas y administrarlas, cómo usar los paquetes de habilidades para comenzar rápidamente y cómo usar la propuesta de habilidades asistida por IA para crear automáticamente una biblioteca de habilidades basada en conocimientos.

***

## 🔢 Tabla de contenidos

1. [Overview](#1-overview)
2. [Endpoint Reference](#2-endpoint-reference)
3. [Authentication & Permissions](#3-authentication--permissions)
4. [Skills — Create & Manage](#4-skills--create--manage)
5. [Skill Packs](#5-skill-packs)
6. [AI-Proposed Skills](#6-ai-proposed-skills)
7. [Skill Optimization](#7-skill-optimization)
8. [Agent Cortex Mode](#8-agent-cortex-mode)
9. [Agent Specialists](#9-agent-specialists)
10. [Response Format](#10-response-format)
11. [Error Handling](#11-error-handling)
12. [Best Practices](#12-best-practices)
13. [Troubleshooting](#13-troubleshooting)

***

## 1. Descripción general

### ¿Qué son las habilidades de los agentes?

Las habilidades de los agentes son **unidades de conocimiento estructuradas** que le enseñan a su empleado de IA cómo comportarse en situaciones específicas. Cada habilidad contiene:

* **Nombre**: una etiqueta clara (por ejemplo, "Manejar solicitud de reembolso")
* **Slug**: un identificador único legible por máquina (por ejemplo, `handle-refund-request`)
* **Descripción** — Cuándo debe activarse esta habilidad
* **Contenido**: las instrucciones detalladas que sigue la IA cuando se aplica esta habilidad.
* **Estado** — `draft`, `active` o `archived`
* **Alcance** — `agent` (IA única) o `organization` (compartido entre todas las IA)

### ¿Por qué utilizar las habilidades?

Sin habilidades, su empleado de IA depende únicamente de sus instrucciones básicas y su base de conocimientos. Las habilidades te permiten:

* Definir comportamientos específicos para situaciones recurrentes.
* Reutilizar el conocimiento entre múltiples empleados de IA (alcance de la organización)
* Habilite AI Cortex para seleccionar automáticamente la habilidad correcta en tiempo de ejecución
* Mantenga y versione la lógica de comportamiento de su IA independientemente de su indicación.

### Cómo se utilizan las habilidades en tiempo de ejecución

Cuando una conversación está en curso, el **Agent Cortex** (en modo `advisory` o `active`) lee todas las habilidades activas y selecciona la más relevante según el contexto. El **contenido** de la habilidad seleccionada se inyecta en la ventana contextual de la IA como una capa de instrucción adicional.

```
Incoming message
      ↓
Agent Cortex evaluates active skills
      ↓
Most relevant skill(s) selected
      ↓
Skill content injected into context
      ↓
AI generates response using skill instructions
```

***

## 2. Referencia de punto final

| Método  | Punto final                                | Descripción                                                                       | Autenticación         | Clasificación        |
| ------- | ------------------------------------------ | --------------------------------------------------------------------------------- | --------------------- | -------------------- |
| `GET`   | `/api/agents/[id]/skills`                  | Enumerar todas las habilidades de un agente (agente + alcance de la organización) | Sesión + Organización | Orientado al usuario |
| `POST`  | `/api/agents/[id]/skills`                  | Crear una nueva habilidad para un agente                                          | Sesión + Organización | Orientado al usuario |
| `PATCH` | `/api/agents/[id]/skills/[skillId]`        | Actualizar una habilidad existente                                                | Sesión + Organización | Orientado al usuario |
| `GET`   | `/api/agents/[id]/skills/packs`            | Listar los paquetes de habilidades disponibles para un agente                     | Sesión + Organización | Orientado al usuario |
| `POST`  | `/api/agents/[id]/skills/packs/apply`      | Aplicar un Skill Pack a un agente                                                 | Sesión + Organización | Orientado al usuario |
| `POST`  | `/api/agents/[id]/skills/propose`          | La IA propone habilidades basadas en la configuración del agente                  | Sesión + Organización | Orientado al usuario |
| `POST`  | `/api/agents/[id]/skills/propose-from-rag` | La IA propone habilidades a partir de una base de conocimientos conectada         | Sesión + Organización | Orientado al usuario |
| `POST`  | `/api/agents/[id]/skills/optimize`         | Generar sugerencias de aprobación de optimización                                 | Sesión + Organización | Orientado al usuario |
| `GET`   | `/api/agents/[id]/skills/cortex-mode`      | Obtener el modo actual de Agent Cortex                                            | Sesión + Organización | Orientado al usuario |
| `PATCH` | `/api/agents/[id]/skills/cortex-mode`      | Actualizar el modo Agent Cortex                                                   | Sesión + Organización | Orientado al usuario |
| `GET`   | `/api/agents/[id]/specialists`             | Listar subagentes especializados vinculados a este agente                         | Sesión + Organización | Orientado al usuario |
| `POST`  | `/api/agents/[id]/specialists`             | Activar/desactivar una regla de enrutamiento especializada                        | Sesión + Organización | Orientado al usuario |
| `PUT`   | `/api/agents/[id]/specialists`             | Vincular un nuevo especialista (subagente)                                        | Sesión + Organización | Orientado al usuario |

***

## 3. Autenticación y permisos

Todos los puntos finales requieren una **cookie de sesión** activa vinculada a un usuario autenticado que pertenece a la organización propietaria del agente.

| Permiso                                | Puntos finales                                  |
| -------------------------------------- | ----------------------------------------------- |
| `agent_skills.read` O `agents.read`    | Todos los puntos finales `GET`                  |
| `agent_skills.manage` O `agents.write` | Todos los puntos finales `POST`, `PATCH`, `PUT` |

> El sistema verifica que `agentId` pertenece a la organización actual del usuario autenticado (`assertAgentBelongsToOrganization`) antes de cualquier operación.

***

## 4. Habilidades: crear y administrar

### Lista de habilidades

Recupera todas las habilidades de un agente determinado, incluidas las habilidades **con alcance del agente** y **con alcance de la organización**, además de cualquier **aprobación de acción** pendiente relacionada con las habilidades.

**Solicitud:**
***CÓDIGO\_BLOQUE\_1***

**Respuesta:**
***CÓDIGO\_BLOQUE\_2***

### Crear una habilidad

**Solicitud:**
***CÓDIGO\_BLOQUE\_3***

**Cuerpo de la solicitud:**

| Campo         | Tipo                                | Requerido | Descripción                                                                       |
| ------------- | ----------------------------------- | --------- | --------------------------------------------------------------------------------- |
| `name`        | `string`                            | ✅         | Nombre para mostrar de la habilidad                                               |
| `content`     | `string`                            | ✅         | El contenido de las instrucciones que sigue la IA                                 |
| `slug`        | `string`                            | ❌         | ID legible por máquina (generado automáticamente a partir del nombre si se omite) |
| `description` | `string \| null`                    | ❌         | Cuándo debería activarse esta habilidad                                           |
| `status`      | `"draft" \| "active" \| "archived"` | ❌         | Predeterminado: `"draft"`                                                         |
| `pinned`      | `boolean`                           | ❌         | Fijar al principio de la lista de habilidades. Predeterminado: `false`            |
| `scope`       | `"agent" \| "organization"`         | ❌         | Predeterminado: `"agent"`                                                         |
| `metadata`    | `object`                            | ❌         | Metadatos JSON arbitrarios                                                        |

**Ejemplo:**
***CÓDIGO\_BLOQUE\_4***

**rizo:**
***CÓDIGO\_BLOQUE\_5***

**Mecanografiado:**
***CÓDIGO\_BLOQUE\_6***

### Actualizar una habilidad

**Solicitud:**
***CÓDIGO\_BLOQUE\_7***

Todos los campos del esquema de creación son opcionales. Sólo se actualizarán los campos proporcionados.

**Ciclo de vida del estado:**

| Estado     | Significado                                                          |
| ---------- | -------------------------------------------------------------------- |
| `draft`    | La habilidad existe pero Cortex NO la utiliza en tiempo de ejecución |
| `active`   | La habilidad está activa y Cortex puede seleccionarla                |
| `archived` | La habilidad está deshabilitada y oculta de la selección activa      |

> Establecer el estado en `active` o `archived` actualiza automáticamente `lastReviewedAt`.

**Conflicto de Slug:** Si se proporciona un nuevo `slug` que ya existe en la organización, la API devuelve `409 Conflict`.

***

## 5. Paquetes de habilidades

Los paquetes de habilidades son **colecciones de habilidades prediseñadas** seleccionadas por ZappWay para casos de uso comunes. Te permiten iniciar una biblioteca de habilidades en segundos.

### Lista de paquetes disponibles

```bash theme={null}
GET /api/agents/{agentId}/skills/packs
```

Devuelve paquetes adaptados a la configuración regional y de habilidades actual del agente.

**Respuesta:**
***CÓDIGO\_BLOQUE\_9***

### Aplicar un paquete de habilidades

```bash theme={null}
POST /api/agents/{agentId}/skills/packs/apply
Content-Type: application/json
```

**Cuerpo de la solicitud:**

| Campo     | Tipo                        | Requerido | Descripción                                                                         |
| --------- | --------------------------- | --------- | ----------------------------------------------------------------------------------- |
| `packId`  | `string`                    | ✅         | ID del pack a aplicar                                                               |
| `scope`   | `"agent" \| "organization"` | ✅         | Si las habilidades se crean para este agente o se comparten en toda la organización |
| `channel` | `ConversationChannel`       | ❌         | Opcionalmente, filtre habilidades a un canal específico                             |

**Ejemplo:**
***CÓDIGO\_BLOQUE\_11***

***

## 6. Habilidades propuestas por la IA

ZappWay puede usar IA para **generar automáticamente sugerencias de habilidades** según la configuración o la base de conocimientos de su agente.

### Proponer habilidades desde la configuración

Analiza las instrucciones del agente y las herramientas existentes para sugerir nuevas habilidades.

```bash theme={null}
POST /api/agents/{agentId}/skills/propose
```

Devuelve una serie de objetos `ActionApproval`: habilidades sugeridas en espera de su revisión y aceptación.

### Proponer habilidades desde la base de conocimientos (RAG)

Analiza los almacenes de datos y las fuentes de datos conectados del agente para extraer temas recurrentes y crear sugerencias de habilidades.

```bash theme={null}
POST /api/agents/{agentId}/skills/propose-from-rag
```

**Respuesta:**
***CÓDIGO\_BLOQUE\_14***

> Las propuestas que coinciden estrechamente con las habilidades existentes se omiten automáticamente (`skipped` recuento).

***

## 7. Optimización de habilidades

Solicite sugerencias de optimización generadas por IA para las habilidades existentes para mejorar su efectividad.

```bash theme={null}
POST /api/agents/{agentId}/skills/optimize
```

Devuelve una lista de `ActionApproval` objetos con mejoras sugeridas para las habilidades existentes. Estos se revisan a través del sistema de Aprobaciones antes de ser aplicados.

**Respuesta:**
***CÓDIGO\_BLOQUE\_16***

***

## 8. Modo Agente Cortex

El **Agent Cortex** controla cómo la IA selecciona y aplica habilidades de forma autónoma en tiempo de ejecución.

### Obtener modo actual

```bash theme={null}
GET /api/agents/{agentId}/skills/cortex-mode
```

**Respuesta:**
***CÓDIGO\_BLOQUE\_18***

| Campo            | Descripción                                                                             |
| ---------------- | --------------------------------------------------------------------------------------- |
| `configuredMode` | El modo establecido explícitamente por el usuario                                       |
| `effectiveMode`  | El modo realmente vigente (puede diferir si se aplican restricciones de implementación) |

### Modo de actualización

```bash theme={null}
PATCH /api/agents/{agentId}/skills/cortex-mode
Content-Type: application/json
```

**Cuerpo de la solicitud:**
***CÓDIGO\_BLOQUE\_20***

| Modo       | Comportamiento                                                                               |
| ---------- | -------------------------------------------------------------------------------------------- |
| `passive`  | La corteza está deshabilitada. Las habilidades no se seleccionan automáticamente.            |
| `advisory` | Cortex sugiere la habilidad más relevante pero no la inyecta automáticamente.                |
| `active`   | Cortex selecciona e inyecta automáticamente la habilidad más relevante en cada conversación. |

***

## 9. Agentes especialistas

Los especialistas permiten que un agente **delegue conversaciones** a otros agentes especializados según las reglas de enrutamiento.

### Lista de especialistas

```bash theme={null}
GET /api/agents/{agentId}/specialists
```

**Respuesta:**
***CÓDIGO\_BLOQUE\_22***

### Activar/Desactivar una regla de enrutamiento

```bash theme={null}
POST /api/agents/{agentId}/specialists
Content-Type: application/json
```

**Cuerpo de la solicitud:**

| Campo           | Tipo                                     | Requerido | Descripción                                           |
| --------------- | ---------------------------------------- | --------- | ----------------------------------------------------- |
| `toolId`        | `string`                                 | ✅         | La herramienta que representa el enlace especializado |
| `targetAgentId` | `string`                                 | ✅         | DNI del agente especialista                           |
| `action`        | `"activate" \| "deactivate" \| "ignore"` | ✅         | Qué hacer con la regla de enrutamiento                |
| `approvalId`    | `string`                                 | ❌         | Si resuelve una regla de enrutamiento sugerida por IA |
| `reason`        | `string`                                 | ❌         | Por qué debería activarse este especialista           |
| `confidence`    | `number`                                 | ❌         | Puntuación de confianza (0–1)                         |

### Vincular a un especialista

Crea un **nuevo enlace de especialista** entre dos agentes. El sistema evita los bucles automáticos y las cadenas de delegación circulares.

```bash theme={null}
PUT /api/agents/{agentId}/specialists
Content-Type: application/json
```

**Cuerpo de la solicitud:**
***CÓDIGO\_BLOQUE\_25***

> **Detección de ciclos:** El sistema bloquea los ciclos de delegación en la profundidad 1 (por ejemplo, A→B cuando B→A ya existe). Devuelve `400 Conflict` con `reasonCode: "CYCLE_BLOCKED"`.

***

## 10. Formato de respuesta

### Códigos de estado

| Estado | Significado                                                                                   |
| ------ | --------------------------------------------------------------------------------------------- |
| `200`  | Solicitud exitosa                                                                             |
| `201`  | Recurso creado                                                                                |
| `400`  | Cuerpo de solicitud no válido o infracción de regla comercial (por ejemplo, bucle automático) |
| `401`  | No autenticado                                                                                |
| `403`  | Permisos insuficientes                                                                        |
| `404`  | Agente o habilidad no encontrada en su organización                                           |
| `409`  | Conflicto de babosas: ya existe una habilidad con esa babosa                                  |
| `500`  | Error interno del servidor                                                                    |

***

## 11. Manejo de errores

| Error                                | Causa                                                           | Cómo solucionarlo                                                          |
| ------------------------------------ | --------------------------------------------------------------- | -------------------------------------------------------------------------- |
| `Agent not found for organization`   | `agentId` no pertenece a su organización actual                 | Verifique el ID del agente y su organización activa                        |
| `Skill not found`                    | `skillId` no existe o no es accesible                           | Confirme que el ID de habilidad pertenece al agente u organización         |
| `Skill slug already exists`          | La nueva babosa ya está tomada                                  | Utilice un slug diferente o deje que el sistema genere uno automáticamente |
| `An agent cannot delegate to itself` | Intentaste vincular a un agente consigo mismo como especialista | Utilice un `targetAgentId` diferente                                       |
| `Delegation cycle detected`          | Delegación circular (A→B, B→A)                                  | Revisar enlaces de especialistas para eliminar dependencias circulares     |

***

## 12. Mejores prácticas

### Escritura de habilidades efectivas

✅ **Hacer:**

* Mantenga cada habilidad enfocada en **una situación o comportamiento específico**
* Utilice el campo `description` para explicar exactamente **cuándo** debe activarse la habilidad.
* Escriba `content` como instrucciones prácticas paso a paso
* Comience con el estado `draft` durante la prueba, luego ascienda a `active`
* Utilice el alcance `organization` para habilidades compartidas entre varios empleados de IA

❌ **Evitar:**

* Habilidades con nombres vagos como "Ayuda general": sea específico
* Reunir demasiados comportamientos en una sola habilidad.
* Dejar todas las habilidades en estado `draft` (no serán utilizadas por Cortex)
* Crear habilidades duplicadas con diferentes nombres pero el mismo comportamiento

### Selección del modo Cortex

| Modo       | Mejor para                                                                           |
| ---------- | ------------------------------------------------------------------------------------ |
| `passive`  | Agentes simples con un único propósito enfocado                                      |
| `advisory` | Modo de prueba: vea qué habilidades selecciona Cortex sin aplicarlas automáticamente |
| `active`   | Agentes de producción con ricas bibliotecas de habilidades                           |

### Organización vs alcance del agente

| Alcance        | Usar cuando                                                                                                                                       |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `agent`        | La habilidad es muy específica de la persona o caso de uso de una IA                                                                              |
| `organization` | La habilidad representa la política o el proceso general de la empresa que todas las IA deben seguir (por ejemplo, "Cumplir siempre con la LGPD") |

***

## 13. Solución de problemas

| Problema                                                     | Posible causa                                                             | Solución                                                                       |
| ------------------------------------------------------------ | ------------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
| Habilidades que no se aplican en las conversaciones          | Cortex está en modo `passive`                                             | Establezca Cortex en `advisory` o `active`                                     |
| Las habilidades existen pero Cortex selecciona la incorrecta | Las habilidades son demasiado genéricas o las descripciones se superponen | Refinar los campos `description` para que sean más específicos                 |
| Habilidad creada pero no visible                             | La habilidad se creó con el estado `draft`                                | Cambiar estado a `active`                                                      |
| Proponer-de-RAG devuelve 0 sugerencias                       | No hay almacenes de datos conectados al agente                            | Conecte al menos un almacén de datos con contenido indexado                    |
| Delegación de especialistas sin enrutamiento                 | La regla de enrutamiento está inactiva                                    | Utilice `POST /specialists` con `action: "activate"`                           |
| `409 Conflict` sobre la creación de habilidades              | Slug ya existe en la organización                                         | Omita el campo `slug` para generar automáticamente o proporcione un slug único |