Agentes Que Escrevem Programas Para Orquestrar Outros Agentes: Como Funcionam Os Dynamic Workflows Do Managed Agents

Em sistema multiagente, a parte que mais dá trabalho costuma não ser o prompt de nenhum agente, e sim o grafo. Quem chama quem, em que ordem, o que acontece quando o terceiro de cinco falha, onde os resultados se juntam. Esse desenho vive em código que alguém do time escreveu, revisou e consegue ler antes de rodar. Tem uma virtude: se alguém pergunta "o que esse sistema vai fazer?", existe um arquivo para abrir.

Foi isso que me veio à cabeça ao ler a documentação dos dynamic workflows do Managed Agents, que a Anthropic registrou nas notas de versão em 9 de outubro. A ideia, resumida sem adjetivos: em vez de o desenvolvedor desenhar o grafo, o agente escreve um programa que coordena muitos agentes em fases e combina o que eles devolvem. O desenvolvedor descreve o trabalho; o fluxo é decidido em tempo de execução. A sensação que isso me provocou foi uma mistura de interesse e desconforto, e acho que os dois são razoáveis.

Já escrevi aqui sobre o Managed Agents comparado ao que Google e OpenAI preparam e sobre a estratégia de rodar agente na nuvem ou na sua máquina, então não vou explicar de novo o que é o produto. Este post é sobre outra coisa: o modelo de programação. Um aviso importante: o recurso está em beta, atrás do header managed-agents-2026-04-01, e o que escrevo vem da leitura da documentação, não de uso em produção. Eu não rodei um workflow run e não medi custo de nenhum.

Vou passar pelo que a documentação define e como um run começa, pelos eventos que permitem acompanhá-lo, pelos limites e o que cada um impõe ao desenho, por custo e orçamento, por falhas e cancelamento, pela escolha entre workflow e subagentes e, no fim, pelas perguntas que a documentação lida simplesmente não responde.

O Que A Documentação Define E Como Um Run Começa

A terminologia importa porque são duas coisas diferentes. O "workflow" é o programa que o agente escreve: ele roda muitos agentes em fases e combina o que eles devolvem. O "workflow run" é a execução desse programa, que o servidor conduz em segundo plano. O agente que pediu pode continuar trabalhando ou encerrar o turno enquanto o run avança. Como contexto e resultados passam programaticamente entre os agentes, a thread principal fica livre para conversar com o usuário e acompanhar um ou mais runs.

Cada agente de um run trabalha na própria thread de sessão. Essas threads podem ser listadas, lidas e transmitidas, o que é bom para auditoria. Duas restrições moldam o uso: o agente não pode mandar mensagens de acompanhamento a threads de run, e o servidor arquiva cada thread ao fim do run. Você dispara, espera, lê o que sobrou.

Para habilitar, os dynamic workflows fazem parte do tipo multiagent_20261001 e vêm ligados por padrão com ele. A configuração do agente fica assim:

{
  "multiagent": {
    "type": "multiagent_20261001",
    "workflows": { "type": "enabled" }
  }
}

Para desligar, "workflows": {"type": "disabled"}. Para permitir apenas workflows e nenhuma delegação a subagentes, "subagents": {"type": "disabled"}. A sessão copia a configuração na criação, então alterar o agente depois não afeta sessões existentes.

O ponto que mais me chamou atenção é como um run começa: não existe chamada de API separada. Você descreve o trabalho numa user.message e o agente decide se e quando iniciar um run. Sua influência é indireta, pela mensagem ou pelo prompt de sistema. A documentação traz um exemplo de prompt para um agente que revisa contratos, que traduzo livremente: "Você revisa contratos. Quando pedirem para revisar mais do que alguns contratos, inicie um workflow run que lê todos em paralelo e combina os achados. Revise um ou dois contratos você mesmo, sem run." Note o desenho da decisão: o limiar entre fazer sozinho e abrir um run está escrito em linguagem natural, e quem o aplica é o modelo.

As políticas de permissão se aplicam às ferramentas que os agentes do run chamam, não ao início do run. Logo, "o agente pode abrir um run?" não se controla por permissão de ferramenta; a chave é desabilitar workflows.

Fases E Eventos: O Que Dá Para Observar

Se o desenvolvedor não vê o grafo antes de rodar, a observabilidade durante e depois vira o substituto. A documentação descreve um ciclo de vida simples: o run alterna entre running e idle e termina em ended. Cada transição aparece como evento no stream da sessão: workflow_run.created, status_running, status_idle, phase_started, phase_ended, status_ended e workflow_run.error. O primeiro carrega o workflow_run_id (no formato wrun_…), o nome, a descrição e as fases. No exemplo da documentação para o revisor de contratos, as fases se chamam "Read the contracts" e "Reconcile the findings".

