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

> O Agent Cortex é a camada de raciocínio autônomo do seu Funcionário IA — ele lê as skills ativas e seleciona a mais contextualmente relevante em tempo de execução, permitindo comportamento proativo e adaptativo.

> **O que você vai aprender:**
> Esta página explica o que é o Agent Cortex, os três modos de operação (`passive`, `advisory`, `active`), como configurar o modo para cada Funcionário IA e como ele interage com o sistema de Agent Skills.

***

## 🔢 Sumário

1. [Visão Geral](#1-visao-geral)
2. [Como o Cortex Funciona](#2-como-o-cortex-funciona)
3. [Modos do Cortex](#3-modos-do-cortex)
4. [Configurar o Modo do Cortex](#4-configurar-o-modo-do-cortex)
5. [Cortex + Integração com Skills](#5-cortex--integracao-com-skills)
6. [Referência de Endpoints](#6-referencia-de-endpoints)
7. [Formato de Resposta](#7-formato-de-resposta)
8. [Boas Práticas](#8-boas-praticas)
9. [Troubleshooting](#9-troubleshooting)

***

## 1. Visão Geral

### O que é o Agent Cortex?

O **Agent Cortex** é uma camada de raciocínio inteligente embutida em cada Funcionário IA do ZappWay. Em sua essência, ele responde uma pergunta antes de cada resposta da IA:

> *"Dado o contexto atual da conversa, qual skill a IA deve aplicar agora?"*

Sem o Cortex, seu IA responde usando apenas seu prompt base e base de conhecimento. Com o Cortex ativo, a IA seleciona dinamicamente a **Agent Skill** mais relevante para cada mensagem recebida e injeta suas instruções no contexto de resposta.

### Por que é Importante

Em conversas do mundo real, os usuários nem sempre fazem o mesmo tipo de pergunta. Uma conversa de suporte pode mudar de uma dúvida de cobrança para um problema técnico em minutos. O Cortex permite que seu IA:

* **Adapte-se automaticamente** a mudanças de tópico dentro de uma conversa
* **Aplique conhecimento especializado** apenas quando necessário
* **Reduza o tamanho do prompt** carregando skills específicas sob demanda
* **Melhore a precisão das respostas** fornecendo instruções focadas e específicas para a situação

***

## 2. Como o Cortex Funciona

```
Usuário envia mensagem
       ↓
Cortex lê todas as skills ATIVAS do agente
       ↓
Correspondência semântica: Qual skill é mais relevante?
       ↓
┌─────────────────────────────────────────┐
│ modo passive → ignora                   │
│ modo advisory → sugere                  │
│ modo active  → injeta + responde        │
└─────────────────────────────────────────┘
       ↓
IA gera resposta (com ou sem contexto de skill)
```

### O que o Cortex Analisa

O Cortex considera:

1. **A mensagem atual** do usuário
2. **Histórico recente da conversa** (janela de contexto)
3. **Todas as skills ativas** para o agente (e skills de escopo organização)
4. **Descrições das skills** — usadas como sinal de correspondência semântica

> O campo `description` de cada skill é o principal sinal que o Cortex usa para selecionar a skill certa. Sempre escreva descrições claras e específicas.

***

## 3. Modos do Cortex

O Cortex possui três modos de operação que controlam **o quão autonomamente** ele seleciona e aplica skills.

### `passive` — Cortex Desligado

O Cortex não avalia nem aplica skills. A IA responde usando apenas seu prompt base e base de conhecimento.

**Use quando:**

* Seu IA tem um único propósito focado sem necessidade de comportamento dinâmico
* Você está configurando o agente e ainda não construiu uma biblioteca de skills
* Você quer controle manual total sobre o comportamento da IA

**Efeito:** Skills existem no sistema mas nunca são selecionadas ou injetadas.

***

### `advisory` — Cortex Observa

O Cortex avalia skills ativas e **sugere** qual é a mais relevante, mas não a injeta automaticamente. Este modo é ideal para **testar** sua biblioteca de skills antes de ir para produção.

**Use quando:**

* Você quer observar quais skills o Cortex seleciona sem afetar conversas ao vivo
* Você está revisando cobertura e qualidade das skills
* Você está ganhando confiança antes de ativar o Cortex completamente

***

### `active` — Cortex Ligado

O Cortex avalia automaticamente as skills ativas e **injeta a mais relevante** no contexto da IA antes de cada geração de resposta.

**Use quando:**

* Você tem uma biblioteca de skills bem testada com pelo menos 3–5 skills ativas
* Suas conversas cobrem tópicos diversos ou requerem comportamentos específicos por situação
* Você quer que a IA se adapte automaticamente sem intervenção manual

**Efeito:** Cada resposta da IA é enriquecida com a skill mais contextualmente relevante. Se nenhuma skill corresponder bem, a IA usa seu prompt base.

***

## 4. Configurar o Modo do Cortex

### Obter Modo Atual

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

**Resposta:**

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

| Campo            | Descrição                                 |
| ---------------- | ----------------------------------------- |
| `configuredMode` | O modo que você configurou explicitamente |
| `effectiveMode`  | O modo realmente em vigor                 |

### Definir Modo

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

**Corpo da Requisição:**

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

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

**cURL:**

```bash theme={null}
curl -X PATCH "https://seu-dominio.com/api/agents/agent_123/skills/cortex-mode" \
  -H "Content-Type: application/json" \
  -H "Cookie: next-auth.session-token=SEU_TOKEN_DE_SESSAO" \
  -d '{"mode": "active"}'
```

**TypeScript:**

```ts theme={null}
const response = await fetch(`/api/agents/${agentId}/skills/cortex-mode`, {
  method: 'PATCH',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ mode: 'active' }),
});

const result = await response.json();
// { configuredMode: 'active', effectiveMode: 'active' }
```

***

## 5. Cortex + Integração com Skills

O Cortex funciona exclusivamente com o sistema de **Agent Skills**. Para usar o Cortex de forma efetiva:

### Passo 1: Crie Skills

Crie pelo menos 3–5 skills ativas para seu agente. Cada skill deve cobrir um cenário distinto que seu IA pode encontrar.

→ Veja [Agent Skills](/pt-BR/agent-skills) para saber como criar skills.

### Passo 2: Ative as Skills

Certifique-se de que cada skill tenha `status: "active"`. Skills com status `draft` ou `archived` são ignoradas pelo Cortex.

### Passo 3: Escreva Descrições Claras

O campo `description` é o **principal sinal de correspondência** para o Cortex.

**Boa descrição:**

> "Quando o cliente menciona erro de cobrança, cobrança inesperada, pedido de reembolso ou contestação de pagamento."

**Descrição ruim:**

> "Para coisas de cobrança."

### Passo 4: Defina o Modo como `advisory` Primeiro

Teste no modo advisory antes de ir para ativo.

### Passo 5: Promova para `active`

Após verificar a cobertura e precisão das skills, defina o modo como `active`.

***

## 6. Referência de Endpoints

| Método  | Endpoint                              | Descrição                  | Auth                                    |
| ------- | ------------------------------------- | -------------------------- | --------------------------------------- |
| `GET`   | `/api/agents/[id]/skills/cortex-mode` | Obtém modo atual do Cortex | `agent_skills.read` OU `agents.read`    |
| `PATCH` | `/api/agents/[id]/skills/cortex-mode` | Define modo do Cortex      | `agent_skills.manage` OU `agents.write` |

***

## 7. Formato de Resposta

### Resposta de Sucesso

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

### Respostas de Erro

| Status | Corpo                                              | Causa                                    |
| ------ | -------------------------------------------------- | ---------------------------------------- |
| `400`  | `{ "error": "Invalid mode" }`                      | Valor do modo inválido                   |
| `404`  | `{ "error": "Agent not found for organization." }` | `agentId` não pertence à sua organização |
| `403`  | `{ "error": "Forbidden" }`                         | Permissões insuficientes                 |

***

## 8. Boas Práticas

### Guia de Seleção de Modo

| Situação                                                    | Modo Recomendado                     |
| ----------------------------------------------------------- | ------------------------------------ |
| Agente novo, sem skills ainda                               | `passive`                            |
| Construindo e testando biblioteca de skills                 | `advisory`                           |
| Agente em produção com 3+ skills ativas                     | `active`                             |
| Agente com propósito único focado (ex: bot de FAQ)          | `passive` ou `active` com 1–2 skills |
| Agente lidando com tópicos diversos (suporte, vendas, info) | `active` com 5–15 skills             |

***

## 9. Troubleshooting

| Problema                                       | Causa Possível                          | Solução                                                                               |
| ---------------------------------------------- | --------------------------------------- | ------------------------------------------------------------------------------------- |
| Cortex parece sempre selecionar a mesma skill  | Skills têm descrições sobrepostas       | Torne a `description` de cada skill mais específica e distinta                        |
| Cortex nunca seleciona uma skill               | Modo está em `passive`                  | Mude o modo para `advisory` ou `active`                                               |
| `effectiveMode` difere de `configuredMode`     | Transição de rollout em andamento       | Aguarde e verifique novamente                                                         |
| IA ignora skills no modo ativo                 | Skills têm status `draft` ou `archived` | Mude o status das skills para `active`                                                |
| Sem melhora nas respostas após ativar o Cortex | Conteúdo das skills muito genérico      | Reescreva o conteúdo das skills com instruções passo a passo específicas e acionáveis |