Este artigo apresenta os conceitos essenciais e os erros mais comuns na criação de sub-agentes (especialistas) na plataforma Claudia. Seguir essas boas práticas garante que o roteamento funcione corretamente, que o agente tome decisões consistentes e que a experiência do usuário final seja fluida.
Como funciona a arquitetura de agentes
Cada sub-agente possui dois campos principais:
-
Description (agent card) — texto que usado como descrição das capacidades que esse sub-agente possui. É com base nesse texto que o nosso sistema decide para qual agente encaminhar a conversa e se vai usar um sub-agente ou vai para a Claudia tradicional. Pontos principais são quando acionar e quando não acionar o sub-agente.
-
System prompt — conjunto completo de instruções que o sub-agente segue quando é acionado. Define quem ele é, o que deve fazer, como decidir e o que retornar.
O sub-agente nunca fala diretamente com o cliente. Ele recebe uma requisição em linguagem natural do supervisor de sub-agentes, executa sua lógica e retorna dados estruturados. Quem formata a resposta final para o cliente é sempre esse supervisor.
Erros conhecidos
Description com linguagem interna
A description é usada para decidir o roteamento da conversa. Se o cliente diz "quero cancelar" mas a description diz "workflow de churn prevention", o roteamento vai falhar. A description deve sempre usar a linguagem do cliente, não termos internos da operação.
Ausência de status de retorno na description
A description deve listar todos os resultados possíveis que o agente pode retornar: sucesso, dados faltantes, erro e necessidade de escalonamento humano. Sem essa informação, o supervisor não sabe como reagir ao resultado do agente e pode dar respostas genéricas ou incorretas ao cliente.
Regras sem explicação de contexto no system prompt
Escrever "se o valor for acima de 1.000, o lead é qualificado" sem explicar o porquê faz com que o agente aplique o critério de forma rígida e falhe em situações de borda. O correto é incluir o raciocínio por trás: "acima de 1.000 porque abaixo disso o custo não se paga para o cliente". Quando o agente entende a lógica de negócio, ele toma decisões melhores em cenários ambíguos.
Árvores de decisão no system prompt
Prompts com cadeias de "Se X, faça Y. Se não, verifique Z, faça W" são frágeis e difíceis de manter. Em vez de montar um fluxograma, descreva os critérios como sinais com pesos: "o sinal mais forte é X, seguido de Y, e como último recurso Z". O agente decide melhor quando entende prioridades do que quando segue um roteiro fixo.
Mensagens prontas para o cliente no system prompt
O sub-agente retorna dados estruturados — quem monta a resposta final é o supervisor, usando o tom de voz configurado. Incluir textos prontos como "Prezado cliente, informamos que..." no prompt do sub-agente cria conflito com o tom do supervisor e gera respostas inconsistentes.
Regras de roteamento repetidas no supervisor
A description do agente já é usada pelo sistema para decidir o roteamento. Repetir regras de "quando chamar" e "quando não chamar" no prompt do supervisor cria duas fontes de verdade que inevitavelmente divergem. O prompt do supervisor deve definir apenas como lidar com os resultados dos sub-agentes, não qual sub-agente chamar.
Sub-agente tentando interpretar a intenção do cliente
O sub-agente recebe uma requisição já processada pelo supervisor, não a mensagem original do cliente. Ele deve executar o que foi pedido, não tentar descobrir qual é a pergunta do cliente. Entender a intenção é responsabilidade do supervisor.
Passos numerados obrigatórios
Evite instruções como "Passo 1, Passo 2, Passo 3" como se fosse uma linha de montagem. O agente consegue resolver múltiplas questões ao mesmo tempo se tiver contexto suficiente. Passos rígidos limitam essa capacidade e tornam o prompt frágil a variações.
Mapeamento exaustivo de cenários
Tentar mapear todas as combinações possíveis de dados presentes ou ausentes gera prompts enormes e ainda assim incompletos. O princípio correto é: "vá o mais longe possível com o que você tem, peça apenas o que realmente precisa, e não pule para a opção mais complexa se caminhos mais simples ainda existirem".
Criação de tools
Tools são as ferramentas que os sub-agentes usam para consultar sistemas externos — buscar dados de um pedido, verificar status de pagamento, consultar estoque, etc. Elas são configuradas separadamente via MCP e vinculadas ao agente, não definidas dentro do prompt.
Como o sub-agente interage com tools
O sub-agente sabe quais tools estão disponíveis pela configuração do MCP. No system prompt, você descreve quando e por que usar cada tool, mas não define a tool em si. A definição técnica (URL, parâmetros, autenticação) fica na configuração do MCP.
Erros conhecidos
Tool sem descrição clara de parâmetros
Cada tool precisa ter seus parâmetros bem descritos — nome, tipo, se é obrigatório ou opcional, e o que representa. Se a tool aceita um order_id mas a descrição não deixa claro o formato esperado (ex: numérico, com prefixo, UUID), o agente pode enviar dados no formato errado e receber erros silenciosos.
Tool genérica demais
Uma tool que faz coisas demais (ex: "consulta qualquer informação do cliente") dificulta o uso correto pelo agente. Prefira tools com escopo bem definido: uma para buscar pedido, outra para consultar pagamento, outra para verificar endereço. Quando o agente tem clareza sobre o que cada tool faz, ele escolhe melhor.
Tool duplicada com nomes diferentes
Às vezes, durante a construção, são criadas duas tools que na prática chamam o mesmo endpoint com os mesmos parâmetros, mas com nomes diferentes. Isso confunde o agente, que pode chamar uma ou outra de forma inconsistente. Antes de criar uma nova tool, verifique se já não existe uma que faz a mesma coisa.
Falta de orientação de uso no system prompt
A tool existe e está configurada, mas o system prompt não menciona quando usá-la. O agente até pode descobrir sozinho em alguns casos, mas o resultado é imprevisível. No system prompt, inclua orientações como: "use a tool X quando o cliente perguntar sobre status do pedido" ou "só use a tool Y depois de já ter o número do pedido".
Tool que retorna dados demais
Se a tool retorna 30 campos mas o agente só precisa de 3 para responder ao cliente, o excesso de informação pode confundir a tomada de decisão. Quando possível, configure a tool para retornar apenas o que é necessário. Quando não for possível, oriente no system prompt quais campos são relevantes para cada situação.
Ausência de tratamento de erro
Toda tool pode falhar — timeout, dado não encontrado, erro de autenticação. O system prompt deve orientar o que fazer quando a tool retorna erro: tentar novamente, pedir outro dado ao cliente, ou escalar para atendimento humano. Sem essa orientação, o agente pode travar ou dar respostas vazias.
Checklist de validação de tools
-
A tool tem uma descrição clara do que faz?
-
Os parâmetros estão documentados com tipo, formato e obrigatoriedade?
-
Não existe outra tool que faz a mesma coisa com nome diferente?
-
O system prompt orienta quando e por que usar essa tool?
-
O retorno da tool contém apenas os dados necessários (ou o prompt orienta quais campos usar)?
-
O system prompt cobre o que fazer quando a tool falha?
Checklist de validação
Antes de publicar um agente, valide:
Na description:
-
O sistema conseguiria identificar corretamente quando chamar este agente apenas pela description?
-
Está claro o que este agente NÃO faz?
-
A linguagem usada reflete as palavras do cliente?
-
Os resultados de retorno cobrem sucesso, dados faltantes, erro e escalonamento?
No system prompt:
-
As regras incluem o raciocínio de negócio, não apenas valores numéricos soltos?
-
A lógica de decisão usa sinais com peso em vez de cadeias rígidas de se/então?
-
Existe um princípio para lidar com informações incompletas?
-
O prompt não contém mensagens prontas para o cliente?
-
As ferramentas disponíveis estão mencionadas com orientação de quando usar?
-
O que o agente retorna está claro para cada resultado possível?
-
Existe uma seção curta e direta de limites (o que nunca fazer)?
Conclusão
Garantir que os agentes sejam criados seguindo essas boas práticas é essencial para um roteamento preciso, decisões consistentes e uma experiência de atendimento fluida para o cliente. Agentes bem construídos são mais fáceis de manter, evoluir e investigar quando algo dá errado. A partir das validações e orientações descritas aqui, sua equipe pode criar agentes mais robustos, previsíveis e alinhados com a lógica real do negócio.