Execuções de workflow

Um "workflow" (fluxo de trabalho) é um programa que um agente escreve para executar muitos agentes e combinar o que eles retornam. Uma "workflow run" (execução de workflow) é a execução de um workflow. Workflows dinâmicos é o recurso que permite que um agente escreva workflows e inicie execuções. Você o ativa ou desativa com a configuração workflows no bloco multiagent do agente.

O servidor executa um workflow em segundo plano. Seus agentes trabalham em threads de sessão que o servidor cria conforme o workflow precisa delas. Você acompanha as execuções no fluxo de eventos da sessão. Somente o agente inicia uma execução. Nenhum evento que você envia encerra uma; arquivar a sessão pode encerrá-la.

Como os workflows dinâmicos funcionam

O agente que a sessão executa escreve cada workflow para o trabalho que você descreve. Um workflow é um programa: ele executa outros agentes, coleta o que cada um retorna e combina os resultados. Dessa forma, o agente pode assumir uma tarefa grande demais para uma única conversa, como a revisão de centenas de documentos. Durante uma execução, o agente pode continuar trabalhando ou encerrar seu turno, e pode verificar o andamento da execução.

O diagrama mostra um exemplo. Cada workflow que o agente escreve tem suas próprias fases e agentes. Uma execução tem estas camadas:

• Execução de workflow: O servidor executa o workflow em segundo plano, como uma execução de workflow. Uma sessão pode ter várias execuções abertas ao mesmo tempo.
• Fases: Um workflow pode dividir seu trabalho em fases. Uma fase é uma etapa nomeada da execução, como "Read the contracts" (Ler os contratos). Você acompanha o progresso de uma execução pelos seus eventos de fase.
• Threads de agente: Em uma fase, o programa executa agentes. Cada agente trabalha em sua própria thread de sessão, com um prompt que o programa escreveu. Um agente em uma execução pode ser um agente inline, que o próprio programa define, ou um agente predefinido, que você lista em workflows.predefined_agents. Para saber o que cada thread mostra, consulte As threads de uma execução.

O programa pode fazer o seguinte:

• Executar agentes ao mesmo tempo: O programa pode executar muitos agentes ao mesmo tempo, o que é chamado de "fanning out" (distribuição em leque). No diagrama, três agentes leem contratos na primeira fase.
• Passar resultados de um agente para outro: Cada agente retorna seu resultado ao programa. O programa pode passar esse resultado para outro agente. No diagrama, o agente da segunda fase trabalha com o que os três primeiros retornaram. Os agentes de uma execução também trabalham com os mesmos arquivos, no sandbox da sessão.
• Dar o próximo passo sozinho: O resultado de um agente vai para o programa, não para o agente que a sessão executa. O programa determina quais agentes são executados em seguida e escreve seus prompts.
• Repetir e escolher: Dentro de uma fase, o programa pode repetir trabalho e escolher seu próximo passo com base no que um agente retornou. Por exemplo, ele pode fazer com que um rascunho seja revisado até que uma revisão seja aprovada ou que um número definido de rodadas se esgote. No diagrama, o programa pode repetir uma etapa dentro da segunda fase.
• Lidar com um agente que falhou: Quando um de seus agentes falha, o programa pode tratar a falha ou deixar que ela encerre a execução.

Quando a execução termina, o agente que a sessão executa recebe um turno para ler o que a execução fez. Ele pode então responder a você ou iniciar outra execução. Eventos de execução lista os casos em que esse turno vem mais tarde ou não vem.

Você pode orientar como uma execução realiza o trabalho, por exemplo, como ela divide o trabalho e o que faz quando um agente falha. Consulte Informar ao agente quando usar uma execução.

Como uma execução passa por seus estados

Uma execução começa como em execução ou como ociosa. Atingir o orçamento, por exemplo, pausa uma execução em andamento, o que a torna ociosa; aumentar ou remover o orçamento faz com que ela volte a ser executada, a menos que uma interrupção também a tenha pausado. Uma execução em andamento termina quando seu workflow é concluído, o agente a para, ela falha, seu tempo de vida se esgota ou a sessão é arquivada. Uma execução ociosa também pode terminar, por exemplo, quando o agente a para ou a sessão é arquivada.