Isso responde parte da pergunta de confiança: você não vê o programa antes, mas vê no created as fases declaradas e acompanha a entrada e a saída de cada uma, um mapa grosso do plano. Não é o código do workflow, e a documentação lida não diz que ele seja exposto.

Dois detalhes operacionais. Primeiro, esses eventos não disparam webhooks; eles vivem no stream da sessão. Segundo, depois de reconectar, o stream não reapresenta eventos perdidos, então quem monitora precisa listar os eventos da sessão com filtro de tipos para recuperar o que passou. E não há endpoint para listar runs: o histórico de eventos é a fonte. Na prática, quem opera isso precisa de um consumidor que persista os eventos workflow_run.* e reconstrua o estado a partir deles. Um esqueleto ilustrativo, abreviado e sem pretensão de ser a assinatura exata do SDK:

# Ilustrativo, não é a assinatura exata do SDK.
runs = {}

def on_event(ev):
    t = ev["type"]
    if not t.startswith("workflow_run."):
        return
    rid = ev.get("workflow_run_id")
    r = runs.setdefault(rid, {"phases": [], "status": None})
    if t == "workflow_run.created":
        r["name"] = ev.get("name")
        r["declared_phases"] = ev.get("phases")
    elif t == "workflow_run.phase_started":
        r["phases"].append(ev.get("phase"))
    elif t == "workflow_run.status_ended":
        r["result"] = ev.get("result")   # completed | stopped | error
    elif t == "workflow_run.error":
        r["error"] = ev   # ex.: max_workflow_runs_error

Repare que o result chega em status_ended, mas, como veremos, ele diz pouco sobre se o trabalho deu certo. A observabilidade por thread complementa: dá para listar as threads de um run pelo workflow_run_id e ler os eventos de cada uma. Isso é o que permite, por exemplo, achar o agente que não conseguiu ler um dos contratos.

Limites E O Que Cada Um Impõe Ao Desenho

Programa que o próprio agente escreve precisa de cercas, e a documentação as dá em números. Reuni os que li nas páginas de dynamic workflows e de workflow runs numa tabela, com o que cada um significa para quem desenha.

Imagine, como cenário hipotético, um time que revisa 300 contratos. Com 64 threads simultâneas, o run processa em ondas, e a latência total tem um piso dado pela duração de cada leitura vezes o número de ondas. Se cada contrato exige várias chamadas longas, o teto de 24 horas deixa de ser abstrato.

O limite de 1.000 agentes iniciados é o que mais pesa no desenho. Ele conta agentes ao longo da vida do workflow, e a documentação avisa que agentes que falham podem ser retentados em novas threads, de modo que o número de threads pode passar de 1.000. Numa migração com milhares de arquivos, "um agente por arquivo" não fecha; alguém precisa agrupar, e quem decide é o workflow, isto é, o agente. Daí a utilidade de instruir o run: a documentação sugere orientações como "num run, use um agente por contrato" e "dê ao run um limite de uma hora". Esta última, atenção, é uma instrução ao agente, não um limite imposto pela plataforma. O limite imposto é o das 24 horas.

Há ainda restrições de composição: a delegação tem um nível de profundidade, todos os agentes precisam fixar o mesmo model.inference_geo ou nenhum fixar, e o prefixo ant__ é reservado (uma ferramenta custom com esse nome faz toda atualização do agente falhar até ser renomeada). Vale checar antes de subir a configuração.

Custo E Orçamento: Cada Agente Do Run Consome Tokens

A frase da documentação que mais importa para quem aprova orçamento é quase banal: um run não tem preço separado. Os tokens são cobrados como em qualquer sessão, ao preço de cada modelo. O que muda é a multiplicação. Em um agente único, o custo cresce com o tamanho da conversa. Em um run, cada agente tem contexto, prompt de sistema e chamadas de ferramenta próprios, e todos consomem. Revisar 40 contratos com um agente por contrato significa pelo menos 40 contextos, mais os agentes que reconciliam, mais as retentativas. A gestão de tokens em produção que discuti em julho continua sendo o ponto de partida, só que agora o número de contextos abertos é decidido em tempo de execução.

O mecanismo de proteção é o orçamento de sessão, definido na criação da sessão. A documentação é explícita: não dá para acrescentar orçamento a uma sessão existente. Quando o orçamento é atingido, todos os runs abertos pausam, a sessão fica idle com stop_reason budget_reached, e eles retomam quando o orçamento é aumentado ou removido. Há uma ressalva que um tech lead precisa ler duas vezes: as threads terminam as requisições em andamento, então um run pode ultrapassar o orçamento em uma requisição por thread ativa. Com até 64 threads em paralelo, isso não é desprezível, e a documentação não dá valor em dinheiro.

