Fan-out e fan-in em agentes de IA: como projetar

Uma tarefa entra e vinte chamadas aparecem

Um agente recebe a solicitação de analisar uma carteira de contratos. Ele separa os documentos, inicia análises em paralelo e aguarda os resultados. Dezoito ramos terminam, um encontra um arquivo inválido e outro ultrapassa o prazo.

A execução principal precisa decidir se entrega uma conclusão parcial, espera, repete apenas o ramo com falha ou encerra tudo. Sem um contrato para essa decisão, o ganho de paralelismo vira uma combinação de custo imprevisível, resultado incompleto e repetição difícil de rastrear.

Fan-out é a decomposição de uma unidade de trabalho em ramos que podem avançar em paralelo. Fan-in é a reunião desses ramos em uma saída coerente. O desenho precisa preservar identidade, limite, estado e critério de conclusão desde a divisão até a agregação.

Este recorte é diferente de backpressure em agentes de IA, que faz a saturação reduzir a entrada. Também difere de falha parcial em lotes, que governa itens agrupados na mesma execução. Aqui, o objeto central é uma tarefa que cria subtarefas e depois depende da combinação dos resultados.

Confirme se os ramos são realmente independentes

Paralelismo ajuda quando cada ramo consegue produzir um resultado útil sem depender da conclusão dos demais.

Exemplos adequados incluem:

consultar fontes diferentes para o mesmo dossiê;
analisar documentos independentes de uma pasta;
executar testes distintos sobre uma versão candidata;
classificar unidades sem relação de ordem;
preparar seções que depois passam por uma validação comum.

A execução sequencial continua necessária quando um ramo altera a entrada do seguinte, existe ordem por objeto, a primeira decisão pode encerrar o restante ou várias tarefas disputam o mesmo recurso exclusivo.

Dividir por conveniência técnica sem respeitar dependências cria resultados que parecem completos isoladamente e entram em conflito no fan-in.

Escreva o manifesto antes de iniciar os ramos

A execução principal precisa registrar o plano de decomposição. Um manifesto mínimo contém:

identificador da tarefa principal;
versão da entrada;
lista de subtarefas esperadas;
identificador estável de cada ramo;
motivo e escopo de cada ramo;
dependências;
prazo individual e prazo global;
orçamento de chamadas, tokens e custo;
permissão e fontes disponíveis;
formato de saída;
regra de repetição;
critério de agregação;
política de cancelamento.

Esse registro permite distinguir um ramo ausente de um ramo concluído com saída vazia. Também impede que uma retomada crie novos identificadores e repita efeitos já confirmados.

Um exemplo conceitual com dados fictícios:

{
  "job_id": "analise-contratos-2026-09-28-01",
  "input_version": "v3",
  "deadline": "2026-09-28T18:00:00Z",
  "branches": [
    {"branch_id": "contrato-101", "status": "pendente", "required": true},
    {"branch_id": "contrato-102", "status": "pendente", "required": true},
    {"branch_id": "anexos-gerais", "status": "pendente", "required": false}
  ],
  "completion_policy": "todos_os_obrigatorios_validos"
}

O schema real deve carregar somente dados necessários e autorizados. Referências protegidas costumam ser melhores que documentos inteiros gravados no histórico do orquestrador.

Limite a largura do fan-out

Iniciar todos os ramos ao mesmo tempo reduz a duração apenas enquanto workers, modelos, APIs, bancos e revisores suportam a carga.

A política precisa definir:

máximo de ramos ativos por tarefa;
máximo por cliente, processo e dependência;
reserva para trabalho crítico;
profundidade máxima de decomposição;
número total de subtarefas;
orçamento compartilhado da tarefa principal;
comportamento quando não há capacidade;
condição para abrir outro ramo.

A documentação da Temporal apresenta execução paralela com Activities ou Child Workflows e recomenda limitar concorrência, usar lotes para não sobrecarregar workers e dependências, tratar falhas e controlar a coleta de resultados. A documentação também alerta para limites de histórico e de execuções pendentes.

A AWS Step Functions oferece o estado Map para iterar sobre itens em paralelo. O modo inline mantém as iterações no histórico da execução principal e possui concorrência limitada. O modo distribuído cria execuções filhas com histórico separado e alta concorrência. Esses limites pertencem ao produto e podem mudar; o desenho empresarial ainda precisa usar um teto compatível com os sistemas seguintes.

O máximo do fornecedor informa capacidade técnica. Ele não informa quantas aprovações a equipe consegue revisar nem quantas escritas o ERP aceita sem degradar.

Use uma janela deslizante quando o conjunto for grande

Uma janela deslizante mantém apenas uma quantidade definida de ramos ativos. Quando um termina, outro começa.

O fluxo fica assim:

