Como estruturar um fluxo de multi-agentes do zero
Nível: Avançado
Tempo de leitura: 10 min
Quando faz sentido usar multi-agentes
Antes de construir um fluxo com múltiplos agentes, vale responder uma pergunta simples: o problema que você quer resolver é grande demais para um único agente bem configurado?
Multi-agentes fazem sentido quando:
- Você tem dois ou mais escopos muito distintos, com bases de conhecimento e ferramentas diferentes (ex: vendas e suporte técnico)
- O volume de conversas é alto o suficiente para justificar especialização
- Um único agente está respondendo mal por tentar cobrir escopos incompatíveis
- Você quer medir performance separadamente por área
Se um agente bem configurado resolve o problema, prefira a simplicidade. Cada camada de roteamento adiciona complexidade e pontos de falha.
Os três papéis no fluxo
Orquestrador: recebe todas as mensagens dos usuários, identifica a intenção e decide para qual especialista encaminhar. Não resolve nada diretamente.
Sub-agente: especialista em um domínio específico. Só entra em cena quando o orquestrador decide acionar. Tem seu próprio prompt, base de conhecimento e ferramentas.
Standalone: agente independente que não participa de nenhum fluxo. Útil quando os escopos são separados a ponto de não terem usuários em comum.
Passo a passo para montar um fluxo
Etapa 1: Mapeie os escopos
Antes de criar qualquer agente, liste claramente o que cada especialista vai cobrir. Seja específico nos limites.
Exemplo para uma empresa de software:
| Sub-agente | Escopo | Fora do escopo |
|---|---|---|
| Vendas | Planos, preços, trials, demos | Problemas técnicos de clientes ativos |
| Suporte | Bugs, configuração, integrações | Negociação comercial |
| Financeiro | Faturas, cobranças, cancelamento | Questões técnicas ou comerciais |
Etapa 2: Crie os sub-agentes primeiro
Crie cada sub-agente como se fosse um agente standalone. Configure:
- Prompt de sistema focado no escopo do especialista
- Base de conhecimento relevante para aquela área
- Integrações e ferramentas necessárias
- Mensagem de boas-vindas (usada quando o agente assume a conversa)
Teste cada sub-agente individualmente antes de conectar ao orquestrador.
Etapa 3: Crie o orquestrador
Crie um novo agente e defina o tipo como Orquestrador na aba Identidade.
O prompt do orquestrador deve:
- Descrever brevemente o que a empresa faz
- Listar os especialistas disponíveis e o que cada um resolve
- Instruir sobre como usar o token de transbordo
Exemplo de prompt de orquestrador:
Você é o assistente virtual da Acme Software. Sua função
é entender o que o usuário precisa e encaminhar para o
especialista certo.
Especialistas disponíveis:
- Vendas: planos, preços, trials e demonstrações
- Suporte: problemas técnicos, configuração e integrações
- Financeiro: faturas, cobranças e cancelamentos
Quando identificar que o usuário quer falar sobre vendas,
inclua [[HANDOFF:vendas]] na sua resposta.
Quando for suporte, use [[HANDOFF:suporte]].
Quando for financeiro, use [[HANDOFF:financeiro]].
Antes de fazer o transbordo, confirme o encaminhamento em
uma frase breve. Exemplo: "Vou te conectar com nosso time
de suporte. Um momento."
Etapa 4: Configure o campo de instruções de roteamento
No orquestrador, preencha também o campo Instruções de roteamento (abaixo do tipo de agente). Esse campo complementa o prompt com diretrizes específicas de decisão:
Rotear para Vendas quando o usuário:
- Perguntar sobre preços ou planos
- Quiser fazer um trial ou demo
- Mencionar que está avaliando a ferramenta
Rotear para Suporte quando o usuário:
- Reportar um erro ou comportamento inesperado
- Pedir ajuda com configuração ou integração
- Mencionar que é cliente ativo com problema
Rotear para Financeiro quando o usuário:
- Questionar uma cobrança ou fatura
- Quiser cancelar ou pausar o plano
- Tiver problema com pagamento
Etapa 5: Conecte no editor de fluxo
Acesse o orquestrador e clique em Editar fluxo visual. No editor:
- O orquestrador aparece como nó central
- Adicione conexões para cada sub-agente
- Para cada conexão, defina o label (deve ser idêntico ao token de transbordo:
vendas,suporte,financeiro) - Opcionalmente, adicione uma condição descritiva para documentação interna
Salve o fluxo.
Etapa 6: Publique e exponha o orquestrador
O canal público deve apontar para o orquestrador, não para os sub-agentes. Os sub-agentes nunca são acessados diretamente pelos usuários.
Para web, o link público e o código de incorporação estão na aba Publicação do orquestrador. Para WhatsApp, acesse Conectores e vincule o número ao agente orquestrador.
Testando o fluxo
Antes de publicar, teste cada rota individualmente:
- Mensagem claramente de vendas: o orquestrador encaminhou corretamente?
- Mensagem claramente de suporte: o sub-agente certo assumiu?
- Mensagem ambígua: o orquestrador pediu esclarecimento ou chutou?
- O sub-agente tem contexto do que foi dito antes do transbordo?
- Após o transbordo, o sub-agente se apresenta adequadamente?
Erros comuns
Orquestrador tentando resolver tudo: se o prompt do orquestrador for muito detalhado sobre os assuntos de cada área, ele começa a responder diretamente em vez de encaminhar. O prompt do orquestrador deve ser enxuto e focado em identificar e rotear.
Labels de transbordo com erro de digitação: o token [[HANDOFF:suporte]] precisa ser exatamente igual ao label configurado no editor de fluxo (case-insensitive, mas sem espaços extras ou caracteres diferentes). Qualquer diferença e o transbordo não acontece.
Sub-agentes sem contexto: o sub-agente recebe o histórico da conversa, mas se o prompt dele não instrui sobre como usar esse contexto, ele pode se apresentar como se fosse o primeiro contato. Instrua o sub-agente a verificar o histórico antes de responder.
Fluxo com muitas camadas: dois ou três sub-agentes é o ideal para a maioria dos casos. Fluxos com cinco ou mais sub-agentes ficam difíceis de manter e testar.
Monitorando no painel
O painel do orquestrador mostra a distribuição de conversas e eventos por sub-agente. Use esses dados para:
- Identificar qual área tem maior demanda
- Detectar sub-agentes com taxa de resolução baixa (indicam necessidade de ajuste no prompt ou na base de conhecimento)
- Verificar se o orquestrador está encaminhando corretamente (conversas caindo no sub-agente errado é sinal de problema no roteamento)