Habilidades del agente

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.

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

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

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.

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.

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.

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

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

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

GET /api/agents/{agentId}/specialists

Respuesta: CÓDIGO_BLOQUE_22

Activar/Desactivar una regla de enrutamiento

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.

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

Agent Skills

Agent Cortex

Livia - 360 Assistant

Conversations

Access Groups

🔢 Tabla de contenidos

1. Descripción general

¿Qué son las habilidades de los agentes?

¿Por qué utilizar las habilidades?

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

2. Referencia de punto final

3. Autenticación y permisos

4. Habilidades: crear y administrar

Lista de habilidades

Crear una habilidad

Actualizar una habilidad

5. Paquetes de habilidades

Lista de paquetes disponibles

Aplicar un paquete de habilidades

6. Habilidades propuestas por la IA

Proponer habilidades desde la configuración

Proponer habilidades desde la base de conocimientos (RAG)

7. Optimización de habilidades

8. Modo Agente Cortex

Obtener modo actual

Modo de actualización

9. Agentes especialistas

Lista de especialistas

Activar/Desactivar una regla de enrutamiento

Vincular a un especialista

10. Formato de respuesta

Códigos de estado

11. Manejo de errores

12. Mejores prácticas

Escritura de habilidades efectivas

Selección del modo Cortex

Organización vs alcance del agente

13. Solución de problemas

​🔢 Tabla de contenidos

​1. Descripción general

​¿Qué son las habilidades de los agentes?

​¿Por qué utilizar las habilidades?

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

​2. Referencia de punto final

​3. Autenticación y permisos

​4. Habilidades: crear y administrar

​Lista de habilidades

​Crear una habilidad

​Actualizar una habilidad

​5. Paquetes de habilidades

​Lista de paquetes disponibles

​Aplicar un paquete de habilidades

​6. Habilidades propuestas por la IA

​Proponer habilidades desde la configuración

​Proponer habilidades desde la base de conocimientos (RAG)

​7. Optimización de habilidades

​8. Modo Agente Cortex

​Obtener modo actual

​Modo de actualización

​9. Agentes especialistas

​Lista de especialistas

​Activar/Desactivar una regla de enrutamiento

​Vincular a un especialista

​10. Formato de respuesta

​Códigos de estado

​11. Manejo de errores

​12. Mejores prácticas

​Escritura de habilidades efectivas

​Selección del modo Cortex

​Organización vs alcance del agente

​13. Solución de problemas

🔢 Tabla de contenidos

1. Descripción general

¿Qué son las habilidades de los agentes?

¿Por qué utilizar las habilidades?

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

2. Referencia de punto final

3. Autenticación y permisos

4. Habilidades: crear y administrar

Lista de habilidades

Crear una habilidad

Actualizar una habilidad

5. Paquetes de habilidades

Lista de paquetes disponibles

Aplicar un paquete de habilidades

6. Habilidades propuestas por la IA

Proponer habilidades desde la configuración

Proponer habilidades desde la base de conocimientos (RAG)

7. Optimización de habilidades

8. Modo Agente Cortex

Obtener modo actual

Modo de actualización

9. Agentes especialistas

Lista de especialistas

Activar/Desactivar una regla de enrutamiento

Vincular a un especialista

10. Formato de respuesta

Códigos de estado

11. Manejo de errores

12. Mejores prácticas

Escritura de habilidades efectivas

Selección del modo Cortex

Organización vs alcance del agente

13. Solución de problemas