AgentRun na prática: vale a pena para orquestração de agentes de IA?

Review do AgentRun: o que ele é na orquestração de agentes de IA

AgentRun é o interpretador de workflows em TypeScript da Parcha. Ele organiza ferramentas, decisões pontuais de modelos e chamadas de agentes dentro de uma estrutura determinística. A Parcha abriu o código em 23 de setembro de 2026. Um documento de workflow define contratos de estado, etapas, ramificações, limites e o caminho de escalonamento; a aplicação fornece ferramentas, acesso a modelos, permissões, armazenamento e entrega. Não se trata do produto homônimo da Alibaba Cloud, do pacote Python mais antigo que executa código gerado por modelos nem do jogo mobile de 2014 que ainda aparece nos resultados de busca. O pacote principal atual é o @parcha/agentrun-dsl versão 0.1.0-beta.4, distribuído sob a licença Apache-2.0.

Para quem o Parcha AgentRun serve — e quem deve evitar

AgentRun é indicado para equipes de TypeScript que já têm um runtime de agentes e conseguem apontar uma tarefa recorrente na qual o código convencional ficou difícil de inspecionar. A triagem de suporte é um bom exemplo: primeiro se faz a busca, depois se avalia se a resposta basta, gasta-se uma única chamada de agente apenas quando é necessário investigar e, por fim, o caso é respondido ou entregue a uma pessoa. Triagem de evidências, fluxos de aprovação e pipelines de pesquisa seguem o mesmo desenho. O ganho é maior quando alguém de produto, operações ou risco precisa entender o fluxo de controle sem percorrer uma teia de callbacks.

Não use AgentRun quando a tarefa cabe em uma função fixa com duas ou três ramificações óbvias. A implementação de controle usada neste review reproduziu os quatro resultados de suporte com um corpo de função de 31 linhas, enquanto o arquivo do workflow de exemplo no AgentRun tem 93 linhas antes mesmo da integração com o host. Em concisão bruta, a função vence.

Prefira LangGraph.js quando o problema central for um agente com estado, execução longa, persistência, streaming e intervenção humana. Escolha Temporal quando o requisito inegociável for manter a execução da aplicação diante de crashes, falhas de rede e esperas prolongadas. AgentRun expõe hooks de recuperação, mas não inclui um scheduler durável. Se a equipe precisa de Python, execução no navegador, dashboard hospedado ou SLA de suporte em produção, beta.4 também é uma escolha inadequada, porque esta versão não oferece nenhum desses itens.

Recurso 1 do AgentRun DSL: estado tipado detecta contratos quebrados

O primeiro ponto a favor do AgentRun DSL é recusar um valor final que já não corresponde ao contrato declarado. Parece algo básico, até o workflow combinar um resultado de busca, uma decisão semântica e o envio para um agente. Sem um validador final único, qualquer mudança de formato em uma ramificação pode chegar a quem chamou o sistema como um sucesso parcial.

O workflow de suporte diferencia um Candidate flexível do Answer final. A busca pode retornar texto vazio ou nenhuma fonte, pois essa condição deve poder acionar uma investigação. A conclusão é mais rigorosa: a resposta final exige texto não vazio e pelo menos uma fonte. O guia de autoria também valida os contratos declarados de entrada e saída, enquanto os caminhos do estado intermediário são verificados durante a execução.

O teste de contrato acrescentou um campo obrigatório sem alterar a saída da fixture:

schemaWorkflow.schemas.Answer.properties.resolutionCode = {
  type: 'string',
  minLength: 1,
};
schemaWorkflow.schemas.Answer.required.push('resolutionCode');

O fluxo de senha ainda fez a consulta de ajuda e a primeira decisão. Na conclusão, porém, falhou com WorkflowOutputInvalidError, código output_invalid, porque resolutionCode não existia. Nenhuma resposta inválida foi devolvida. Esse é o comportamento certo: o sistema para em seu limite em vez de tratar um objeto semanticamente plausível como resultado contratualmente completo.

A proteção tem um limite bem definido. Uma string text válida e um array sources válido ainda podem carregar uma resposta errada. A validação do schema comprova que o código seguinte consegue consumir o valor, não que o cliente deva confiar nele. O review complementar sobre roteamento de tickets de suporte com Jev trata dessa camada de decisão: probabilidades e saídas tipadas ainda exigem casos rotulados e fallback humano.