Uma execução está aberta desde seu evento workflow_run.created até seu evento workflow_run.status_ended, esteja ela em execução ou ociosa. Uma execução fica ociosa enquanto está pausada, por exemplo, no orçamento da sessão. O tempo de vida de uma execução é de 24 horas por padrão. O agente pode definir um tempo de vida menor ao iniciar a execução. O tempo que uma execução passa esperando pelo seu cliente conta para esse tempo de vida. Uma pausa não impede que o tempo de vida de uma execução se esgote, então uma execução que permanece pausada pode terminar com timeout_error. Os eventos a seguir informam o início de uma execução, suas fases e seu fim. Uma pausa no orçamento também envia um. Uma pausa após uma interrupção pode não enviar nenhum. Todo evento workflow_run.* inclui workflow_run_id, que é null apenas em um workflow_run.error quando nenhuma execução foi criada.

Eventos de execução

Os eventos de execução chegam no fluxo de eventos da sessão, que é o fluxo da thread principal, e listar os eventos da sessão também os retorna. Os eventos de execução não acionam webhooks. Os eventos de status das threads da execução chegam no mesmo fluxo. Cada um nomeia sua thread em session_thread_id, e as threads de uma execução são aquelas cujo evento session.thread_created tinha o workflow_run_id da execução.

Um resultado de erro tem a forma {"type": "error", "error": {"type": "timeout_error", "message": "..."}}, em que é seguro registrar message em log. Trate um result.type não reconhecido como uma execução que terminou de alguma outra forma, e um error.type não reconhecido como um erro. Quando algo de que a sessão depende falha, como o modelo, um servidor MCP, credenciais ou cobrança, o fluxo da thread que falhou recebe um session.error. Isso não encerra uma execução por si só. Mas, se fizer com que uma das threads da execução falhe, e o workflow deixar que isso encerre a execução, a execução termina com program_error.

Por exemplo, você pergunta ao agente de revisão de contratos quais de 300 contratos têm uma cláusula de mudança de controle, e o agente inicia uma execução:

1. workflow_run.created nomeia a execução como "Find change-of-control clauses" e lista as fases "Read the contracts" e "Reconcile the findings" em phases. Em seguida, vem workflow_run.status_running.
2. Eventos de fase marcam cada fase, e cada thread que a execução cria envia session.thread_created com o workflow_run_id da execução.
3. workflow_run.status_ended chega com result: {"type": "completed"}.
4. O agente responde "41 dos 300 contratos têm uma", e session.status_idle chega com end_turn.

O primeiro evento da execução lista suas fases:

{
  "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 }
  ],
  "processed_at": "2026-10-09T14:01:45Z"
}

Cada evento de fase nomeia sua fase por workflow_run_phase_id. Esse é um id em phases, mas a API não garante isso:

{
  "type": "workflow_run.phase_started",
  "id": "sevt_01def...",
  "workflow_run_id": "wrun_01J8XkN5uT3vHpLqRfWdY2",
  "workflow_run_phase_id": "wrph_01Kd3a1f3",
  "processed_at": "2026-10-09T14:01:46Z"
}

O último evento da execução informa como ela terminou:

{
  "type": "workflow_run.status_ended",
  "id": "sevt_01ghi...",
  "workflow_run_id": "wrun_01J8XkN5uT3vHpLqRfWdY2",
  "result": { "type": "completed" },
  "processed_at": "2026-10-09T14:09:12Z"
}

As threads de uma execução

Cada agente em uma execução trabalha em sua própria thread de sessão, que o servidor cria conforme o workflow precisa dela. Você pode listar, ler e fazer streaming das threads de uma execução como qualquer thread filha, e responder às suas chamadas de ferramenta a partir do fluxo principal. Para fazê-las parar, peça ao agente que pare a execução (consulte Interromper uma sessão com execuções abertas). Você não pode parar uma pelo seu ID, nem arquivar uma enquanto sua execução estiver aberta.