Modelos sem preço de lista bloqueiam a continuação por orçamento, e remover o orçamento é a única opção. Já os workflows.predefined_agents (até 20, vazio por padrão) são agentes já criados, com modelo, prompt e ferramentas próprios, e servem, segundo a documentação, para rodar parte dos agentes em outro modelo. É a alavanca de custo mais óbvia: deixar o modelo caro para a reconciliação e um mais barato para a leitura em massa. Já os agentes inline (workflows.inline_agents, ligados por padrão) são definidos pelo próprio workflow, que escreve o prompt de sistema de cada um, e usam o modelo, as ferramentas, os servidores MCP e as skills do agente da sessão. Ou seja, por padrão, todo agente do run roda no modelo da sessão.

Para medir o que um run consumiu, a documentação indica um caminho manual: listar as threads da sessão, filtrar por workflow_run_id e somar o campo usage, incluindo threads arquivadas e terminadas, pulando usage nulo. Não vi um agregado pronto por run. Para FinOps, o relatório de custo por run é algo que o seu time monta; o preço de cada modelo está na página de preços da Anthropic. Sem uso real, não estimo quanto um run típico custa, e desconfio de quem estime sem ter rodado.

Falhas, Cancelamento E Idempotência

O resultado de um run pode ser completed, stopped ou error, e o erro vem com um tipo: timeout_error, program_error, thread_limit_error ou unknown_error. A frase mais importante de toda a documentação, na minha leitura, é esta: completed significa que o workflow terminou, e não que o trabalho passou. É preciso verificar os eventos de cada thread em busca de falhas. Pense no revisor de contratos: o programa pode terminar normalmente com 37 contratos lidos e 3 que o agente não conseguiu abrir. Para o sistema, é completed.

Isso conversa com o que escrevi sobre agentes que falham em silêncio e entregam resposta confiante e errada. A diferença é que aqui o status verde é do orquestrador, não do agente. A documentação oferece um antídoto de prompt: instruir o run com algo como "uma falha de agente não deve falhar o run; se um agente não conseguir ler um contrato, liste-o como não coberto". Mas, de novo, é instrução que o agente segue, não regra que a plataforma impõe. Se o seu processo depende de cobertura completa, a checagem final deve ser sua: contar o que entrou, contar o que saiu, e tratar a diferença como incidente.

Cancelamento é o outro ponto sensível. Não há endpoint para cancelar um run por ID. O user.interrupt para o turno do agente, mas não encerra runs; runs pausados podem ficar pausados com o tempo de vida correndo. Para parar, há dois caminhos. O primeiro é pedir ao agente por user.message, e o run termina com {"type":"stopped"}; enquanto a sessão está idle com budget_reached, esse pedido retorna 400 até o orçamento ser aumentado ou removido. O segundo é arquivar a sessão, que encerra cada run aberto com stopped, embora possa retornar 400 workflow_run_open enquanto houver run aberto. Há mais amarras com run aberto: não dá para arquivar uma thread do run nem atualizar o agent da sessão.

Na prática, o "botão de parar" depende da cooperação do agente ou da destruição da sessão inteira. Um runbook razoável decide de antemão qual dos dois usar e deixa o orçamento de sessão como rede de segurança. Os padrões que discuti sobre operação de agentes em produção valem aqui: o desenho do desligamento deve existir antes do primeiro deploy.

Por fim, a idempotência. A documentação avisa que um run pode criar mais de uma thread para o mesmo trabalho, por retentativa, e que as requisições de modelo do run contam nos limites normais de taxa da Messages API. Uma thread que sofre rate limit recebe session.error na própria stream. Se uma ferramenta envia e-mail, cria ticket ou grava em banco, ela pode ser chamada duas vezes para o mesmo contrato. A recomendação é direta: ferramentas que os agentes de um run usam devem ser idempotentes, com chave de operação derivada do item de trabalho, não da thread.

Workflow Ou Subagentes: Quando Cada Um

A documentação traz uma comparação que eu resumiria assim. Workflows fazem sentido quando o trabalho tem muitas peças, pede paralelismo ou deve terminar mais rápido, como auditorias, migrações, pesquisa profunda e checagem cruzada. Também quando você quer a thread principal livre e não precisa mandar mensagens a agentes individuais no meio da tarefa. Subagentes fazem sentido quando o agente deve fazer acompanhamento depois que o subagente reporta, quando você precisa de especialistas nomeados com prompts e ferramentas próprios, ou quando o agente precisa mandar mensagens a um subagente específico.

