Skip to main content
Use esta receita quando um turno do agente puder chamar várias ferramentas locais independentes com segurança e você quiser executá-las em paralelo sem alterar a ordem determinística dos resultados.

Quando usar

Use toolExecution.toolConcurrency quando:
  • o modelo puder emitir várias chamadas a ferramentas locais em um turno
  • essas ferramentas não dependerem dos resultados umas das outras
  • a execução em série desperdiçar tempo dos workers
  • você ainda quiser manter os resultados persistidos na ordem original das chamadas
Não use alta concorrência quando uma ferramenta alterar um estado compartilhado ou quando ferramentas posteriores dependerem de resultados anteriores.

Exemplo

Veja a versão incluída em packages/sdk/agent-sdk-ts/examples/parallel-tool-agent.ts.

O que o runtime garante

  • as ferramentas locais podem ser executadas em paralelo até o limite configurado em toolConcurrency
  • os eventos tool.started e tool.completed continuam sendo emitidos para cada ferramenta
  • as mensagens persistidas de resultado mantêm a ordem original das chamadas
  • o checkpoint continua sendo criado após a conclusão da fase de ferramentas
  • o tempo limite timeoutMs continua sendo aplicado a cada ferramenta

Orientações operacionais

  • comece com um valor baixo de concorrência, como 2 ou 3
  • mantenha as ferramentas locais idempotentes e com poucos efeitos colaterais
  • use timeoutMs para que uma dependência travada não ocupe todos os workers
  • adicione store somente se a aplicação realmente precisar retomar execuções ou coordenar processos remotos

Validação

Depois de habilitar este padrão:
  • execute os testes do loop do agente que cobrem turnos com várias ferramentas
  • confirme que o fluxo continua produzindo mensagens de resultados na ordem correta
  • confirme que os logs de operação continuam mostrando os eventos tool.started e tool.completed esperados
Última modificação em 2 de outubro de 2026