Os workflows dinâmicos tiram o «esperar o modelo terminar e depois analisar». O contrato de progresso continua sendo um fluxo de eventos JSON. Em 9 de outubro de 2026, o Claude Managed Agents abriu workflows dinâmicos em beta, com o cabeçalho managed-agents-2026-04-01. O agente escreve um programa. O servidor o executa em segundo plano como um workflow run. O que você acompanha não é a frase final, e sim workflow_run.* no fluxo de eventos da sessão.
Este texto vale para 12 de outubro de 2026, pela nota de lançamento e a página Workflow runs. Já cobrimos a Agents API e JSON Schema e MCP, Skills, Tools e Subagents. Aqui só importa qual JSON conta como o fim de uma execução e qual não pode ser tratado como sucesso.
O que abriu em 9 de outubro
O interruptor fica no bloco multiagent. Com o tipo multiagent_20261001, subagents e workflows ficam ligados por padrão. Só workflows: subagents em disabled. Agentes já criados vão em workflows.predefined_agents. Os que o próprio workflow escreve são agentes inline.
{
"type": "multiagent_20261001",
"workflows": { "type": "enabled" }
}
Uma execução tem três camadas: o workflow run em segundo plano (várias podem estar abertas), fases com nomes escritos pelo modelo e threads de agente. O programa pode subir vários ao mesmo tempo, passar um resultado adiante e repetir dentro de uma fase. Só o agente inicia uma execução. Nenhum evento que você envia a encerra. Arquivar a sessão pode.
Os eventos vão pelo fluxo da sessão e também aparecem na listagem. Não disparam webhooks. A vida padrão é de 24 horas; o agente pode encurtar. Esperar o cliente e as pausas contam. Uma execução pausada pode acabar com timeout_error.
created é a lista de fases
workflow_run.created traz workflow_run_id (wrun_), name, description e phases. Cada fase tem id (wrph_), name e description. Sem descrição, o campo é null. phases sempre está presente e pode ser vazio. Os nomes vêm do modelo ou do servidor. Não são um enum estável.
{
"type": "workflow_run.created",
"id": "sevt_01abc",
"workflow_run_id": "wrun_01J8XkN5uT3vHpLqRfWdY2",
"name": "Find change-of-control clauses",
"description": "Reads each contract and lists those that have the clause.",
"phases": [
{"id": "wrph_01Kd3a1f3", "name": "Read the contracts", "description": "Reads each contract for the clause."},
{"id": "wrph_01Kd3b7c9", "name": "Reconcile the findings", "description": null}
]
}
phase_started e phase_ended trazem workflow_run_phase_id e nenhum nome. O nome se busca em created.phases. phase_ended casa o início por phase_started_id e não diz se o trabalho acabou. A página diz uma fase por vez, na ordem de phases, cada uma no máximo uma vez, e também que a API não garante isso. É preciso aceitar várias fases abertas, uma fase fora da lista e uma fase listada que nunca começa. Toda fase que começa também termina, antes de status_ended.
completed não é «deu certo»
workflow_run.status_ended é sempre o último workflow_run.* daquela execução e inclui result. A execução fica aberta de created até aí, rodando ou idle.
| result | Sentido |
|---|---|
| type completed | O programa terminou. Não cada peça. Uma thread pode falhar ou nem ser criada. |
| type stopped | O agente parou a execução, ou a sessão foi arquivada. O evento não diz qual. |
| error timeout_error | A vida acabou: 24 horas, ou a mais curta que o agente definiu. |
| error program_error | O código falhou, uma regra foi quebrada, ou uma thread falha e o programa deixa isso encerrar a execução. |
| error thread_limit_error | Agentes demais para um workflow. |
| error unknown_error | O servidor não pôde continuar, ou outro limite do servidor. |
Um erro tem a forma {"type":"error","error":{"type":"timeout_error","message":"..."}}. message pode ir para o log. Um result.type desconhecido: a execução acabou de outro jeito. Um error.type desconhecido: um erro.
workflow_run.error chega antes de status_ended e não é o fim. workflow_run_id null quer dizer que nenhuma execução foi criada. Caso contrário, acompanhe até status_ended. Uma falha de modelo, MCP, credenciais ou cobrança aparece primeiro como session.error e não encerra a execução sozinha. Se o programa deixa essa falha encerrá-la, ela termina com program_error.
As threads não nomeiam a fase
Cada agente trabalha na própria thread de sessão. session.thread_created traz o workflow_run_id. As outras threads põem o campo em null. Nenhum campo diz a fase, e agent_name pode se repetir. O progresso vai pelos eventos de fase; as threads, por session_thread_id.
Um agente de predefined_agents tem id e version na thread. Um inline tem type inline e não esses campos. Ele usa o modelo do agente da sessão. Ferramentas, MCP e skills são um subconjunto; a página diz que recebe todos e também que a API não garante isso. As threads compartilham o sandbox, não o histórico.
Não dá para parar uma thread pelo id nem arquivá-la enquanto a execução está aberta. O agente precisa parar a execução inteira. Com execuções abertas, uma chamada de ferramenta pode chegar com a sessão em running. Não espere session.status_idle. Responda assim que evaluated_permission for ask.
Quatro JSON para conferir antes
- multiagent. Tipo
multiagent_20261001eworkflows.typeemenabled. Só workflows:subagentsexplicitamentedisabled. - Um workflow_run.created.
phasesestá presente, os ids começam comwrph_. Um array vazio é válido. Não ponha os nomes numa allowlist. - Um status_ended. Leia primeiro
result.type. Depois decompleted, leia ainda os eventos de cada thread. - O par início e fim de fase. Una com
phase_started_id. Busque o nome nasphasesde created.
Cruzar eventos com ferramentas locais
Antes de ligar a beta, abra três textos: o bloco multiagent, um workflow_run.created e um workflow_run.status_ended.
- Validador JSON — se cada evento é JSON válido e se você reconhece
result.type. - JSONPath —
$.phases[*].idcontraworkflow_run_phase_id. - JSON Diff — a lista de fases contra os eventos posteriores, para ver ids que não estavam na lista.
Nada sai do navegador. Leia os eventos planos e só então deixe o agente escrever. O sucesso não é só result.type == completed.
FAQ
Está disponível para todos e dá para omitir o cabeçalho beta?
Em 12 de outubro de 2026 ainda é beta. O pedido precisa de managed-agents-2026-04-01. Tipo multiagent multiagent_20261001 e workflows em enabled.
Se result.type for completed, cada peça teve sucesso?
Não. completed quer dizer que o programa terminou. Uma thread pode falhar ou nem ser criada. As falhas estão nos eventos de cada thread.
Posso parar quando chega workflow_run.error?
Não. Ele chega antes de status_ended e não é o fim. workflow_run_id null: nenhuma execução foi criada. Caso contrário, espere status_ended.
Por que phase_started não traz o nome da fase?
O nome só está em phases de workflow_run.created. Busque por workflow_run_phase_id. phase_ended casa o início por phase_started_id.
Posso enviar um evento que pare uma thread?
Não. Com a execução aberta não se para uma thread pelo id nem se arquiva. O agente precisa parar a execução inteira. Nenhum evento que você envia a encerra. Arquivar a sessão pode.
É o mesmo JSON de um tools/list do MCP?
Não. tools/list é a descoberta de ferramentas. Este contrato são os eventos workflow_run. As ferramentas de um agente inline são um subconjunto, não um segundo tools/list.
Resumo
Os workflows dinâmicos transformam centenas de documentos num programa em segundo plano. O progresso continua sendo eventos JSON. A beta de 9 de outubro abre com multiagent_20261001. created lista as fases. status_ended é o fim. completed não significa que cada thread teve sucesso. Um evento error espera o fim seguinte. Os nomes de fase não estão nos eventos de fase.
Deixe planos multiagent, created e status_ended no local antes de deixar o agente escrever. O sucesso não deve encolher para um único completed.