Recurso 2 do workflow AgentRun: controle de ramificações limita chamadas de agentes

O controle do workflow AgentRun fez exatamente o que o grafo prometia nos quatro casos de suporte: duas solicitações pararam depois da busca e de uma decisão, enquanto outras duas passaram por uma investigação limitada e uma segunda decisão. A unidade útil não é um agente autônomo, mas um caminho determinístico com um único ponto no qual um agente pode ser chamado.

Cada execução direta das fixtures terminou com o código documentado. Senha, fatura e pagamento recusado retornaram código 0. O pagamento sem solução retornou código 2 e informou que a resposta continuava insuficiente ou incerta após uma investigação. Os quatro casos gravaram zero bytes em stderr. A suíte focada em suporte do repositório também passou nos 31 testes em 2.92 segundos, incluindo envios inválidos, decisões de baixa confiança, cancelamento e erros de adapters.

Os resultados comprovam disciplina nas chamadas, não qualidade de atendimento. As respostas da busca, as decisões do Jev e as saídas de investigação eram fixtures fixas. Alterar um prompt não faz com que elas se adaptem, e nenhuma resposta é enviada a um cliente real. A conclusão demonstrada pela execução é mais estreita, porém útil: quando a primeira resposta passa, o interpretador não gasta uma chamada de agente; quando falha, libera exatamente uma investigação; se a segunda verificação também falha, o caso não escapa como concluído.

Esse é o argumento mais forte para adotar o runtime. Um loop genérico de agente pode decidir buscar novamente, revisar mais uma vez ou chamar outra ferramenta porque a conversa ainda parece inconclusa. Com AgentRun, o próprio workflow torna finito o trabalho permitido. Assim, o operador consegue inspecionar o orçamento de chamadas antes da execução, embora o host ainda precise controlar gastos com provedores e permissões de ferramentas.

Recurso 3: escalonamento fica no código, não como desejo em um prompt

AgentRun transforma o escalonamento em um estado retornado pelo runtime, acompanhado de uma justificativa, em vez de deixá-lo como uma frase perdida no prompt do agente. O workflow testado só aceita uma resposta quando a decisão é yes, a resposta atende ao contrato e a confiança chega a 0.8. Caso contrário, abre uma fila que comporta no máximo uma investigação, verifica o resultado novamente e escala o caso se o mesmo gate continuar falhando.

Para confirmar que o número realmente comandava o comportamento, as duas comparações foram elevadas de 0.8 para 0.98. A decisão roteirizada da fixture de senha permaneceu yes com 0.97. No workflow original, o caso terminou imediatamente, sem chamada de agente. Com a regra mais rígida, entrou em investigação, recebeu a mesma resposta válida, retornou outro yes com 0.97 e foi escalado depois de uma chamada de agente e duas decisões.

Essa pequena alteração mudou a ramificação sem tocar no prompt, na resposta da fixture ou no adapter. Na prática, esse é o ganho de manter a política de confiança no código. A equipe pode revisar a mudança de limiar como qualquer outra alteração de comportamento, executar casos rotulados e observar a taxa de encaminhamento resultante antes do release.

O escalonamento também permanece separado da entrega. O runtime retorna complete ou escalated; cabe ao host decidir se abre um ticket de suporte, alerta uma pessoa ou não faz nada. Essa separação impede que um documento de workflow conceda a si mesmo permissão para contatar um cliente ou alterar uma conta.

Recurso 4: a inspeção ajuda, mas a integração continua por sua conta

A inspeção do AgentRun torna o workflow legível antes que o código rode, mas não elimina o trabalho de aplicação ao redor dele. No exemplo de triagem gerado, agentrun inspect devolveu um digest do workflow, os nós judge, escalate e code, o adapter obrigatório runJudge e executableCode: true. validate retornou ok: true. dry-run também retornou ok: true, deixando claro, porém, que o caminho sintético de escalonamento havia sido ignorado.

Esse caminho ignorado importa. Um dry run verde comprova a fiação, não a cobertura das ramificações. As quatro fixtures de suporte forneceram a evidência comportamental porque exercitaram de propósito o retorno, a investigação e a revisão. Mantenha essa distinção no CI: a inspeção verifica a estrutura, a validação confere os contratos e os casos fixos testam o comportamento.

