Depois dos workflows dinâmicos do Claude, por que o progresso ainda é JSON? De multiagent_20261001 a workflow_run.status_ended

Em 12 de outubro de 2026: a beta de 9 de outubro deixa um Managed Agent escrever um workflow. O progresso não é a frase final, são os eventos workflow_run. completed quer dizer que o programa terminou, não que cada thread teve sucesso.

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.

resultSentido
type completedO programa terminou. Não cada peça. Uma thread pode falhar ou nem ser criada.
type stoppedO agente parou a execução, ou a sessão foi arquivada. O evento não diz qual.
error timeout_errorA vida acabou: 24 horas, ou a mais curta que o agente definiu.
error program_errorO código falhou, uma regra foi quebrada, ou uma thread falha e o programa deixa isso encerrar a execução.
error thread_limit_errorAgentes demais para um workflow.
error unknown_errorO 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

  1. multiagent. Tipo multiagent_20261001 e workflows.type em enabled. Só workflows: subagents explicitamente disabled.
  2. Um workflow_run.created. phases está presente, os ids começam com wrph_. Um array vazio é válido. Não ponha os nomes numa allowlist.
  3. Um status_ended. Leia primeiro result.type. Depois de completed, leia ainda os eventos de cada thread.
  4. O par início e fim de fase. Una com phase_started_id. Busque o nome nas phases de 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[*].id contra workflow_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.