Como criar Sub-agentes

Sub-agentes são os especialistas da ClaudIA Agêntica. Cada um é treinado para uma área específica — rastrear pedidos, consultar crédito, verificar agendamentos, qualificar leads.

O Supervisor decide qual Sub-agente chamar e passa o contexto necessário. O Sub-agente executa, retorna os dados, e o Supervisor formata a resposta para o cliente.

O Sub-agente nunca fala diretamente com o cliente. Ele retorna dados para o Supervisor, que cuida da comunicação.

📋 O que compõe um Sub-agente

Cada Sub-agente tem dois artefatos principais:

📝 Como escrever a Description do Sub-agente

A description do sub-agente é o texto que o Supervisor usa para decidir se e quando chamar aquele Sub-agente. É o mecanismo de roteamento.

Formato:

When to call: [1-5 frases descrevendo que tipo de pedido do cliente aciona este agente.
Usar linguagem do cliente, não termos internos.]

Do NOT call if: [1-3 frases delimitando pedidos similares que NÃO são trabalho deste agente]

Exemplo para um Sub-agente de rastreamento:

When to call: O cliente quer saber onde está o pedido, qual o status da entrega,
ou se o produto já foi enviado.

Do NOT call if: O cliente quer cancelar o pedido, solicitar troca ou relatar
que o produto chegou errado — esses casos são de outro especialista.

Regras importantes:

• Use a linguagem do cliente — se o cliente diz "quero cancelar", use "quero cancelar", não "workflow de prevenção de churn"

• Mantenha ~60 palavras no total — a description compete com outras descriptions pela atenção do modelo

• Não liste campos obrigatórios nem status de retorno — o Supervisor interpreta naturalmente

🧩 Como escrever o System Prompt

O system prompt instrui o Sub-agente sobre como executar sua tarefa. A estrutura sugerida:

1. Quem você é e como é acionado — contexto básico de papel

2. O que precisa descobrir/resolver — objetivo de negócio em linguagem clara

3. Sinais e critérios de decisão — descreva como sinais com peso, não como if/else rígido

4. Como lidar com informação parcial — declare um princípio, não mapeie cada combinação

5. Ferramentas disponíveis — quais tools pode usar e quando

6. O que retornar — para cada tipo de outcome: resolvido, dados faltantes, erro, escalação

7. Limites — lista curta do que nunca fazer

Princípio fundamental

Explique o raciocínio, não só a regra.

❌ "Se o campo status for IN_TRANSIT, responda que o pedido está em trânsito."

✅ "Traduz o status técnico da API para linguagem do cliente. IN_TRANSIT significa que o pedido saiu do centro de distribuição e está a caminho — use essa explicação, não o código interno."

Descreva critérios como sinais

Em vez de if/else, descreva o que pesa mais na decisão:

"O sinal mais forte para qualificar é o tamanho da equipe (>50). Como segundo critério, considere o budget declarado. Como último recurso, use o segmento de mercado."

⚠️ Erros comuns a evitar

Na description do sub-agente:

• Usar jargão interno que o cliente nunca usaria → roteamento falha

• Esquecer o "Do NOT call if" → o Supervisor pode chamar o agente errado em casos limítrofes

No system prompt:

• Divergência entre a description e o prompt → uma description muito ampla e um prompt engessado vai gerar muitos acionamentos mas que o sub-agent nao tenha autonomia para agir e resolver boa parte deles, e vice-versa

• Escrever fluxogramas de if/else → a IA não precisa de fluxograma, precisa de lógica

• Colocar mensagens prontas para o cliente → quem cuida da comunicação é o Supervisor

• Tentar lidar com a retenção do cliente ou reformular respostas → responsabilidade do Supervisor

• Over-especificar cada cenário → declare o princípio e confie na IA

✅ Checklist de validação

Description do sub-agente:

• O sistema identificaria quando chamar baseado só na description?

• Está claro o que o agente não faz?

• A linguagem reflete as palavras do cliente?

• Tem menos de ~60 palavras?

System prompt:

• Explica o porquê das regras, não só o quê?

• Usa sinais com peso, não árvores if/else?

• Tem um princípio para lidar com informações incompletas?

• Não tem mensagens prontas para o cliente?

• Menciona as tools disponíveis e quando usá-las?

• Descreve o que retornar para cada tipo de resultado?

• Tem seção de limites (o que nunca fazer)?