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.

O que é o código de roteamento

Cada conexão entre o orquestrador e um sub-agente tem um código de roteamento, que é um identificador curto tipo vendas ou suporte. É esse código que o orquestrador "fala" para acionar o sub-agente. Internamente o sistema usa o marcador [[HANDOFF:vendas]], mas você não precisa decorar isso, a sincronização com o prompt faz isso por você.

Por que o código existe separado do nome do agente:

Confiabilidade. Nomes humanos têm acento, espaço e maiúscula. O código limpo (vendas em vez de Equipe de Vendas B2B) reduz erro de digitação quando o orquestrador gera a resposta.
Liberdade pra renomear. Você pode trocar o nome do sub-agente sem precisar reescrever nada no orquestrador.
Mesmo sub-agente, contextos diferentes. O mesmo sub-agente pode ser conhecido como closer num orquestrador e como vendas em outro.

Convenção recomendada: só letras minúsculas, números e hífen. O sistema sugere automaticamente um código limpo quando você adiciona um sub-agente ao fluxo, mas você pode editar.

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 system prompt do orquestrador é focado em personalidade e contexto geral. Você não precisa colocar regras de roteamento aqui, o sistema faz isso por você na próxima etapa.

Exemplo:

Você é o assistente virtual da Acme Software. Atenda com tom
amigável e profissional. Antes de transferir para um especialista,
confirme o encaminhamento em uma frase curta tipo "Vou te conectar
com o time de suporte. Um momento."

Etapa 4: Conecte no editor de fluxo

Acesse o orquestrador e clique em Editar fluxo visual. No editor:

O orquestrador aparece como nó central
Clique em Adicionar sub-agente para conectar cada especialista
Para cada conexão, revise o código de roteamento (o sistema gera automaticamente um código limpo a partir do nome do sub-agente, mas você pode editar)
Opcional: clique na conexão e descreva quando ela deve disparar no campo Condição de roteamento (ex: "o usuário pedir ajuda técnica"). Isso entra na instrução automática.

Etapa 5: Sincronize as instruções com o prompt

No editor, clique em Definir regras de roteamento. Um preview mostra exatamente o que vai entrar no campo "Instruções de roteamento entre sub-agentes" do orquestrador, algo como:

Você é o assistente principal. Encaminhe cada conversa para o
especialista certo:

- Quando o usuário pedir ajuda técnica → responda apenas com [[HANDOFF:suporte]]
- Quando o usuário quiser falar de planos ou demos → responda apenas com [[HANDOFF:vendas]]
- Quando o usuário tiver dúvida sobre cobrança → responda apenas com [[HANDOFF:financeiro]]

Não escreva texto antes ou depois do código. O sub-agente assume
e responde ao usuário.

Revise e clique em Aplicar. Esse bloco é concatenado automaticamente ao system prompt do orquestrador em tempo de execução. Seu prompt principal não é modificado.

Se você quiser ajustar o texto manualmente, abra o agente e edite o campo "Instruções de roteamento entre sub-agentes". Se sincronizar de novo depois, o sistema mostra o diff antes de sobrescrever.

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 da transferência?
Após a transferência, 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.

Edição manual do bloco de roteamento sem cuidado: se você editou o conteúdo do campo "Instruções de roteamento entre sub-agentes" e mudou os códigos ([[HANDOFF:vendas]] → [[HANDOFF:venda]]), a transferência pode falhar. A comparação é tolerante a acentos, maiúsculas e espaços, mas erros de digitação como uma letra a mais quebram o match. Prefira usar Definir regras de roteamento para regenerar.

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)

Próximos passos

←

Como configurar roteamento por intenção

Como integrar com Google Calendar

→