validar o manifesto;
reservar a capacidade inicial;
iniciar até o teto de concorrência;
registrar cada conclusão;
liberar a reserva do ramo encerrado;
verificar prazo, orçamento e saúde das dependências;
iniciar o próximo ramo elegível;
interromper a abertura quando um gate reprovar.

Esse desenho reduz o pico e permite reagir durante a execução. Se a latência do CRM subir, a janela pode permanecer fechada para novas escritas enquanto ramos de leitura já iniciados terminam.

A página sobre rate limit para agentes de IA detalha cotas e concorrência por recurso. O fan-out deve consumir essa capacidade, sem criar uma rota paralela que escape da política.

Escolha a unidade de isolamento

Nem toda subtarefa precisa virar outro agente ou workflow completo.

Uma operação simples e curta pode ser uma chamada assíncrona dentro da mesma execução. Um ramo com estado próprio, várias etapas, prazo longo, consultas, cancelamento e recuperação pode justificar um workflow filho.

Avalie:

duração;
quantidade de etapas;
necessidade de consulta individual;
volume de histórico;
política de repetição;
necessidade de cancelamento independente;
equipe ou worker especializado;
permissão diferente;
possibilidade de sobreviver à execução principal.

A documentação da Temporal recomenda Child Workflows quando os subprocessos precisam de acompanhamento e estado próprios. Para operações leves, Activities evitam a sobrecarga de criar workflows adicionais.

Arquitetura distribuída cobra aluguel. Se cada ramo não precisa de identidade operacional própria, um agente adicional pode ser só complexidade usando crachá.

Faça cada ramo terminar com um contrato

O fan-in não deveria interpretar textos livres para descobrir se uma subtarefa terminou corretamente.

Cada ramo devolve campos estruturados, como:

branch_id;
input_version;
status;
result ou referência protegida;
evidence;
validation_state;
error_class;
attempt_id;
started_at e finished_at;
efeito externo confirmado;
próxima ação quando houver pendência.

O resultado precisa distinguir:

concluído e validado;
concluído sem evidência suficiente;
falha temporária;
entrada inválida;
cancelado;
vencido;
estado externo incerto;
não iniciado.

Essa taxonomia evita que ausência, erro e conclusão vazia sejam tratados como o mesmo null.

Defina a política de fan-in antes da execução

O agregador precisa saber quando possui material suficiente para concluir.

Todos os ramos obrigatórios

A tarefa só termina quando cada ramo marcado como obrigatório conclui e passa pela validação. Serve para fechamento, reconciliação e análises em que uma parte ausente invalida o conjunto.

Quórum explícito

A conclusão aceita uma quantidade ou proporção definida de resultados, desde que nenhum ramo crítico esteja ausente. O quórum precisa representar uma regra do processo, não um atalho para esconder falhas.

Primeiro resultado válido

Vários ramos buscam o mesmo tipo de resposta e a primeira saída que cumpre os critérios encerra a disputa. Os demais são cancelados quando isso é seguro.

Resultado parcial com pendências

O sistema entrega o que foi confirmado e registra lacunas, impacto, dono e prazo. Essa política serve quando os ramos são independentes e a decisão pode avançar sem fingir completude.

Falha rápida

Uma condição impeditiva encerra a tarefa principal e cancela o restante. Use quando um bloqueio invalida todo o trabalho posterior, como permissão negada ou versão de entrada obsoleta.

A política deve aparecer no manifesto e nos testes. Decidir depois que três ramos falharam costuma favorecer a resposta mais conveniente para o sistema, não a correta para o processo.

Agregue evidência antes de redigir a conclusão

O fan-in tem duas etapas diferentes.

Primeiro, valide os ramos:

todos pertencem ao mesmo job_id;
a versão da entrada continua vigente;
não existem resultados duplicados;
ramos obrigatórios estão presentes;
o schema está válido;
permissões e fontes continuam aplicáveis;
efeitos externos foram confirmados;
pendências estão classificadas.

Depois, construa a síntese. A redação final não deve apagar divergências para parecer coerente. Se duas fontes oficiais entram em conflito, o resultado mostra o conflito e pede a decisão adequada.

Em análises documentais, preserve ligação entre cada afirmação material e o ramo que trouxe a evidência. O artigo sobre citações verificáveis em RAG explica como validar suporte e aplicabilidade antes de liberar uma conclusão.

Trate falha parcial sem repetir sucessos

Uma falha num ramo não autoriza reiniciar toda a árvore.

A recuperação usa o mesmo job_id, mantém identificadores estáveis e abre outra tentativa somente para a unidade elegível. Antes de repetir:

confirme se o ramo chegou a produzir efeito;
verifique se a entrada e a autorização continuam válidas;
classifique a falha;
confira o prazo restante;
reserve capacidade;
use a mesma chave de idempotência quando houver consequência externa;
registre a nova tentativa sem apagar a anterior.