• Agrupamento: A thread de uma execução carrega o workflow_run_id da execução, assim como o evento session.thread_created que a anuncia. Outras threads, e os eventos session.thread_created que as anunciam, têm workflow_run_id definido como null.
• Agente: agent mostra o agente que a thread executa. Para um agente que você listou em multiagent.workflows.predefined_agents, agent tem o id e a version desse agente, como na thread de um subagente que você listou. Para um agente que o workflow define (um agente inline), agent tem type inline e nenhum id ou version. Ele tem o prompt do sistema que o workflow escreveu, não o do agente da sessão. Ele também tem o nome e a descrição que o workflow lhe deu; o servidor atribui um nome se o workflow não tiver dado nenhum. Ele usa o modelo do agente da sessão, o agente que a sessão executa. Suas ferramentas, servidores MCP e skills são um subconjunto dos do agente da sessão. Ele recebe todos eles, mas a API não garante isso. Suas ferramentas mantêm suas políticas de permissão.
• O que as threads compartilham: As threads de uma execução trabalham no sandbox da sessão, então todas as threads trabalham com os mesmos arquivos. Isso inclui os arquivos de um memory store que a sessão monta. Um agente que o workflow define usa seus servidores MCP com as credenciais que a sessão resolve para eles. Cada thread tem seu próprio histórico de conversa.
• Eventos: Os eventos session.thread_created, session.thread_status_running, session.thread_status_idle e session.thread_status_terminated de uma thread de execução também chegam no fluxo principal (consulte Eventos de execução). Seus eventos de mensagem permanecem em seu próprio fluxo. Seus webhooks de thread são enviados como para qualquer thread filha. Para saber o que o próprio fluxo da thread registra, consulte Eventos de thread de sessão.
• Fases: Nenhum evento ou campo diz em qual fase uma thread trabalha, e threads de uma mesma execução podem ter o mesmo agent_name. Acompanhe o progresso de uma execução pelos seus eventos de fase e diferencie suas threads por session_thread_id.
• Limite de threads: As threads de uma execução estão isentas do limite de threads filhas da sessão.
• Iniciar execuções: Somente o agente na thread principal da sessão inicia execuções. Um agente trabalhando na thread de uma execução não pode iniciar uma execução própria, então as execuções não se aninham.
• Arquivamento: O servidor arquiva cada thread no máximo até o fim de sua execução. Ele pode arquivar uma antes, assim que a thread retorna seu resultado ou a execução termina de usá-la. Se a thread ainda estiver em execução ou esperando pelo seu cliente nesse momento, o servidor a para primeiro. Uma thread arquivada permanece na lista de threads, com status terminated. Você não precisa arquivar as threads de uma execução por conta própria. Enquanto a execução estiver aberta, uma solicitação para arquivar uma que o servidor ainda não arquivou retorna 400 com error.details.error_code: "workflow_run_open".
• Visibilidade: Você não vê o código do workflow, mas pode pedir o workflow ao agente, como descreve a dica após esta lista. Você também não vê as chamadas de ferramenta que o agente faz para iniciar e gerenciar execuções, nem o resultado que cada thread retorna ao workflow.

Saiba quando o trabalho está concluído

Enquanto uma execução estiver em andamento, espere que a sessão permaneça running, mesmo enquanto nenhuma de suas threads estiver trabalhando. Ela fica idle com requires_action quando nenhuma thread está trabalhando e uma thread espera pelo seu cliente. Um idle por si só não significa que o trabalho está concluído. O trabalho está concluído quando ambas as condições são verdadeiras:

1. Toda execução que você viu ser criada tem seu workflow_run.status_ended.
2. Depois disso, chega um session.status_idle com stop_reason end_turn, e não foi sua própria solicitação, como uma interrupção, que o causou. Depois de interromper, conte apenas um idle que venha após sua próxima user.message ou user.define_outcome.

• Execuções pausadas: Uma execução pausada não mantém a sessão running, então a sessão pode ficar ociosa enquanto a execução ainda está aberta. No orçamento, por exemplo, a sessão fica ociosa com budget_reached. O trabalho não está concluído até que a execução termine.
• Outra execução: O agente pode iniciar uma nova execução ao ler um resultado, então verifique novamente.
• "Outcomes" (resultados): Se você definiu um resultado, nenhuma avaliação começa enquanto uma execução estiver aberta, esteja ela em execução ou ociosa. O turno em que o agente lê o resultado da execução pode iniciar uma.
• retries_exhausted: O turno do agente falhou por um erro: as novas tentativas se esgotaram, ou o erro não pode ser tentado novamente, como uma falha de cobrança. Uma execução ainda pode estar em andamento quando esse idle chega. Se uma execução terminou e o agente ainda não leu seu resultado, o servidor inicia um novo turno sem nenhuma entrada sua. A sessão volta a ficar running, então espere pelo próximo idle. Se a sessão permanecer ociosa, leia o session.error que veio antes dele e corrija a causa. Em seguida, envie uma user.message ou leia o result de cada execução você mesmo.

Acompanhar uma execução

Este exemplo acompanha uma sessão desde a sua mensagem até a resposta do agente. Ele abre o fluxo e envia a mensagem. Em seguida, faz o seguinte:

