Orquestração Agêntica e Melhores Práticas Multiagente
Um checklist para projetar arquiteturas multiagente confiáveis e com custo limitado: quando usar múltiplos agentes, como projetar a divisão orquestrador/trabalhador, como delegar trabalho em paralelo, como escolher entre encadeamento e roteamento, e as salvaguardas, recuperação de erros, avaliação e disciplina de ADR que mantêm um sistema multiagente seguro para rodar em produção.
Como Usar Esta Lista
- Percorra os grupos na ordem na primeira vez que projetar um fluxo de trabalho multiagente; grupos posteriores (salvaguardas, avaliação, ADR) assumem que você já tomou as decisões nos anteriores.
- Trate o Grupo A como um portão, não uma formalidade. Se uma tarefa não passar no teste de decomposição, pare por ali e construa um único agente em vez disso.
- Use isto como um checklist de revisão de design para qualquer novo orquestrador, não apenas como uma referência única; revise-o sempre que o mix de tarefas de um fluxo de trabalho, o perfil de custo ou a taxa de falha mudarem.
- Cada item se vincula de volta à página nesta seção que explica o raciocínio e mostra código funcional.
A - Quando Usar Multiagente Afinal
- Comece cada tarefa como um único agente e prove que ele é insuficiente antes de dividi-lo. Um único loop de chamada de ferramenta é suficiente para a maioria das tarefas; multiagente é a exceção que tem que justificar sua complexidade adicionada, não a arquitetura padrão.
- Recorra a multiagente quando uma tarefa se decompõe em subtarefas independentes e paralelizáveis. Se você pode descrever as subtarefas como pontos de lista paralelos sem setas entre eles, dividir entre agentes vale a pena considerar; se os passos dependem do estado intermediário um do outro, mantenha-os em um loop.
- Recorra a multiagente quando subtarefas precisam de acesso a ferramentas ou contexto especializados, não para adicionar cerimônia. Uma subtarefa que só deveria ler arquivos, ou que precisa de um contexto mais restrito do que o resto da tarefa, é um candidato legítimo para seu próprio agente mesmo sem paralelismo, já que o escopo de ferramentas no Claude Agent SDK é definido por agente.
B - Design do Orquestrador/Trabalhador
- Dê ao orquestrador um único trabalho: despachar e mesclar, não o trabalho subjacente em si. Um orquestrador configurado com uma lista de ferramentas vazia e apenas
subagentsdefinido mantém seu papel ambíguo e o impede de fazer silenciosamente o trabalho de um trabalhador. - Escreva a descrição de cada trabalhador tão especificamente quanto a descrição de uma ferramenta. Uma
SubagentConfig.descriptionvaga não dá ao modelo do orquestrador nenhum sinal confiável para quando esse trabalhador se aplica, e ele o ignorará ou o invocará para a subtarefa errada. - Especifique a forma exata da saída mesclada no prompt do orquestrador. Deixado vago, um orquestrador irá por padrão colar o resultado bruto de cada trabalhador lado a lado em vez de sintetizá-los; nomeie as seções de destino, a ordenação e os limites de comprimento da mesma forma que você especificaria o tipo de retorno de uma função.
- Escopo as ferramentas de cada trabalhador independentemente do orquestrador e de qualquer outro trabalhador. Um trabalhador não herda nada automaticamente do pai; conceda a ele apenas o que seu trabalho específico requer, não a união de tudo o que o orquestrador pode fazer.
C - Delegação Paralela
- Inicie um subagente por subtarefa independente, não um subagente fazendo várias. O isolamento por subtarefa mantém os becos sem saída e as chamadas exploratórias de ferramentas de cada trabalhador fora do contexto dos outros trabalhadores e do orquestrador.
- Despache trabalhadores independentes concorrentemente, não sequencialmente. O despacho sequencial de subtarefas que não dependem umas das outras desperdiça o paralelismo que era a razão para delegar em primeiro lugar.
- Sequencie trabalhadores dependentes explicitamente quando um precisa da saída do outro. Forçar o despacho paralelo em um par onde o segundo trabalhador realmente precisa do resultado do primeiro produz um trabalhador que está adivinhando a entrada que ele ainda não tem.
- Faça com que cada trabalhador reporte um resultado final de volta ao agente coordenador, não um fluxo de estado parcial. O orquestrador deve ser capaz de raciocinar sobre o que um trabalhador encontrou sem reconstruí-lo a partir de chamadas de ferramentas intermediárias que ele nunca viu.
D - Encadeamento vs. Roteamento
- Use encadeamento de prompt para uma sequência fixa e previsível de passos. O encadeamento se adequa a fluxos de trabalho onde o próximo passo é sempre o mesmo, independentemente da entrada, e é mais simples de raciocinar e depurar do que uma alternativa dinâmica.
- Use roteamento quando o tipo de tarefa varia e o caminho a seguir é uma decisão dinâmica. O roteamento se adequa a tipos de tarefas variáveis onde diferentes entradas genuinamente precisam de tratamento diferente, não a um fluxo de trabalho que é sempre os mesmos três passos disfarçados.
- Não construa um roteador para um fluxo de trabalho que nunca realmente se ramifica. Uma decisão de roteamento desnecessária adiciona uma chamada de modelo e um modo de falha para uma escolha que sempre seria resolvida da mesma maneira.
- Não force entradas genuinamente variáveis através de uma única cadeia fixa. Forçar tudo através da mesma sequência produz passos desperdiçados para entradas que não precisavam deles, ou uma cadeia que silenciosamente lida mal com os casos para os quais não foi construída.
E - Salvaguardas: Profundidade, Ferramentas e Gastos
- Limite a profundidade dos subagentes. Trabalhadores que delegam a sub-trabalhadores multiplicam a sobrecarga de coordenação e tornam as falhas muito mais difíceis de rastrear até uma causa raiz; a maioria dos sistemas de produção limita a delegação a um ou dois níveis.
- Escopo o acesso a ferramentas para o menor privilégio, por agente. Cada ferramenta habilitada é uma área de superfície adicional na qual um agente, orquestrador ou trabalhador descontrolado pode agir sem supervisão; as decisões de escopo não se propagam automaticamente entre os agentes.
- Defina um orçamento explícito de tokens ou custos por tarefa, não apenas por execução. Uma etapa de síntese que lê o resultado completo de cada trabalhador no contexto pode gastar muito mais do que qualquer trabalhador individual gastou; limite o gasto total entre despacho e mesclagem, não apenas no nível do agente individual.
- Trate profundidade, ferramentas e gastos como um sistema de salvaguardas, não três controles separados. Um agente superficial, mas rico em ferramentas, pode gastar tanto e causar tanto dano quanto um agente profundo e com escopo restrito; revise todos os três juntos ao projetar ou auditar um fluxo de trabalho.
F - Recuperação de Erros
- Tente novamente uma chamada de ferramenta com falha antes de escalá-la como uma falha de tarefa. Falhas transitórias como limites de taxa ou uma chamada de rede instável não devem falhar toda a execução; uma nova tentativa limitada absorve o caso comum.
- Defina um fallback para um subagente que trava ou esgota seu orçamento de novas tentativas. Uma ferramenta mais simples, um trabalhador diferente, ou um encaminhamento para um humano são todos caminhos de fallback legítimos; deixar o orquestrador esperar indefinidamente não é.
- Aplique um padrão de disjuntor para que uma dependência falha não se propague pelo sistema. Uma vez que um trabalhador ou ferramenta falhou vezes suficientes em uma janela, pare de chamá-lo e apresente a falha em vez de tentar novamente para sempre e gastar orçamento em algo que não vai se recuperar por conta própria.
- Registre cada falha e a decisão de recuperação que a seguiu. Sem um registro do que falhou e o que entrou em ação depois, você não pode dizer se uma dependência genuinamente instável é um bug sistêmico em sua lógica de orquestração.
G - Avaliação Antes da Produção
- Pontue a taxa de sucesso da tarefa em um conjunto de tarefas representativo antes de lançar. Um processo de avaliação repetível, não verificações pontuais anedóticas durante o desenvolvimento, é o que diz se a arquitetura realmente funciona na gama de entradas que ela verá em produção.
- Acompanhe o custo por tarefa ao lado da taxa de sucesso, não apenas a taxa de sucesso. Um design multiagente que tem mais sucesso, mas custa várias vezes mais por execução por tarefa, pode não ser a troca certa para o fluxo de trabalho; avalie ambos juntos.
- Catalogar modos de falha, não apenas uma contagem de aprovação ou reprovação. Entender como um fluxo de trabalho falha, um trabalhador travado, uma mesclagem ruim, um caso de borda perdido, é o que diz em qual salvaguarda ou fallback investir a seguir.
- Reexecute a avaliação sempre que um prompt, modelo ou o escopo de ferramentas de um subagente mudar. Uma avaliação de antes de uma mudança significativa não diz nada confiável sobre o sistema como ele está hoje.
H - Disciplina de ADR
- Escreva um ADR antes de se comprometer com um orquestrador multiagente para um fluxo de trabalho. Documentar a troca entre um único agente e um orquestrador multiagente força uma decisão deliberada no ponto em que ela é tomada, em vez de uma arquitetura que acumulou um subagente de cada vez.
- Registre qual necessidade de decomposição ou especialização justificou a divisão. Se você não consegue declarar a razão específica claramente no ADR, o teste de decomposição no Grupo A provavelmente não foi realmente atendido.
- Revisite o ADR quando o mix de tarefas ou o perfil de custo do fluxo de trabalho mudar materialmente. Uma decisão de arquitetura que estava correta no lançamento pode se tornar errada à medida que o volume de tarefas, o custo ou os requisitos mudam, e o ADR é o registro que diz à próxima pessoa por que ela foi feita em primeiro lugar.
FAQs
Quando um único agente ainda é a chamada certa, mesmo que uma tarefa pareça complexa?
Quando os passos são sequenciais e dependem do estado intermediário um do outro, não importa quantos passos existam. A complexidade no raciocínio não requer múltiplas janelas de contexto; apenas a independência genuína entre subtarefas o faz.
Qual é a maneira mais rápida de saber se uma tarefa se decompõe bem o suficiente para multiagente?
Tente descrever as subtarefas como pontos de lista paralelos sem setas entre eles. Se você não consegue fazer isso sem adicionar uma seta (subtarefa B precisa do resultado da subtarefa A), ela não é independente o suficiente para ser dividida de forma limpa.
O orquestrador em si deve ter ferramentas?
Somente se ele precisar fazer algo além de despachar e mesclar, como escrever o resultado final em um arquivo. Quando seu trabalho é puramente síntese, uma lista de ferramentas vazia mantém seu papel ambíguo e o impede de fazer o trabalho de um trabalhador.
Qual é a diferença entre encadeamento e roteamento na prática?
Encadeamento é uma sequência fixa: o passo dois sempre segue o passo um da mesma maneira. Roteamento é uma decisão dinâmica: o fluxo de trabalho escolhe qual caminho seguir com base na entrada. Use encadeamento para fluxos de trabalho previsíveis e roteamento para tipos de tarefas variáveis.
Até que ponto a delegação de subagentes deve ir?
Limite a um ou dois níveis para quase todos os sistemas de produção. Delegação mais profunda, trabalhadores que por si só geram sub-trabalhadores, multiplica a sobrecarga de coordenação e torna as falhas muito mais difíceis de rastrear até uma causa raiz.
Qual é a maneira mais comum de sistemas multiagente saírem do controle de custos?
Um prompt em aberto que permite ao orquestrador despachar quantos trabalhadores ele decidir que precisa, combinado com uma etapa de mesclagem que lê o resultado completo de cada trabalhador no contexto. Limite a contagem de subagentes e o gasto de tokens explicitamente em vez de deixar o despacho em aberto.
O que deve acionar uma nova tentativa vs. um fallback vs. um disjuntor?
Tente novamente uma única falha transitória, como um limite de taxa. Recorra assim que um orçamento de nova tentativa for esgotado ou um subagente travar completamente. Acione um disjuntor assim que uma dependência falhar repetidamente em uma janela, para que o sistema pare de chamar algo que claramente não vai se recuperar.
O que significa "avaliar antes da produção" na prática?
Executar o fluxo de trabalho contra um conjunto de tarefas representativo e pontuar a taxa de sucesso da tarefa, o custo e os modos de falha como um processo repetível, não apenas verificar se funcionou nos exemplos que você testou manualmente durante o desenvolvimento.
Todo fluxo de trabalho multiagente precisa de um ADR?
Qualquer fluxo de trabalho onde você está escolhendo um orquestrador multiagente em vez de um único agente deve ter um. O ADR é o que documenta a troca e a necessidade específica de decomposição ou especialização que justificou a complexidade adicionada.
Qual é o maior erro que as equipes cometem quando adotam multiagente pela primeira vez?
Recorrer a ele por padrão em vez de provar que um único agente é insuficiente primeiro. A maioria das tarefas permanece como agente único; multiagente justifica sua complexidade apenas quando uma tarefa se decompõe genuinamente ou precisa de acesso a ferramentas especializadas.
Um único subagente pode quebrar salvaguardas por conta própria?
Sim, se seu próprio escopo de ferramentas ou gastos não forem limitados independentemente. As salvaguardas se aplicam por agente, não apenas no nível superior; um orquestrador com escopo restrito e um trabalhador ilimitado ainda tem um sistema ilimitado no geral.
Como a delegação paralela e o design orquestrador/trabalhador se relacionam?
Orquestrador/trabalhador é a divisão de papéis, um agente despacha e mescla, outros fazem o trabalho subjacente. A delegação paralela é uma propriedade de como esse despacho acontece: trabalhadores independentes rodando concorrentemente em vez de um após o outro. Você pode ter um sem o outro, mas eles geralmente são emparelhados na prática.
Relacionados
- Loops de Agente Único vs. Sistemas Multiagente: Um Modelo Mental - o teste de decomposição por trás do Grupo A
- Padrões de Orquestrador/Trabalhador com o Claude Agent SDK - o design de despacho e mesclagem em profundidade
- Salvaguardas para Sistemas Multiagente: Limitando Custo e Escopo - profundidade, acesso a ferramentas e limites de gastos em profundidade
- Avaliando a Qualidade do Agente: Um Checklist para Prontidão de Produção - o processo de avaliação por trás do Grupo G
- Modelo de ADR: Agente Único vs. Orquestrador para um Novo Fluxo de Trabalho - um modelo para a disciplina de ADR no Grupo H
- Melhores Práticas do Claude Agent SDK - as práticas de nível de SDK subjacentes nas quais esta seção se baseia
Versões de Stack: Escrito contra a linha de modelos Claude atual em ~junho de 2026 - Claude Fable 5, Claude Opus 4.8, Claude Sonnet 5 (o padrão), e Claude Haiku 4.5 - e o Claude Agent SDK (última versão). Nomes de modelos, versões de SDK e preços mudam rapidamente - verifique os detalhes atuais em platform.claude.com/docs antes de confiar neles.