Agent Cortex

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

Visão Geral
Como o Cortex Funciona
Modos do Cortex
Configurar o Modo do Cortex
Cortex + Integração com Skills
Referência de Endpoints
Formato de Resposta
Boas Práticas
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:

A mensagem atual do usuário
Histórico recente da conversa (janela de contexto)
Todas as skills ativas para o agente (e skills de escopo organização)
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

GET /api/agents/{agentId}/skills/cortex-mode

Resposta:

{
  "configuredMode": "advisory",
  "effectiveMode": "advisory"
}

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

Definir Modo

PATCH /api/agents/{agentId}/skills/cortex-mode
Content-Type: application/json

Corpo da Requisição:

{
  "mode": "active"
}

Valores válidos: "passive", "advisory", "active" cURL:

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:

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

{
  "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

Agent Skills

Livia - 360 Assistant

Conversations

Access Groups

Agent Cortex

🔢 Sumário

1. Visão Geral

O que é o Agent Cortex?

Por que é Importante

2. Como o Cortex Funciona

O que o Cortex Analisa

3. Modos do Cortex

`passive` — Cortex Desligado

`advisory` — Cortex Observa

`active` — Cortex Ligado

4. Configurar o Modo do Cortex

Obter Modo Atual

Definir Modo

5. Cortex + Integração com Skills

Passo 1: Crie Skills

Passo 2: Ative as Skills

Passo 3: Escreva Descrições Claras

Passo 4: Defina o Modo como `advisory` Primeiro

Passo 5: Promova para `active`

6. Referência de Endpoints

7. Formato de Resposta

Resposta de Sucesso

Respostas de Erro

8. Boas Práticas

Guia de Seleção de Modo

9. Troubleshooting

​🔢 Sumário

​1. Visão Geral

​O que é o Agent Cortex?

​Por que é Importante

​2. Como o Cortex Funciona

​O que o Cortex Analisa

​3. Modos do Cortex

​passive — Cortex Desligado

​advisory — Cortex Observa

​active — Cortex Ligado

​4. Configurar o Modo do Cortex

​Obter Modo Atual

​Definir Modo

​5. Cortex + Integração com Skills

​Passo 1: Crie Skills

​Passo 2: Ative as Skills

​Passo 3: Escreva Descrições Claras

​Passo 4: Defina o Modo como advisory Primeiro

​Passo 5: Promova para active

​6. Referência de Endpoints

​7. Formato de Resposta

​Resposta de Sucesso

​Respostas de Erro

​8. Boas Práticas

​Guia de Seleção de Modo

​9. Troubleshooting

🔢 Sumário

1. Visão Geral

O que é o Agent Cortex?

Por que é Importante

2. Como o Cortex Funciona

O que o Cortex Analisa

3. Modos do Cortex

`passive` — Cortex Desligado

`advisory` — Cortex Observa

`active` — Cortex Ligado

4. Configurar o Modo do Cortex

Obter Modo Atual

Definir Modo

5. Cortex + Integração com Skills

Passo 1: Crie Skills

Passo 2: Ative as Skills

Passo 3: Escreva Descrições Claras

Passo 4: Defina o Modo como `advisory` Primeiro

Passo 5: Promova para `active`

6. Referência de Endpoints

7. Formato de Resposta

Resposta de Sucesso

Respostas de Erro

8. Boas Práticas

Guia de Seleção de Modo

9. Troubleshooting