• Acompanha cada execução desde seu workflow_run.created até seu workflow_run.status_ended, e imprime cada fase quando ela começa.
• Responde a chamadas de ferramentas personalizadas quando cada agent.custom_tool_use chega, porque a thread de uma execução pode esperar pelo seu cliente enquanto a sessão permanece running. Se as ferramentas do seu agente pedem confirmação, adicione um ramo que responda a cada agent.tool_use ou agent.mcp_tool_use cujo evaluated_permission seja ask. O exemplo não tem nenhum, porque um ramo que permite todas as chamadas transformaria always_ask em sempre permitir.
• Para quando o trabalho está concluído: nenhuma execução está aberta e a sessão fica ociosa com end_turn. Ele também para se a sessão for encerrada. Em um idle com qualquer outro motivo de parada exceto requires_action, como budget_reached, retries_exhausted ou refusal, ele imprime o motivo e para, então trate esses casos no seu próprio código. Ele para em retries_exhausted mesmo quando o servidor está prestes a iniciar um novo turno por conta própria. Ele continua esperando em requires_action, e em end_turn enquanto uma execução estiver aberta.

open_runs: dict[str, str] = {}  # workflow_run_id -> run name
phase_names: dict[tuple[str, str], str] = {}  # (run ID, phase ID) -> phase name

# Abra o stream primeiro e depois envie a mensagem do usuário
with client.beta.sessions.events.stream(session_id) as stream:
    client.beta.sessions.events.send(
        session_id,
        events=[
            {
                "type": "user.message",
                "content": [
                    {
                        "type": "text",
                        "text": "Which contracts in /contracts have a change-of-control clause?",
                    },
                ],
            },
        ],
    )

    for event in stream:
        match event.type:
            case "workflow_run.created":
                open_runs[event.workflow_run_id] = event.name
                for phase in event.phases:
                    phase_names[event.workflow_run_id, phase.id] = phase.name
                print(f"Run started: {event.name}")
            case "workflow_run.phase_started":
                phase_id = event.workflow_run_phase_id
                key = (event.workflow_run_id, phase_id)
                print(f"  Phase: {phase_names.get(key, phase_id)}")
            case "workflow_run.status_ended":
                name = open_runs.pop(event.workflow_run_id, event.workflow_run_id)
                print(f"Run ended: {name} ({event.result.type})")
            case "agent.custom_tool_use":
                # Responda quando o evento chegar. A thread de uma execução pode aguardar seu
                # cliente enquanto a sessão continua em execução.
                result = call_tool(event.name, event.input)
                try:
                    client.beta.sessions.events.send(
                        session_id,
                        events=[
                            {
                                "type": "user.custom_tool_result",
                                "custom_tool_use_id": event.id,
                                "content": [{"type": "text", "text": result}],
                            },
                        ],
                    )
                except anthropic.BadRequestError as error:
                    # O servidor recusa um resultado que chega tarde demais, depois de
                    # arquivar a thread da chamada. Continue acompanhando a execução.
                    print(f"  Answer to {event.name} refused: {error.message}")
            case "session.status_idle":
                # Concluído quando todas as execuções terminarem e o agente tiver finalizado seu turno
                if not open_runs and event.stop_reason.type == "end_turn":
                    break
                # Um idle com requires_action aguarda seu cliente, então continue lendo.
                # Em qualquer outro motivo de parada, imprima-o e pare.
                if event.stop_reason.type not in ("end_turn", "requires_action"):
                    print(f"Session idle: {event.stop_reason.type}")
                    break
            case "session.status_terminated":
                break

Interromper uma sessão com execuções abertas

Envie user.interrupt sem session_thread_id, ou com o ID da thread principal. Isso interrompe o turno do agente. Não encerra nenhuma execução. As execuções da sessão podem pausar ou continuar em andamento, e seus eventos podem não mostrar qual dos dois. O tempo de vida de uma execução pausada continua passando, então a execução pode terminar com timeout_error enquanto está pausada.

