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

# Agent Skills

> Amplie seu Funcionário IA com skills personalizadas — instruções reutilizáveis e regras comportamentais que moldam como o agente responde, raciocina e age em cada conversa.

> **O que você vai aprender:**
> Esta página explica como funcionam as Agent Skills, como criar e gerenciá-las, como usar Skill Packs para começar rapidamente, e como usar a proposta assistida por IA para construir uma biblioteca de skills automaticamente.

***

## 🔢 Sumário

1. [Visão Geral](#1-visao-geral)
2. [Referência de Endpoints](#2-referencia-de-endpoints)
3. [Autenticação e Permissões](#3-autenticacao-e-permissoes)
4. [Skills — Criar e Gerenciar](#4-skills--criar-e-gerenciar)
5. [Skill Packs](#5-skill-packs)
6. [Skills Propostas por IA](#6-skills-propostas-por-ia)
7. [Otimização de Skills](#7-otimizacao-de-skills)
8. [Agent Cortex Mode](#8-agent-cortex-mode)
9. [Agent Specialists](#9-agent-specialists)
10. [Formato de Resposta](#10-formato-de-resposta)
11. [Tratamento de Erros](#11-tratamento-de-erros)
12. [Boas Práticas](#12-boas-praticas)
13. [Troubleshooting](#13-troubleshooting)

***

## 1. Visão Geral

### O que são Agent Skills?

As Agent Skills são **unidades de conhecimento estruturado** que ensinam ao seu Funcionário IA como se comportar em situações específicas. Cada skill contém:

* **Nome** — Um rótulo claro (ex: "Lidar com Pedido de Reembolso")
* **Slug** — Um identificador único legível por máquina (ex: `lidar-com-reembolso`)
* **Descrição** — Quando essa skill deve ser ativada
* **Conteúdo** — As instruções detalhadas que a IA segue quando a skill é aplicada
* **Status** — `draft`, `active` ou `archived`
* **Escopo** — `agent` (um único IA) ou `organization` (compartilhado entre todos os IAs)

### Por que usar Skills?

Sem skills, seu Funcionário IA depende apenas de suas instruções base e da base de conhecimento. As skills permitem que você:

* Defina comportamentos específicos para situações recorrentes
* Reutilize conhecimento entre múltiplos Funcionários IA (escopo de organização)
* Permita que o Agent Cortex selecione automaticamente a skill certa em tempo de execução
* Mantenha e versione a lógica comportamental do seu IA de forma independente do prompt

### Como as Skills são Usadas em Tempo de Execução

Quando uma conversa está em andamento, o **Agent Cortex** (nos modos `advisory` ou `active`) lê todas as skills ativas e seleciona a mais relevante com base no contexto. O **conteúdo** da skill selecionada é injetado na janela de contexto da IA como uma camada adicional de instrução.

```
Mensagem recebida
      ↓
Agent Cortex avalia skills ativas
      ↓
Skill(s) mais relevante(s) selecionada(s)
      ↓
Conteúdo da skill injetado no contexto
      ↓
IA gera resposta usando as instruções da skill
```

***

## 2. Referência de Endpoints

| Método  | Endpoint                                   | Descrição                                                | Auth         | Classificação      |
| ------- | ------------------------------------------ | -------------------------------------------------------- | ------------ | ------------------ |
| `GET`   | `/api/agents/[id]/skills`                  | Lista todas as skills de um agente (escopo agente + org) | Sessão + Org | Voltada ao usuário |
| `POST`  | `/api/agents/[id]/skills`                  | Cria uma nova skill para um agente                       | Sessão + Org | Voltada ao usuário |
| `PATCH` | `/api/agents/[id]/skills/[skillId]`        | Atualiza uma skill existente                             | Sessão + Org | Voltada ao usuário |
| `GET`   | `/api/agents/[id]/skills/packs`            | Lista Skill Packs disponíveis para o agente              | Sessão + Org | Voltada ao usuário |
| `POST`  | `/api/agents/[id]/skills/packs/apply`      | Aplica um Skill Pack ao agente                           | Sessão + Org | Voltada ao usuário |
| `POST`  | `/api/agents/[id]/skills/propose`          | Propõe skills com IA baseadas na configuração do agente  | Sessão + Org | Voltada ao usuário |
| `POST`  | `/api/agents/[id]/skills/propose-from-rag` | Propõe skills com IA a partir da base de conhecimento    | Sessão + Org | Voltada ao usuário |
| `POST`  | `/api/agents/[id]/skills/optimize`         | Gera sugestões de otimização de skills                   | Sessão + Org | Voltada ao usuário |
| `GET`   | `/api/agents/[id]/skills/cortex-mode`      | Obtém o modo atual do Agent Cortex                       | Sessão + Org | Voltada ao usuário |
| `PATCH` | `/api/agents/[id]/skills/cortex-mode`      | Atualiza o modo do Agent Cortex                          | Sessão + Org | Voltada ao usuário |
| `GET`   | `/api/agents/[id]/specialists`             | Lista agentes especialistas vinculados                   | Sessão + Org | Voltada ao usuário |
| `POST`  | `/api/agents/[id]/specialists`             | Ativa/desativa uma regra de roteamento de especialista   | Sessão + Org | Voltada ao usuário |
| `PUT`   | `/api/agents/[id]/specialists`             | Vincula um novo especialista (sub-agente)                | Sessão + Org | Voltada ao usuário |

***

## 3. Autenticação e Permissões

Todos os endpoints exigem um **cookie de sessão** ativo vinculado a um usuário autenticado que pertença à organização proprietária do agente.

| Permissão                               | Endpoints                                 |
| --------------------------------------- | ----------------------------------------- |
| `agent_skills.read` OU `agents.read`    | Todos os endpoints `GET`                  |
| `agent_skills.manage` OU `agents.write` | Todos os endpoints `POST`, `PATCH`, `PUT` |

> O sistema verifica que o `agentId` pertence à organização atual do usuário autenticado antes de qualquer operação.

***

## 4. Skills — Criar e Gerenciar

### Listar Skills

Retorna todas as skills de um agente, incluindo as de **escopo agente** e **escopo organização**, além das **aprovações pendentes** relacionadas a skills.

**Requisição:**

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

**Resposta:**

```json theme={null}
{
  "skills": [
    {
      "id": "skill_abc123",
      "organizationId": "org_xyz",
      "agentId": "agent_123",
      "slug": "lidar-com-reembolso",
      "name": "Lidar com Pedido de Reembolso",
      "description": "Ativada quando um cliente solicita reembolso ou menciona problemas de cobrança.",
      "content": "Ao lidar com pedido de reembolso:\n1. Reconheça a frustração do cliente\n2. Solicite o número do pedido\n3. Verifique elegibilidade conforme a política de reembolso\n4. Processe ou escale conforme necessário",
      "status": "active",
      "pinned": false,
      "origin": "manual",
      "scope": "agent",
      "metadata": null,
      "createdAt": "2025-01-15T10:00:00.000Z",
      "updatedAt": "2025-01-15T10:00:00.000Z",
      "lastReviewedAt": "2025-01-15T10:00:00.000Z"
    }
  ],
  "approvals": []
}
```

### Criar uma Skill

**Requisição:**

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

**Corpo da Requisição:**

| Campo         | Tipo                                | Obrigatório | Descrição                                                        |
| ------------- | ----------------------------------- | ----------- | ---------------------------------------------------------------- |
| `name`        | `string`                            | ✅           | Nome de exibição da skill                                        |
| `content`     | `string`                            | ✅           | O conteúdo de instruções que a IA segue                          |
| `slug`        | `string`                            | ❌           | ID legível por máquina (auto-gerado a partir do nome se omitido) |
| `description` | `string \| null`                    | ❌           | Quando esta skill deve ser ativada                               |
| `status`      | `"draft" \| "active" \| "archived"` | ❌           | Padrão: `"draft"`                                                |
| `pinned`      | `boolean`                           | ❌           | Fixar no topo da lista. Padrão: `false`                          |
| `scope`       | `"agent" \| "organization"`         | ❌           | Padrão: `"agent"`                                                |
| `metadata`    | `object`                            | ❌           | Metadados JSON arbitrários                                       |

**Exemplo:**

```json theme={null}
{
  "name": "Lidar com Pedido de Reembolso",
  "description": "Quando um cliente menciona cobrança, reembolso ou contestação de pagamento.",
  "content": "Ao lidar com pedido de reembolso:\n1. Reconheça o problema com empatia\n2. Solicite o número do pedido ou nota fiscal\n3. Verifique a data da compra (reembolsos aceitos em até 30 dias)\n4. Se elegível: confirme o início do reembolso e prazo (3-5 dias úteis)\n5. Se não elegível: explique a política claramente e ofereça alternativas",
  "status": "active",
  "scope": "agent"
}
```

**cURL:**

```bash theme={null}
curl -X POST "https://seu-dominio.com/api/agents/agent_123/skills" \
  -H "Content-Type: application/json" \
  -H "Cookie: next-auth.session-token=SEU_TOKEN_DE_SESSAO" \
  -d '{
    "name": "Lidar com Pedido de Reembolso",
    "content": "Quando um reembolso é solicitado, reconheça com empatia e verifique a elegibilidade.",
    "status": "active"
  }'
```

**TypeScript:**

```ts theme={null}
const response = await fetch(`/api/agents/${agentId}/skills`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    name: 'Lidar com Pedido de Reembolso',
    content: 'Quando um reembolso é solicitado, reconheça com empatia e verifique a elegibilidade.',
    status: 'active',
  }),
});

const skill = await response.json();
```

### Atualizar uma Skill

**Requisição:**

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

Todos os campos do schema de criação são opcionais. Apenas os campos fornecidos serão atualizados.

**Ciclo de Vida do Status:**

| Status     | Significado                                                   |
| ---------- | ------------------------------------------------------------- |
| `draft`    | Skill existe mas NÃO é usada pelo Cortex em tempo de execução |
| `active`   | Skill está ativa e o Cortex pode selecioná-la                 |
| `archived` | Skill está desativada e oculta da seleção ativa               |

> Definir o status como `active` ou `archived` atualiza automaticamente `lastReviewedAt`.

***

## 5. Skill Packs

Os Skill Packs são **coleções pré-construídas de skills** criadas pela ZappWay para casos de uso comuns. Eles permitem que você inicialize uma biblioteca de skills em segundos.

### Listar Packs Disponíveis

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

Retorna packs adaptados ao locale do agente e à configuração atual de skills.

**Resposta:**

```json theme={null}
{
  "packs": [
    {
      "id": "pack_customer_support",
      "name": "Suporte ao Cliente Essencial",
      "description": "Skills fundamentais para lidar com consultas de suporte, escalonamentos e problemas comuns.",
      "skills": [
        { "name": "Escalar para Humano", "description": "Quando escalar para um atendente humano" },
        { "name": "Reconhecer Frustração", "description": "Desescalonamento empático" },
        { "name": "Solicitar Mais Informações", "description": "Quando a IA precisa de mais contexto" }
      ]
    }
  ]
}
```

### Aplicar um Skill Pack

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

**Corpo da Requisição:**

| Campo     | Tipo                        | Obrigatório | Descrição                                             |
| --------- | --------------------------- | ----------- | ----------------------------------------------------- |
| `packId`  | `string`                    | ✅           | ID do pack a ser aplicado                             |
| `scope`   | `"agent" \| "organization"` | ✅           | Skills criadas para este agente ou compartilhadas org |
| `channel` | `ConversationChannel`       | ❌           | Opcionalmente filtrar skills para um canal específico |

***

## 6. Skills Propostas por IA

O ZappWay pode usar IA para **gerar automaticamente sugestões de skills** com base na configuração do agente ou base de conhecimento.

### Propor Skills a partir da Configuração

Analisa as instruções do agente e ferramentas existentes para sugerir novas skills.

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

### Propor Skills a partir da Base de Conhecimento (RAG)

Analisa os datastores e datasources conectados ao agente para extrair tópicos recorrentes e criar sugestões de skills.

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

**Resposta:**

```json theme={null}
{
  "createdCount": 3,
  "approvals": [
    {
      "id": "approval_abc",
      "actionType": "agent_skill.create",
      "payload": {
        "name": "Lidar com Devoluções de Produtos",
        "content": "Quando o cliente pergunta sobre devolução de produtos..."
      }
    }
  ],
  "skipped": 1
}
```

> Propostas que se assemelham muito a skills existentes são automaticamente ignoradas (contagem `skipped`).

***

## 7. Otimização de Skills

Solicite sugestões de otimização geradas por IA para skills existentes a fim de melhorar sua efetividade.

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

Retorna uma lista de objetos `ActionApproval` com melhorias sugeridas para skills existentes. Elas são revisadas via sistema de Aprovações antes de serem aplicadas.

***

## 8. Agent Cortex Mode

O **Agent Cortex** controla como a IA seleciona e aplica skills autonomamente em tempo de execução.

### Obter Modo Atual

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

**Resposta:**

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

### Atualizar Modo

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

```json theme={null}
{
  "mode": "active"
}
```

| Modo       | Comportamento                                                                      |
| ---------- | ---------------------------------------------------------------------------------- |
| `passive`  | Cortex desativado. Skills não são selecionadas automaticamente.                    |
| `advisory` | Cortex sugere a skill mais relevante mas não injeta automaticamente.               |
| `active`   | Cortex seleciona e injeta automaticamente a skill mais relevante em cada conversa. |

***

## 9. Agent Specialists

Os Specialists permitem que um agente **delegue conversas** para outros agentes especializados com base em regras de roteamento.

### Vincular um Especialista

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

**Corpo da Requisição:**

```json theme={null}
{
  "targetAgentId": "agent_specialist_456",
  "name": "Especialista em Vendas Enterprise",
  "description": "Lida com precificação e contratos para clientes enterprise"
}
```

> **Detecção de Ciclo:** O sistema bloqueia delegações circulares (A→B quando B→A já existe). Retorna `400` com `reasonCode: "CYCLE_BLOCKED"`.

***

## 10. Formato de Resposta

### Status Codes

| Status | Significado                                          |
| ------ | ---------------------------------------------------- |
| `200`  | Requisição bem-sucedida                              |
| `201`  | Recurso criado                                       |
| `400`  | Corpo inválido ou violação de regra de negócio       |
| `401`  | Não autenticado                                      |
| `403`  | Permissões insuficientes                             |
| `404`  | Agente ou skill não encontrado na sua organização    |
| `409`  | Conflito de slug — já existe uma skill com esse slug |
| `500`  | Erro interno do servidor                             |

***

## 11. Tratamento de Erros

| Erro                                 | Causa                                                  | Como Resolver                                                             |
| ------------------------------------ | ------------------------------------------------------ | ------------------------------------------------------------------------- |
| `Agent not found for organization`   | `agentId` não pertence à sua organização atual         | Verifique o ID do agente e sua organização ativa                          |
| `Skill not found`                    | `skillId` não existe ou não é acessível                | Confirme que o ID da skill pertence ao agente ou org                      |
| `Skill slug already exists`          | O novo slug já está em uso                             | Use um slug diferente ou deixe o sistema gerar automaticamente            |
| `An agent cannot delegate to itself` | Tentou vincular um agente a si mesmo como especialista | Use um `targetAgentId` diferente                                          |
| `Delegation cycle detected`          | Delegação circular (A→B, B→A)                          | Revise os vínculos de especialistas para eliminar dependências circulares |

***

## 12. Boas Práticas

### Escrevendo Skills Efetivas

✅ **Faça:**

* Mantenha cada skill focada em **uma situação ou comportamento específico**
* Use o campo `description` para explicar exatamente **quando** a skill deve ser ativada
* Escreva `content` como instruções passo a passo acionáveis
* Comece com o status `draft` durante testes, depois promova para `active`
* Use escopo `organization` para skills compartilhadas entre múltiplos Funcionários IA

❌ **Evite:**

* Skills com nomes vagos como "Ajuda Geral" — seja específico
* Colocar muitos comportamentos em uma única skill
* Deixar todas as skills com status `draft` (elas não serão usadas pelo Cortex)
* Criar skills duplicadas com nomes diferentes mas o mesmo comportamento

### Seleção do Modo Cortex

| Modo       | Melhor Para                                                                      |
| ---------- | -------------------------------------------------------------------------------- |
| `passive`  | Agentes simples com um único propósito focado                                    |
| `advisory` | Modo de teste — veja quais skills o Cortex seleciona sem aplicar automaticamente |
| `active`   | Agentes em produção com bibliotecas de skills ricas                              |

***

## 13. Troubleshooting

| Problema                                       | Causa Possível                                    | Solução                                                                   |
| ---------------------------------------------- | ------------------------------------------------- | ------------------------------------------------------------------------- |
| Skills não estão sendo aplicadas nas conversas | Cortex está no modo `passive`                     | Defina o Cortex para `advisory` ou `active`                               |
| Cortex seleciona a skill errada                | Skills muito genéricas ou descrições se sobrepõem | Refine os campos `description` para ser mais específico                   |
| Skill criada mas não visível                   | Skill foi criada com status `draft`               | Mude o status para `active`                                               |
| Proposta via RAG retorna 0 sugestões           | Nenhum datastore conectado ao agente              | Conecte pelo menos um datastore com conteúdo indexado                     |
| Delegação de especialista não está roteando    | Regra de roteamento está inativa                  | Use `POST /specialists` com `action: "activate"`                          |
| `409 Conflict` ao criar skill                  | Slug já existe na organização                     | Omita o campo `slug` para gerar automaticamente, ou forneça um slug único |