> ## 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.

# Agente corteza

> Agent Cortex es la capa de razonamiento autónomo de su empleado de IA: lee las habilidades activas y selecciona la más contextualmente relevante en tiempo de ejecución, lo que permite un comportamiento proactivo y adaptativo.

> **Lo que aprenderás:**
> Esta página explica qué es Agent Cortex, los tres modos operativos (`passive`, `advisory`, `active`), cómo configurar el modo para cada empleado de IA y cómo interactúa con el sistema Agent Skills.

***

## 🔢 Tabla de contenidos

1. [Overview](#1-overview)
2. [How the Cortex Works](#2-how-the-cortex-works)
3. [Cortex Modes](#3-cortex-modes)
4. [Configure the Cortex Mode](#4-configure-the-cortex-mode)
5. [Cortex + Skills Integration](#5-cortex--skills-integration)
6. [Endpoint Reference](#6-endpoint-reference)
7. [Response Format](#7-response-format)
8. [Best Practices](#8-best-practices)
9. [Troubleshooting](#9-troubleshooting)

***

## 1. Descripción general

### ¿Qué es el Agente Cortex?

**Agent Cortex** es una capa de razonamiento inteligente integrada en cada empleado de IA de ZappWay. En esencia, responde una pregunta antes de cada respuesta de la IA:

> *"Dado el contexto de conversación actual, ¿qué habilidad debería aplicar la IA en este momento?"*

Sin Cortex, su IA responde utilizando solo su base de indicaciones y conocimientos básicos. Con Cortex activo, la IA selecciona dinámicamente la **Habilidad del agente** más relevante para cada mensaje entrante e inyecta sus instrucciones en el contexto de respuesta.

### Por qué es importante

En las conversaciones del mundo real, los usuarios no siempre hacen el mismo tipo de preguntas. Una conversación de soporte puede pasar de una consulta de facturación a un problema técnico en cuestión de minutos. Cortex le permite a su IA:

* **Adaptarse automáticamente** a cambios de tema dentro de una conversación
* **Aplicar conocimientos especializados** solo cuando sea necesario
* **Reduzca la duración del mensaje** cargando habilidades específicas a pedido en lugar de poner todo en el mensaje base
* **Mejorar la precisión de la respuesta** proporcionando instrucciones enfocadas y específicas de la situación

***

## 2. Cómo funciona la corteza

```
User sends message
       ↓
Cortex reads all ACTIVE skills for this agent
       ↓
Semantic matching: Which skill is most relevant?
       ↓
┌─────────────────────────────────┐
│ passive mode → skip             │
│ advisory mode → suggest         │
│ active mode  → inject + respond │
└─────────────────────────────────┘
       ↓
AI generates response (with or without skill context)
```

### Lo que lee la corteza

La Corteza considera:

1. **El mensaje actual** del usuario
2. **Historial de conversaciones recientes** (ventana contextual)
3. **Todas las habilidades activas** para el agente (y las habilidades del ámbito de la organización)
4. **Descripciones de habilidades**: se utiliza como señal de coincidencia semántica

> El campo `description` de cada habilidad es la señal principal que utiliza Cortex para seleccionar la habilidad correcta. Escriba siempre descripciones claras y específicas.

***

## 3. Modos de corteza

Cortex tiene tres modos de funcionamiento que controlan **con qué autonomía** selecciona y aplica habilidades.

### `passive` — Corteza desactivada

Cortex no evalúa ni aplica habilidades. La IA responde utilizando únicamente su base de indicaciones y conocimientos básicos.

**Usar cuando:**

* Su IA tiene un propósito único y enfocado sin necesidad de un comportamiento dinámico
* Estás configurando el agente y aún no has creado una biblioteca de habilidades.
* Quieres un control manual total sobre el comportamiento de la IA.

**Efecto:** Las habilidades existen en el sistema pero nunca se seleccionan ni se inyectan.

***

### `advisory` — Cortex observa

Cortex evalúa las habilidades activas y **sugiere** cuál es la más relevante, pero no la inyecta automáticamente. Este modo es ideal para **probar** tu biblioteca de habilidades antes de pasar a producción.

**Usar cuando:**

* Quieres observar qué habilidades selecciona Cortex sin afectar las conversaciones en vivo.
* Estás revisando la cobertura y la calidad de las habilidades.
* Estás ganando confianza antes de activar completamente el Cortex.

**Efecto:** Cortex toma una decisión de selección de habilidades, pero la muestra solo en las herramientas de desarrollo/observabilidad, no en la respuesta de IA en vivo.

***

### `active` — Corteza activada

Cortex evalúa automáticamente las habilidades activas e **inyecta la más relevante** en el contexto de la IA antes de cada generación de respuesta.

**Usar cuando:**

* Tienes una biblioteca de habilidades bien probada con al menos 3 a 5 habilidades activas
* Tus conversaciones cubren diversos temas o requieren comportamientos específicos de cada situación.
* Quieres que la IA se adapte automáticamente sin intervención manual

**Efecto:** Cada respuesta de la IA se enriquece con la habilidad más contextualmente relevante. Si ninguna habilidad coincide bien, la IA vuelve a su indicación básica.

***

## 4. Configurar el modo Cortex

### Obtener modo actual

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

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

| Campo            | Descripción                                                                         |
| ---------------- | ----------------------------------------------------------------------------------- |
| `configuredMode` | El modo que configuró explícitamente                                                |
| `effectiveMode`  | El modo realmente vigente (puede variar durante las transiciones de implementación) |

### Establecer modo

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

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

**Valores válidos:** `"passive"`, `"advisory"`, `"active"`

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

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

***

## 5. Integración de habilidades Cortex +

Cortex funciona exclusivamente con el sistema **Agent Skills**. Para utilizar Cortex de forma eficaz:

### Paso 1: Crear habilidades

Cree al menos de 3 a 5 habilidades activas para su agente. Cada habilidad debe cubrir un escenario distinto que su IA podría encontrar.

→ Consulte [Habilidades del agente](/agent-skills) para saber cómo crear habilidades.

### Paso 2: Activar habilidades

Asegúrese de que cada habilidad tenga `status: "active"`. Cortex ignora las habilidades en estado `draft` o `archived`.

### Paso 3: escriba descripciones claras

El campo `description` es la **señal de coincidencia principal** para Cortex. Escribe descripciones que respondan claramente: "¿Cuándo debería activarse esta habilidad?"

**Buena descripción:**

> "Cuando el cliente menciona un error de facturación, un cargo inesperado, una solicitud de reembolso o una disputa de pago".

**Mala descripción:**

> "Para facturar cosas."

### Paso 4: Establezca el modo en `advisory` primero

Pruebe en modo de aviso antes de activarlo. Observe qué habilidades se seleccionan en sus análisis/registros.

### Paso 5: Promocionar a `active`

Una vez satisfecho con la cobertura de habilidades y la precisión de la selección, configure el modo en `active`.

***

## 6. Referencia de punto final

| Método  | Punto final                           | Descripción                   | Autenticación                          |
| ------- | ------------------------------------- | ----------------------------- | -------------------------------------- |
| `GET`   | `/api/agents/[id]/skills/cortex-mode` | Obtener el modo Cortex actual | `agent_skills.read` O `agents.read`    |
| `PATCH` | `/api/agents/[id]/skills/cortex-mode` | Establecer el modo Cortex     | `agent_skills.manage` O `agents.write` |

***

## 7. Formato de respuesta

### Respuesta exitosa

```json theme={null}
{
  "configuredMode": "active",
  "effectiveMode": "active"
}
```

### Respuestas de error

| Estado | Cuerpo                                             | Causa                                                    |
| ------ | -------------------------------------------------- | -------------------------------------------------------- |
| `400`  | `{ "error": "Invalid mode" }`                      | El valor del modo no es `passive`, `advisory` o `active` |
| `404`  | `{ "error": "Agent not found for organization." }` | `agentId` no pertenece a su organización                 |
| `403`  | `{ "error": "Forbidden" }`                         | Permisos insuficientes                                   |

***

## 8. Mejores prácticas

### Guía de selección de modo

| Situación                                                                        | Modo recomendado                           |
| -------------------------------------------------------------------------------- | ------------------------------------------ |
| Nuevo agente, aún sin habilidades                                                | `passive`                                  |
| Biblioteca de habilidades de construcción y prueba                               | `advisory`                                 |
| Agente de producción con 3+ habilidades activas                                  | `active`                                   |
| Agente con propósito único y enfocado (por ejemplo, bot de preguntas frecuentes) | `passive` o `active` con 1 o 2 habilidades |
| Agente que maneja diversos temas (soporte, ventas, información)                  | `active` con 5 a 15 habilidades            |

### Cobertura de habilidades para el modo activo

Para que Cortex funcione bien en el modo `active`:

* **Mínimo:** 3 habilidades activas que cubran los tipos de conversación más comunes
* **Recomendado:** 5 a 15 habilidades con descripciones distintas y que no se superpongan
* **Evitar:** Descripciones extremadamente similares (Cortex puede seleccionar de manera inconsistente)

### Pruebas con modo de asesoramiento

Utilice el modo de asesoramiento para responder:

1. ¿Cortex selecciona la habilidad adecuada para cada tipo de conversación?
2. ¿Hay temas de conversación en los que no coinciden ninguna habilidad?
3. ¿Hay descripciones de habilidades demasiado similares, lo que hace que se seleccione la habilidad incorrecta?

***

## 9. Solución de problemas

| Problema                                                     | Posible causa                                      | Solución                                                                                        |
| ------------------------------------------------------------ | -------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
| Cortex parece seleccionar siempre la misma habilidad         | Las habilidades tienen descripciones superpuestas  | Hacer que el `description` de cada habilidad sea más específico y distinto                      |
| Cortex nunca selecciona una habilidad                        | El modo es `passive`                               | Cambie el modo a `advisory` o `active`                                                          |
| `effectiveMode` difiere de `configuredMode`                  | Una transición de implementación está en progreso  | Espere brevemente y verifique nuevamente; póngase en contacto con el soporte si persiste        |
| La IA ignora las habilidades en modo activo                  | Las habilidades tienen estado `draft` o `archived` | Cambiar el estado de la habilidad a `active`                                                    |
| No hay mejoras en las respuestas después de habilitar Cortex | La habilidad `content` es demasiado genérica       | Reescriba el contenido de las habilidades con instrucciones paso a paso específicas y prácticas |