• Chamadas de ferramenta em espera: Após a interrupção, a chamada de ferramenta de uma thread de execução ainda pode estar esperando pelo seu cliente. Responda a cada uma. Para cancelar uma chamada que pede confirmação, negue-a. Para cancelar uma chamada de ferramenta personalizada, envie um resultado com is_error definido como true e um texto em content que explique o motivo. Enquanto a sessão estiver idle com requires_action, uma user.message retorna 400, então responda às chamadas primeiro.
• Para parar as execuções: Envie uma user.message pedindo ao agente que pare suas execuções. Uma execução parada termina com result {"type": "stopped"}. Enquanto a sessão estiver idle com budget_reached, uma user.message retorna 400 até que você aumente ou remova o orçamento. Aumentá-lo ou removê-lo também retoma as execuções que o orçamento pausou, a menos que a interrupção também as tenha pausado.
• Para continuar: Envie uma user.message pedindo ao agente que continue suas execuções. Após uma interrupção, as execuções podem esperar por essa mensagem. Se a sessão estiver idle com budget_reached, aumente ou remova o orçamento primeiro.
• Resultados das execuções: Uma execução que termina após a interrupção ainda envia workflow_run.status_ended.

Enquanto uma execução está aberta

Reconstruir o estado da execução após reconectar

Reconstrua o estado de cada execução a partir dos eventos da sessão. O fluxo não reproduz o que você perdeu: uma nova conexão entrega apenas eventos emitidos depois que ela foi aberta. Então liste os eventos com um filtro types, uma entrada types[] para cada tipo de evento, como em Listar eventos anteriores. Passe o next_page de cada resposta como page até que next_page seja null ou esteja ausente. workflow_run.created, workflow_run.status_running, workflow_run.status_idle e workflow_run.status_ended fornecem o estado de cada execução, exceto que uma execução pausada após uma interrupção ainda pode aparecer como em execução. workflow_run.phase_started e workflow_run.phase_ended reconstroem o progresso. Uma execução sem nenhum evento de status ainda não começou a ser executada. Nenhum endpoint lista execuções.

Orçamentos e limites

As solicitações de modelo de uma execução contam para o orçamento da sessão. Uma execução não tem preço próprio. Os tokens que seus agentes usam são cobrados como os outros tokens da sessão, às tarifas de cada modelo. Para todas as cobranças de uma sessão, consulte Preços do Claude Managed Agents.

• Uso de uma execução: Liste as threads da sessão e some as contagens de tokens em usage das threads com o workflow_run_id da execução. A lista inclui threads arquivadas, cujo status é terminated, então as threads de uma execução concluída são contadas. Passe o next_page de cada resposta como page até que next_page seja null ou esteja ausente, e ignore uma thread cujo usage seja null. Se, em vez disso, você somar o list_cost das threads, o total deixa de fora o tempo de execução da sessão, e cada valor é arredondado separadamente.
• No orçamento: Toda execução aberta é pausada, e a sessão informa idle com budget_reached, ou requires_action se uma chamada de ferramenta também estiver esperando. Cada thread conclui a solicitação de modelo que já iniciou, então uma execução pode ultrapassar o orçamento em uma solicitação para cada thread que está trabalhando. Aumentar ou remover o orçamento retoma as execuções que ele pausou, a menos que uma interrupção também as tenha pausado. Se o uso da sessão incluir um modelo sem preço de lista, apenas remover o orçamento faz isso; consulte Modelos sem preço de lista.

O servidor encurta o name de uma execução ou fase para 64 caracteres e sua description para 256. O servidor tem outros limites para workflows, e regras para eles, que não estão listados aqui. O que você vê depende de quando o servidor encontra o problema:

Uma sessão pode iniciar qualquer número de execuções ao longo de sua vida.

Limites de taxa

O trabalho de uma execução conta para os "rate limits" (limites de taxa) que sua organização já tem.

Quando uma solicitação de modelo de uma das threads de uma execução atinge o limite de taxa, ou o modelo está sobrecarregado, o próprio fluxo da thread pode receber um session.error do tipo model_rate_limited_error ou model_overloaded_error:

• Se seu retry_status.type for retrying, o servidor está tentando a solicitação novamente, e a thread ainda está trabalhando.
• Se for exhausted, a thread falhou. Se o workflow deixar que essa falha encerre a execução, a execução termina com program_error, que não nomeia a causa. Leia os eventos das threads que falharam para encontrá-la.

O servidor também limita quanto todas as sessões da sua organização fazem a cada minuto. Uma thread que atinge esse limite para, com um session.error em seu próprio fluxo cuja mensagem nomeia um limite de taxa. Espere um minuto antes de pedir ao agente que continue.

Uma execução pode criar mais de uma thread para a mesma parte do trabalho, então torne as ferramentas que seus agentes chamam seguras para serem chamadas duas vezes.