Eu leio essa fronteira como uma pergunta sobre conversa. Subagente é um interlocutor: você pergunta, ele responde, você refina. Run é terceirização em lote: você entrega a lista e volta quando terminar. Se a tarefa tem a forma "para cada item, faça X e me devolva Y", o workflow é natural. Se é "investigue, me diga o que achou, e então decido o próximo passo", o subagente preserva o laço de decisão.

A segunda dimensão é o controle do desenho. Com subagentes, quem lê a configuração enxerga os especialistas, seus prompts e suas ferramentas. Com workflow e agentes inline, o prompt de cada agente é escrito pelo workflow, e há uma limitação que a documentação declara: o MCP é escopado por definição de agente e os agentes inline usam os servidores MCP do agente da sessão, sem como restringir o MCP de um inline agent. Para restringir, desabilite inline_agents ({"type":"disabled"}) e liste pelo menos um agente predefinido, senão a API responde 400. As entradas ficam fixadas na versão resolvida na criação ou atualização. Também vale lembrar que vault_ids valem para todas as threads da sessão. Em outras palavras, a configuração mais conservadora é a dos predefinidos: você recupera um pedaço do grafo estático, em troca de perder a liberdade de o agente inventar papéis.

De passagem: o Claude Code 2.1.296, de 10 de outubro, adicionou CLAUDE_CODE_WORKFLOW_SUBAGENT_MODEL e autoCompactWindow para subagentes, segundo as notas de versão; não há relação documentada com o Managed Agents. E o tipo antigo coordinator não inicia runs nem define subagentes: migrar para multiagent_20261001 exige atualizar com um bloco multiagent completo.

O Que A Documentação Não Responde

Sobre a pergunta que mais me intriga, a documentação que li é silenciosa: em que linguagem o agente escreve o workflow, e como é esse programa. Não sei se é código, uma descrição declarativa ou outra coisa, e portanto não consigo dizer o que ele pode ou não pode fazer além do que as páginas descrevem. Também não encontrei dados de desempenho, nem latência típica, nem ganho de tempo frente a uma execução sequencial. O preço de execução, como visto, não é separado, e não há estimativa de quantos tokens um run típico gasta.

Outra lacuna é o resultado. A documentação lida não descreve um endpoint dedicado para buscá-lo. Dá para listar as threads de um run e ler seus eventos, mas não se vê o que cada thread devolveu ao workflow, e o result de status_ended diz como o run terminou, não o conteúdo combinado. Suponho que o agente da sessão entregue o produto final na thread principal, mas isso é inferência minha, não está na página.

E há a pergunta de confiança, que a documentação não tem como responder por mim. O desenvolvedor deixa de ver o grafo antes de rodar. Recupera visibilidade por fases declaradas, eventos e threads auditáveis depois, e por orçamento, limites e predefinidos como cercas. Se isso basta depende do risco do trabalho. Em pesquisa, onde o pior caso é refazer, parece aceitável. Em migração com escrita em sistemas reais, eu exigiria predefinidos, ferramentas idempotentes e etapa humana antes de aplicar qualquer coisa.

Conclusão

O que me parece genuinamente novo nos dynamic workflows é a transferência de uma decisão de arquitetura, o formato do fluxo, do código do time para o tempo de execução. O que não muda é tudo o que sempre foi trabalho de engenharia: limitar o raio de dano, medir custo, tratar falha parcial, ter um jeito de parar. A documentação entrega bons instrumentos para isso, como eventos por fase, threads auditáveis, orçamento de sessão e limites explícitos. Mas várias garantias, como o limite de uma hora ou a política de falhas, são instruções ao agente, e não regras do sistema.

Se eu estivesse avaliando para um time, começaria por um cenário de baixo risco e só leitura, com agentes predefinidos, orçamento de sessão baixo, um consumidor que guarde os eventos workflow_run.* e verificação própria de cobertura. Mediria o usage das threads antes de qualquer conversa sobre escala. E trataria o completed como o que ele é: um sinal de que o programa acabou, não de que o trabalho está certo.

Fico com incerteza honesta. É um recurso em beta, descrito por uma documentação que cala sobre a linguagem do workflow, o desempenho e o custo típico. Minha leitura é que ele resolve bem os trabalhos com muitas peças e mal os trabalhos que pedem conversa. Quanto à confiança em um fluxo que ninguém desenhou, acho que ela vai ser construída do jeito de sempre: rodando, observando, errando em ambiente seguro e ajustando as cercas.

Fontes:

• Anthropic — Dynamic workflows (Managed Agents)
• Anthropic — Workflow runs (Managed Agents)
• Anthropic — Release notes
• Anthropic — Pricing