Principal Primeiros passos Como criar Sub-agentes na ClaudIA Agêntica

Como criar Sub-agentes na ClaudIA Agêntica

Última atualização em May 20, 2026

Quando usar

  • Você vai criar um novo Sub-agente para a ClaudIA Agêntica (rastrear pedido, consultar crédito, validar agendamento, qualificar lead, etc.).
  • Você está revisando um Sub-agente existente e quer alinhar com o padrão atual.
  • Você está migrando lógica de um Eddie (fluxo Typebot) para um Sub-agente.

Sobre este artigo

Sub-agentes são os especialistas da ClaudIA Agêntica. O Supervisor decide qual chamar a partir da descrição de cada Sub-agente e passa o request. O Sub-agente executa e devolve dado/resultado ao Supervisor, que formata a resposta para o cliente.

:::warning O Sub-agente nunca fala diretamente com o cliente. Ele devolve dados ao Supervisor, que cuida da comunicação. Frases prontas para o cliente dentro do system_prompt são bug. :::

Cada Sub-agente tem dois artefatos:

  • description (agent card) — texto curto que define se e quando este agente deve ser chamado.
  • system_prompt — instruções de como ele se comporta quando é chamado.

Como criar um Sub-agente

Opção recomendada — AI Companion

A forma mais rápida é usar o AI Companion dentro da plataforma. Você descreve em linguagem natural o que o agente precisa fazer e o Companion gera description e system_prompt no padrão atual.

O Companion consegue:

  • Criar um Sub-agente do zero a partir de um pedido em linguagem natural.
  • Migrar um Eddie (Typebot) existente para um Sub-agente — ele lê o fluxo, identifica tools necessárias, mapeia as regras de negócio e gera os artefatos.
  • Revisar um Sub-agente já criado e sugerir ajustes (description mais específica, system_prompt mais enxuto).
  • Iterar com você até o resultado ficar bom.

Veja o passo a passo em Como criar agentes com linguagem natural (AI Companion).

Mesmo usando o Companion, vale entender os dois artefatos abaixo para revisar o que ele gera.

Description (agent card)

A description é o texto que o Supervisor usa para decidir se e quando chamar este agente. Precisa ser objetiva, curta e em pt-BR.

Formato:

O QUE FAZ:
<1-3 frases sobre a ação. Descreva a AÇÃO, não a interface
("busca o endereço pelo CEP" ✓; "solicita o CEP ao cliente" ✗).>

PRÉ-REQUISITOS DE INVOCAÇÃO (request DEVE conter):
- <campo 1> — <formato esperado>

QUANDO ACIONAR:
<1-2 frases: que tipo de pedido do cliente dispara este agente,
COM o pré-requisito em mãos. Use a linguagem do cliente.>

QUANDO NÃO ACIONAR:
<1-2 frases: pedidos similares que NÃO são deste agente. Inclua
"cliente expressou intenção mas ainda não forneceu [pré-requisito]"
quando aplicável.>

Exemplo — Sub-agente de rastreamento:

O QUE FAZ:
Consulta o status atual de um pedido e devolve a posição da entrega.

PRÉ-REQUISITOS DE INVOCAÇÃO:
- número do pedido — formato alfanumérico, 8-12 caracteres

QUANDO ACIONAR:
Cliente quer saber onde está o pedido, status da entrega, ou se o
produto já foi enviado — E já forneceu o número do pedido.

QUANDO NÃO ACIONAR:
- Cliente quer cancelar, trocar ou devolver — outro especialista.
- Cliente relata defeito no produto recebido — escopo de garantia.
- Cliente expressou intenção mas ainda não enviou o número — Supervisor
  coleta antes.

:::info Por que os pré-requisitos importam: se a description só diz "agente rastreia pedido", o Supervisor invoca na intenção ("quero saber do meu pedido") sem o número. O Sub-agente devolve "incompleto", o Supervisor pergunta ao cliente, reinvoca — 2 round-trips em vez de 1. Declarando o pré-requisito, o Supervisor coleta o dado antes de rotear. :::

System Prompt

O system_prompt é a inteligência do agente. Princípios:

  • Explique o raciocínio, não só a regra. Em vez de "se status = IN_TRANSIT, responda em trânsito", escreva "traduza o status técnico para linguagem do cliente. IN_TRANSIT significa que o pedido saiu do CD e está a caminho".
  • Descreva critérios como sinais, não como if/else. "O sinal mais forte para qualificar é o tamanho da equipe (>50). Como segundo critério, o budget. Como último, o segmento."
  • Descreva a AÇÃO, não a tool. "Busque o endereço pelo CEP" funciona melhor do que citar o nome literal da tool — assim o prompt sobrevive a renomeações e mudanças no MCP.
  • Confie na IA com contexto parcial. Declare o princípio em vez de mapear todas as combinações: "trabalhe com o que tem, peça só o que precisa".
  • Deixe claro o papel: a resposta vai pro Supervisor, não pro cliente — formato direto: dados, status ou erro.

Erros comuns a evitar

  • Description sem pré-requisitos para agente data-dependent. Se precisa de CEP, CPF, número de pedido — declare. Sem isso, o Supervisor invoca sem o dado e queima round-trip.
  • "QUANDO NÃO ACIONAR" fraco. Sem distinguir "iniciar nova ação" vs "consultar existente", ou sem excluir defeito/reclamação/orientação, o roteamento erra sempre que a palavra-chave do domínio aparecer.
  • Capacidade na description sem cobertura no prompt nem tool. Se a description promete "lida com cancelamento", precisa existir cenário no system_prompt e tool que suporte a ação. Sem isso vira alucinação.
  • Mensagens prontas para o cliente no system_prompt. O Sub-agente devolve dados. O Supervisor monta a fala.
  • Lógica de conversa dentro do Sub-agente. Retenção, reformulação para cliente insistente, tom — tudo isso é do Supervisor. O Sub-agente faz a mesma coisa na primeira e na quinta chamada.
  • Formato de retorno engessado (DIAGNÓSTICO + MOTIVO + RECOMENDAÇÃO + …). Quanto mais campos estruturados o Sub-agente devolve, mais matéria-prima o Supervisor tem pra cherry-pickar trechos errados. Deixe a resposta emergir em prosa natural.
  • Prompts paranoicos com blocos longos de "BLOQUEANTE / fraude potencial" + frases prontas de recusa: o agente passa a recusar usar as tools. Anti-fabricação cabe em uma linha: "use somente dados retornados pelas tools".