Se a falha for compartilhada, como credencial revogada ou destino indisponível, interrompa a abertura de novos ramos. Criar cem erros iguais produz volume, não diagnóstico.

Propague cancelamento e prazo

A tarefa principal e suas filhas precisam compartilhar uma política de encerramento.

Quando o prazo global vence, o orquestrador:

deixa de iniciar novos ramos;
solicita cancelamento dos ramos ativos;
preserva checkpoints seguros;
aguarda operações que não podem ser interrompidas abruptamente;
consulta efeitos externos incertos;
marca o que terminou, o que foi cancelado e o que exige reconciliação;
produz o estado final permitido pela política.

A documentação da Temporal diferencia políticas para o comportamento dos filhos quando a execução principal fecha. A configuração precisa ser intencional. Abandonar filhos pode ser válido em tarefas realmente independentes; deixar execuções órfãs por acidente amplia custo e consequência sem um dono visível.

O guia sobre cancelamento de tarefas em agentes de IA aprofunda propagação, pontos seguros e reconciliação.

Teste a árvore, não somente cada ramo

Um ramo aprovado isoladamente ainda pode falhar quando dezenas disputam recursos e retornam fora de ordem.

Inclua na matriz de teste:

todos os ramos concluídos;
um ramo inválido antes do início;
falha temporária em um ramo;
falha compartilhada da dependência;
resultados chegando fora de ordem;
resultado duplicado;
ramo concluído depois do prazo;
cancelamento da tarefa principal;
perda de confirmação de uma escrita;
retomada depois da interrupção do orquestrador;
estouro do teto de concorrência;
profundidade acima do permitido;
fan-in com ramo obrigatório ausente;
conflito entre duas evidências válidas;
repetição do mesmo manifesto.

Verifique chamadas, custo, tempo, efeitos externos, ausência de duplicidade, estado das pendências e aderência à política de conclusão.

Métricas para operar fan-out e fan-in

Acompanhe por tipo de tarefa:

ramos planejados, iniciados e concluídos;
concorrência ativa e máxima;
profundidade da árvore;
duração da tarefa principal e dos ramos;
tempo parado por falta de capacidade;
chamadas e custo por ramo;
resultados inválidos ou duplicados;
falhas por classe e dependência;
cancelamentos propagados;
efeitos externos incertos;
tarefas encerradas com pendência;
tempo entre último ramo e conclusão do fan-in;
resultados descartados por versão vencida;
diferença entre prazo global e conclusão válida.

O ganho precisa aparecer na unidade completa. Reduzir o tempo de execução dos ramos ajuda pouco se o fan-in cria uma fila de revisão ou se a recuperação repete toda a árvore.

Checklist de implementação

[ ] A tarefa principal possui identidade e versão?
[ ] Os ramos são independentes ou têm dependências declaradas?
[ ] Existe um manifesto com lista e escopo das subtarefas?
[ ] Largura, profundidade e orçamento possuem teto?
[ ] Cada ramo usa identificador estável entre tentativas?
[ ] O limite considera APIs, bancos e revisão humana?
[ ] A saída de cada ramo segue um contrato estruturado?
[ ] A política de fan-in foi definida antes da execução?
[ ] Resultados duplicados e vencidos são bloqueados?
[ ] Falha compartilhada interrompe novos ramos?
[ ] Cancelamento e prazo alcançam tarefas filhas?
[ ] Efeitos externos incertos entram em reconciliação?
[ ] O teste cobre ordem, falha parcial, retomada e saturação?
[ ] A síntese preserva evidências e divergências?

Fontes oficiais verificadas em 28 de setembro de 2026

Parallel Execution, Temporal Documentation. A página descreve execução concorrente, coleta de resultados, limites, falhas e controle de carga.
Fan-Out with Child Workflows, Temporal Documentation. A página apresenta divisão em partes, workflows filhos, agregação, identificadores determinísticos e limites operacionais.
Map workflow state, AWS Step Functions Developer Guide. A documentação diferencia os modos inline e distribuído, concorrência e histórico por execução.

Limites, nomes de recursos e defaults pertencem às plataformas citadas e podem mudar. Consulte a documentação da tecnologia adotada e valide o desenho no ambiente de teste.

A divisão termina quando existe uma conclusão verificável

Fan-out acelera trabalho independente. Fan-in devolve unidade ao processo. Entre os dois, a operação precisa manter identidade, capacidade, prazo, evidência e consequência sob controle.

O artefato central é o manifesto de execução junto com a política de agregação. Eles mostram quais ramos deveriam existir, quais terminaram, quais ainda impedem a conclusão e o que pode acontecer em seguida.