Principal Primeiros passos Boas práticas para criação de agentes na plataforma ClaudIA Agêntica

Boas práticas para criação de agentes na plataforma ClaudIA Agêntica

Última atualização em May 21, 2026

Quando usar

  • Você está construindo seu primeiro Sub-agente e quer evitar erros comuns
  • Você está revisando agentes existentes e quer um checklist de validação
  • Você quer entender as boas práticas para criação de tools

Pré-requisitos

  • Acesso à plataforma ClaudIA Agêntica
  • Conhecimento básico de arquitetura agêntica (Supervisor, Sub-agente, Tools)

Sobre este artigo

Este artigo apresenta conceitos essenciais e os erros mais comuns na criação de Sub-agentes (especialistas) na plataforma. Seguir essas boas práticas garante:

  • Roteamento funcionando corretamente

  • Decisões consistentes do agente

  • Experiência fluida do usuário final

Como funciona a arquitetura de agentes

Cada Sub-agente possui dois campos principais:

  1. Description (agent card) — texto usado como descrição das capacidades do Sub-agente. Com base nele, o sistema decide para qual agente encaminhar a conversa. Quando acionar e quando não acionar.

  2. System prompt — instruções completas que o Sub-agente segue quando é acionado. Define quem ele é, o que faz, 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, executa sua lógica e retorna dados estruturados. Quem formata a resposta final para o cliente é sempre o Supervisor.

Erros conhecidos

Description com linguagem interna

Se o cliente diz "quero cancelar" mas a description diz "workflow de churn prevention", o roteamento vai falhar. Use linguagem do cliente, não termos internos.

Ausência de status de retorno na description

A description deve listar todos os resultados possíveis: sucesso, dados faltantes, erro e necessidade de escalonamento. Sem isso, o Supervisor não sabe como reagir.

Regras sem explicação de contexto no system prompt

❌ "Se o valor for acima de 1.000, o lead é qualificado" (rígido, falha em borda)

✅ "Acima de 1.000 porque abaixo disso o custo não se paga" (lógica de negócio)

Árvores de decisão no system prompt

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 disso: descreva critérios como sinais com pesos — "o sinal mais forte é X, seguido de Y, e como último recurso Z".

Mensagens prontas para o cliente no system prompt

Sub-agente retorna dados estruturados — quem monta a resposta é o Supervisor, com tom de voz configurado. Textos como "Prezado cliente, informamos que..." no Sub-agente conflitam com o tom do Supervisor.

Regras de roteamento repetidas no Supervisor

A description já é usada para roteamento. Repetir "quando chamar" / "quando não chamar" no Supervisor cria duas fontes de verdade.

Sub-agente tentando interpretar a intenção do cliente

O Sub-agente recebe requisição já processada pelo Supervisor — não a mensagem original. Entender a intenção é responsabilidade do Supervisor.

Passos numerados obrigatórios

"Passo 1, Passo 2, Passo 3" (linha de montagem) limita a capacidade da IA de resolver múltiplas questões simultaneamente.

Mapeamento exaustivo de cenários

Não tente mapear todas as combinações. Use o princípio: "vá o mais longe possível com o que você tem, peça apenas o necessário, não pule para a opção complexa se houver caminhos simples".

Criação de tools

Tools são as ferramentas que os Sub-agentes usam para consultar sistemas externos. Configuradas via MCP e vinculadas ao agente — não definidas dentro do prompt.

Erros conhecidos em tools

Tool sem descrição clara de parâmetros

Cada tool precisa ter parâmetros bem descritos: nome, tipo, obrigatório/opcional, formato esperado (numérico, prefixo, UUID).

Tool genérica demais

Prefira tools com escopo bem definido. Uma para buscar pedido, outra para consultar pagamento, outra para verificar endereço.

Tool duplicada com nomes diferentes

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, mas o system prompt não menciona quando usar. Inclua: "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

Configure para retornar apenas o necessário ou oriente no system prompt quais campos são relevantes.

Ausência de tratamento de erro

Toda tool pode falhar. O system prompt deve orientar: tentar novamente, pedir outro dado, ou escalar para humano.

Checklist de validação de tools

  • A tool tem descrição clara do que faz?

  • Os parâmetros estão documentados (tipo, formato, obrigatoriedade)?

  • Não existe outra tool que faz a mesma coisa?

  • O system prompt orienta quando e por que usar?

  • O retorno contém só os dados necessários (ou o prompt orienta quais usar)?

  • O system prompt cobre erros?

Checklist de validação geral

Description

  • O sistema conseguiria identificar quando chamar apenas pela description?

  • Está claro o que NÃO faz?

  • A linguagem reflete as palavras do cliente?

  • Os retornos cobrem sucesso, dados faltantes, erro e escalonamento?

System prompt

  • As regras incluem raciocínio de negócio, não apenas valores numéricos?

  • Lógica de decisão usa sinais com peso em vez de cadeias rígidas?

  • Há um princípio para informações incompletas?

  • O prompt não tem mensagens prontas para o cliente?

  • As ferramentas estão mencionadas com orientação de uso?

  • O que retornar está claro para cada resultado?

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

Conclusão

Garantir que os agentes sejam criados seguindo essas boas práticas é essencial para roteamento preciso, decisões consistentes e experiência fluida. Agentes bem construídos são mais fáceis de manter, evoluir e investigar quando algo dá errado.

Observações