A integração depende de três adapters principais. runEffect despacha ferramentas e outros efeitos. runJudge fornece decisões tipadas, opcionalmente por meio do Jev. runNode conecta o runtime de agentes e precisa encaminhar schema, ferramentas, sinal de cancelamento e qualquer callback de revisão. O host também é responsável por autenticação, segredos, escolha de modelo, limites de turnos, orçamentos, logs, mascaramento de dados sensíveis, entrega e recibos duráveis.

O controle feito com uma função simples deixa a troca mais nítida. Seu corpo de 31 linhas usou os mesmos adapters roteirizados e reproduziu cada status e contagem de chamadas da linha de base. Para uma única rota de suporte, essa função é mais fácil de ler e entregar. As 62 linhas adicionais no arquivo de workflow do AgentRun compram um documento reutilizável, inspeção genérica, semântica compartilhada entre nós, contratos de saída, escalonamento estruturado e uma superfície que um agente de autoria pode gerar. Não compram menos código por padrão.

Essa é a mesma fronteira por trás da discussão mais ampla entre desenvolver ou comprar agentes de programação para workflows internos: adote uma infraestrutura compartilhada quando o trabalho operacional recorrente superar o custo de mantê-la.

Preço do AgentRun beta: o interpretador é grátis, o runtime não

O AgentRun beta tem um único preço de software: $0 pelo código Apache-2.0. Não existe plano pago do AgentRun nem runtime hospedado do AgentRun na beta.4. O produto é composto pelo pacote npm, código-fonte, CLI, interpretador de workflows e exemplos. A Parcha não inclui nessa licença tokens de modelos, execução de ferramentas, armazenamento, observabilidade nem suporte em produção.

Jev é um custo separado e opcional para o modelo de decisão. Conforme verificado na página ativa de modelos da TypeSafe em 24 de setembro de 2026, o Jev 1.13 custa $0.042 por milhão de tokens de entrada, e os tokens de saída são gratuitos. Partindo da premissa declarada de 500 tokens de entrada por decisão, uma verificação custa $0.000021, e duas custam $0.000042. Em 100,000 casos, essas chamadas de decisão totalizariam $2.10 ou $4.20, respectivamente.

Essa conta não inclui a investigação do agente. O AgentRun pode se conectar a qualquer runtime de agentes fornecido pelo host, portanto não existe um valor universal e honesto por caso. Um atendimento que termina após uma verificação do Jev tem perfil de custo diferente de outro que aciona agente, ferramentas, uma segunda verificação, armazenamento, logs e revisão humana. O review roteirizado não fez chamadas a modelos ao vivo, então o gasto de inferência observado foi de $0 — e sua evidência sobre custos em produção também foi zero.

Temporal mostra por que hospedagem durável é uma compra separada. O Temporal Cloud atualmente parte de $50 por milhão de ações, além do armazenamento, com $150 em créditos por 90 dias. O AgentRun não cobra essa tarifa de plataforma porque não oferece uma camada comparável de execução hospedada.

As limitações que realmente importam

As limitações do AgentRun são relevantes o bastante para que o beta entre pela porta de um workflow bem delimitado, e não vire a arquitetura padrão.

1. Os artefatos da versão discordam entre si

O manifesto publicado do pacote identifica a instalação como 0.1.0-beta.4, mas o README incluído informa Beta: 0.1.0-beta.3. O README na raiz da tag beta.4 também chama a versão de beta.3, e o changelog marca beta.4 como não lançada. A branch main atual corrige o README da raiz para beta.4, porém quem fixa a tag publicada encontra informações de status contraditórias.

Isso não quebra o interpretador, mas é relevante em um sistema de workflows no qual a proveniência da versão importa. Fixe a versão do npm, armazene o digest do workflow e registre separadamente as versões dos adapters e das políticas. Não dependa de um texto de status para reconstruir uma execução de produção.

2. A carga do host é a fronteira do produto

AgentRun entrega fluxo de controle, não um sistema de suporte pronto. Ainda são necessários ferramentas autenticadas, adapter de agente, acesso ao Jev quando usado, segredos, controle de orçamento, cancelamento, diagnósticos privados, política para dados de clientes, entrega, monitoramento e tratamento da revisão humana. Os 30.48 segundos de configuração do código-fonte não dizem nada sobre esse esforço de integração.

3. Hooks de recuperação não equivalem a execução durável

O runtime expõe interfaces de checkpoint, memo, recibo e recuperação, mas o host implementa armazenamento e reconciliação. Uma chave de idempotência ajuda a eliminar duplicatas; não garante entrega exatamente uma vez. Um efeito externo que sofreu timeout ainda pode terminar, e o host precisa verificar seu estado final antes de tentar novamente. Se recuperação após crash é o requisito principal, use Temporal. Se grafos persistentes de agentes com estado são a prioridade, avalie LangGraph.js.

4. JavaScript confiável é uma fronteira rígida de segurança

Nós de código executam JavaScript com os privilégios do processo, e a validação pode rodar probes. A flag --trusted da CLI é um reconhecimento desse fato, não um sandbox. Equipes que aceitam workflows enviados por usuários, artefatos gerados ou materiais vindos de outro domínio de confiança precisam isolá-los com limites de processo, sistema de arquivos, rede e credenciais controlados pelo host.

5. Resultados tipados ainda podem estar errados com muita confiança

O teste de schema falhou exatamente como deveria, mas não consegue detectar uma resposta ruim e bem formada. Uma decisão yes com alta confiança ainda é resultado de um modelo. O workflow precisa de casos rotulados, limiares específicos para a tarefa, monitoramento em produção e um caminho de revisão. Os 31 testes de suporte aprovados validam os cenários fornecidos, não a acurácia do Jev ao vivo.

6. As opções de plataforma e suporte são restritas

Beta.4 é uma biblioteca ESM para Node.js que requer no mínimo Node 22.19 e, para usuários de TypeScript, TypeScript 5.4. Python, execução no navegador e runtime hospedado estão fora do escopo. O beta não inclui SLA de suporte em produção, e mudanças na API ou na execução podem exigir migração entre versões beta.

7. Uma função fixa continua sendo a melhor abstração com frequência surpreendente

A função de controle de 31 linhas não é um contraexemplo de brinquedo. Ela reproduziu o workflow nos quatro casos roteirizados. Se a tarefa tem uma busca, uma condição, uma chamada opcional a agente e um encaminhamento sob responsabilidade de uma equipe, a função oferece mais localidade e menos conceitos. O AgentRun se justifica quando o próprio workflow precisa ser inspecionado, gerado, versionado, composto ou avaliado de forma independente da aplicação ao redor.

Para a adoção operacional, combine este review com um plano de evidências de falha. O guia de ferramentas para análise de falhas em agentes de IA aborda os logs e traces necessários quando o grafo do caminho feliz já não basta.

Veredito: quando o AgentRun vale a pena

AgentRun é um beta convincente para transformar a parte repetível de uma tarefa de agente em software explícito. O interpretador foi fácil de instalar, o grafo de suporte percorreu corretamente todas as ramificações limitadas, o contrato de saída falhou de forma segura e o limiar se comportou como código. O projeto é incomumente direto sobre tudo o que permanece fora da biblioteca.

O veredito, porém, depende de condições. Escolha o AgentRun apenas quando estas quatro afirmações forem verdadeiras: o workflow se repete; pelo menos uma ramificação de modelo ou agente precisa de um limite visível; mais de uma pessoa ou sistema precisa inspecionar ou gerar o workflow; e o host consegue assumir adapters, permissões, recuperação, avaliação e entrega. Se qualquer uma delas for falsa, comece com uma função TypeScript.

Use LangGraph.js quando o produto for, em essência, um grafo persistente de agentes. Use Temporal quando o workflow for, em essência, um processo distribuído durável. AgentRun ocupa o espaço entre os dois e uma função: é mais estreito que qualquer um desses runtimes, porém mais estruturado que um controle escrito à mão.

O próximo passo para segunda-feira é concreto. Pegue uma tarefa de agente existente e classifique cada etapa como código determinístico, decisão tipada, investigação de agente ou revisão humana. Se o diagrama tiver uma única linha fixa, mantenha a função. Se mostrar uma ramificação recorrente cujo gasto com agente ou política de escalonamento precisa ser revisado, codifique apenas esse caminho no AgentRun, fixe beta.4 e crie quatro fixtures antes de conectar modelos ao vivo.

FAQ sobre AgentRun