Edição em Markdown

AI-translated from English; not yet reviewed by a fluent editor.

# Crie um fluxo de trabalho do Claude para revisar documentos em paralelo

> O Managed Agents beta da Anthropic pode transformar a revisão de documentos em um fluxo de trabalho com várias fases. Este guia mostra como configurar uma execução, inspecionar seus eventos e resultados e levar em conta custos e limites.

By BIG CHANGE Editorial

Published: 2026-10-09T20:34:58.333Z
Updated: 2026-10-09T20:34:58.333Z
Canonical: https://bigchange.ai/blog/claude-managed-agents-parallel-document-review-guide

![One reader sits at a laptop with text on screen; a page with faint text lines lies on the table beside it.](https://bigchange.ai/api/media/file/claude-managed-agents-document-review-hero-v1.png)
Conceptual illustration of a reader manually checking a proposed document-review report. It is not a Claude product screenshot or a BIG CHANGE hands-on test. AI-generated illustration by BIG CHANGE.

O Claude Managed Agents agora pode escrever um programa de fluxo de trabalho que atribui partes de uma tarefa grande a vários agentes, reúne as descobertas e as combina. O recurso está em beta. Veja uma configuração documentada para quem desenvolve software e quer revisar uma pasta de documentos e produzir um arquivo de descobertas verificadas.

Isto usa a API Claude Platform e a CLI da Anthropic. A BIG CHANGE analisou a documentação atual; não executamos a configuração nem testamos um fluxo de trabalho.

## O que o fluxo de trabalho faz

Um [fluxo de trabalho dinâmico](https://platform.claude.com/docs/en/managed-agents/workflow-runs) é um programa para uma execução. O programa pode dividir o trabalho em fases, iniciar threads de agentes em paralelo, passar resultados entre fases, repetir ou tratar uma ramificação com falha e combinar os resultados. Por exemplo, uma primeira fase pode inspecionar arquivos separados e uma fase posterior conciliar as descobertas. O agente principal inicia a execução; o servidor a executa em segundo plano.

Isso é diferente de pedir ao agente principal que crie execuções separadas. Uma execução de fluxo de trabalho coordena threads filhos dentro de uma única execução e devolve o resultado ao agente que a iniciou. Uma mensagem comum da sessão não inicia uma execução por si só; o agente decide quando iniciá-la com base na tarefa e no prompt do sistema. Segundo a Anthropic, uma sessão pode ter várias execuções abertas, mas cada execução tem fases e resultado próprios.

## Antes de começar

Você precisa de uma conta Claude Console, uma chave de API e acesso ao Claude Managed Agents, que, segundo a Anthropic, vem ativado por padrão para contas de API. Os endpoints de agente e fluxo de trabalho exigem o `managed-agents-2026-04-01` cabeçalho beta. O SDK da Anthropic define esse cabeçalho automaticamente; ao chamar a API sem um SDK, inclua-o manualmente.

A documentação atual ainda identifica o Managed Agents como [beta](https://platform.claude.com/docs/en/managed-agents/overview). As [notas de versão](https://platform.claude.com/docs/en/release-notes/overview) da Anthropic datam a beta pública de 9 de abril de 2026, a orquestração multiagente de 11 de maio e os fluxos de trabalho dinâmicos de 9 de outubro. Os fluxos dinâmicos também estão em beta. A data importa: o número de “1.000 agentes” é um limite atual por execução de fluxo de trabalho, não uma nova capacidade de iniciar 1.000 agentes simultaneamente.

A plataforma armazena no servidor o histórico de conversa da sessão, o estado da sandbox e as saídas. A Anthropic informa que o Managed Agents não é atualmente elegível para [Zero Data Retention ou cobertura de HIPAA Business Associate Agreement](https://platform.claude.com/docs/en/managed-agents/overview). Não coloque material regulamentado ou confidencial em uma sessão sem que sua organização tenha confirmado as regras de dados aplicáveis e a configuração.

## 1. Instale a CLI e o SDK

Instale a `ant` CLI da Anthropic pelo método para seu sistema operacional no [guia de início rápido do Managed Agents](https://platform.claude.com/docs/en/managed-agents/quickstart). Por exemplo, o comando documentado para macOS é:

```sh
brew install anthropics/tap/ant
```

Para Python, instale o SDK e forneça a chave de API pelo ambiente, em vez de colocá-la em um arquivo-fonte:

```sh
pip install anthropic
export ANTHROPIC_API_KEY="your-api-key"
```

A chave acima é um valor de exemplo. Guarde o valor real no seu gerenciador de segredos habitual ou em uma configuração de ambiente protegida.

## 2. Defina um agente que possa usar fluxos de trabalho

Crie `document-reviewer.md`. O bloco `multiagent` ativa o tipo de fluxo de trabalho de outubro. Desativar subagentes deixa explícito o caminho de delegação configurado: este agente usa fluxos de trabalho dinâmicos em vez de delegar tarefas pontuais a subagentes.

```yaml
---
name: document-reviewer
model: claude-sonnet-5-5
tools:
- type: agent_toolset_20260401
multiagent:
type: multiagent_20261001
subagents:
type: disabled
workflows:
type: enabled
---

You review documents for a user-defined checklist.

When a request contains more than 20 independent files, use a dynamic workflow.
Make one phase that checks the files independently and a later phase that
reconciles duplicate findings. Do not infer missing facts. Save the final
machine-readable results to report.json and a concise explanation to summary.md.
Include the source filename and a short evidence excerpt for every finding.
If a file cannot be read or a worker fails, record that file as unresolved;
do not silently omit it. The final response must report the number of files
reviewed, unresolved files, and whether every output file was written.
```

O limite e as instruções de revisão são escolhas da sua política, não padrões da Anthropic. Adapte-os ao trabalho e ao custo dos erros. `claude-sonnet-5-5` é um ID de modelo de exemplo; escolha um modelo atualmente disponível para sua conta e orçamento.

Crie o agente e guarde o ID retornado:

```sh
ant apply document-reviewer.md
```

A CLI exibe o ID do agente e o registra em `claude-lock.json`. O Managed Agents separa a definição reutilizável do agente (modelo, instruções e ferramentas) do ambiente onde uma sessão é executada.

## 3. Configure a sandbox

Um ambiente controla onde as sessões são executadas: em uma sandbox na nuvem gerenciada pela Anthropic ou em uma sandbox auto-hospedada na sua infraestrutura. O exemplo de nuvem do guia de início rápido usa rede restrita e permite gerenciadores de pacotes:

```yaml
# environment.yaml
name: document-review
config:
type: cloud
networking:
type: limited
allow_package_managers: true
```

Aplique-o com `ant apply environment.yaml`; o ID também é salvo em `claude-lock.json`. Se o agente precisar de acesso à rede, liste apenas os hosts necessários em `allowed_hosts`. Com a rede limitada, essa lista de hosts também restringe as ferramentas de pesquisa e busca na web do Managed Agents. Uma configuração que permita gerenciadores de pacotes não adiciona sites à lista de permissões.

Na primeira execução, use uma pasta pequena e sem dados confidenciais, e somente as ferramentas necessárias. O conjunto integrado de ferramentas do agente inclui operações de shell e arquivos; adicionar ferramentas pode ampliar o que ele consegue fazer. Confira a política de permissões documentada e os controles da sandbox antes de conceder acesso a sistemas externos ou credenciais.

## 4. Inicie uma sessão e envie uma tarefa delimitada

Use os IDs do agente e do ambiente para criar uma sessão com o SDK de Python:

```python
import anthropic

client = anthropic.Anthropic()
session = client.beta.sessions.create(
agent="AGENT_ID_FROM_CLAUDE_LOCK",
environment_id="ENVIRONMENT_ID_FROM_CLAUDE_LOCK",
title="Small document review",
)
print(session.id)
```

Substitua os dois espaços reservados de ID pelos valores em `claude-lock.json`. Em seguida, envie uma tarefa concreta pelo fluxo de eventos da sessão. Inicie o fluxo antes de enviar o evento para acompanhar a execução e seu andamento à medida que ocorrem:

```python
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": (
"Review each Markdown file in /review-set for a missing "
"owner, deadline, or acceptance criterion. Quote evidence; "
"do not infer missing details. Reconcile duplicate findings "
"and write /mnt/session/outputs/report.json plus "
"/mnt/session/outputs/summary.md. In report.json, use "
"a files array with one record per input: path, status "
"(reviewed or unresolved), and findings; each finding has "
"a check, evidence excerpt, and source location. Include "
"input, reviewed, and unresolved counts."
),
}],
}],
)
open_runs = {}
run_results = {}
for event in stream:
if event.type == "workflow_run.created":
open_runs[event.workflow_run_id] = event.name
print(f"Run started: {event.name}")
elif event.type == "workflow_run.status_ended":
run_results[event.workflow_run_id] = event.result.type
open_runs.pop(event.workflow_run_id, None)
print(f"Run ended: {event.result.type}")
elif event.type == "workflow_run.error":
print(f"Run error: {event.error}")
elif event.type == "agent.message":
for block in event.content:
if block.type == "text":
print(block.text)
elif event.type == "session.status_idle":
if event.stop_reason.type == "end_turn" and not open_runs:
break

# Inspect the child threads associated with completed workflow runs.
for thread in client.beta.sessions.threads.list(session.id):
if thread.workflow_run_id in run_results:
print(f"Thread {thread.id}: {thread.status}")
for thread_event in client.beta.sessions.threads.events.list(
thread.id, session_id=session.id
):
if thread_event.type == "session.error":
print(f"Thread error: {thread_event}")
```

Este exemplo pressupõe que o método de entrada configurado para sua sessão disponibilize os arquivos em `/review-set`. Coloque os arquivos na sandbox da sessão pelo método de entrada documentado antes de pedir ao agente que os revise. Peça que ele grave os resultados em `/mnt/session/outputs/`; a documentação de arquivos do [Managed Agents](https://platform.claude.com/docs/en/managed-agents/files) explica como listar arquivos vinculados a uma sessão e baixá-los. No SDK de Python, a forma documentada para ler o resultado é:

```python
files = client.beta.files.list(
scope_id=session.id,
betas=["managed-agents-2026-04-01"],
)
for report in files:
if report.filename == "report.json":
content = client.files.download(report.id)
content.write_to_file("report.json")
break
```

Um arquivo pode levar alguns segundos para aparecer depois que a sessão fica ociosa; se estiver faltando, liste novamente após uma breve espera. Para uma primeira execução segura, crie uma pasta de teste com alguns documentos cujas descobertas esperadas você possa inspecionar manualmente. O prompt de exemplo define a tarefa de revisão; não garante que o agente encontrará todos os problemas.

O contrato de saída deve ser rigoroso o bastante para permitir auditoria. Por exemplo:

```json
{
"files": [
{
"path": "requirements.md",
"status": "reviewed",
"findings": [
{
"check": "deadline",
"evidence_excerpt": "...",
"source_location": "requirements.md, section 2"
}
]
}
],
"input_count": 1,
"reviewed_count": 1,
"unresolved_count": 0
}
```

Este é um esquema sugerido para seu fluxo de trabalho, não um esquema fornecido pela Anthropic. Mantenha arquivos não resolvidos ou ilegíveis como registros para que um resultado ausente não pareça uma revisão sem problemas.

## 5. Verifique a execução e os resultados

Quando um fluxo de trabalho começa, o fluxo de eventos informa `workflow_run.created`, incluindo um ID de execução e as fases declaradas pelo fluxo. O exemplo mantém cada ID de execução aberto até o respectivo `workflow_run.status_ended`; uma sessão primária ociosa, por si só, não comprova que o fluxo em segundo plano terminou. O fluxo primário resume o estado das threads filhas, enquanto a lista de eventos de cada thread contém suas mensagens e erros. O exemplo lista threads por `workflow_run_id` e apresenta eventos `session.error` . Inspecione esses eventos para encontrar tentativas esgotadas (inclusive `retry_status.type == "exhausted"`) ou outros erros de threads filhas e marque os arquivos afetados como não resolvidos.

Trate o arquivo de saída como a entrega, e não a palavra “concluído”. A Anthropic alerta explicitamente que uma execução pode terminar com `completed` mesmo que uma thread tenha falhado ou não tenha podido ser criada. Abra `report.json` e confira se cada arquivo de entrada tem descobertas ou um status explicitamente não resolvido, se os trechos de evidência apontam para o arquivo-fonte correto e se as contagens correspondem aos arquivos enviados. Compare a pequena pasta de teste com os resultados esperados por você antes de usar o fluxo em um corpus maior.

Se seu cliente desconectar, um novo fluxo de eventos envia apenas os eventos emitidos depois que ele é aberto. Reconstrua o estado da execução listando eventos anteriores da sessão com os filtros documentados por tipo de evento e seguindo a paginação. Não conclua que uma execução terminou só porque o agente primário ficou ocioso enquanto threads filhas ainda podem estar trabalhando. Depois que todas as execuções observadas terminarem, liste os arquivos da sessão e baixe `/mnt/session/outputs/report.json` e `summary.md` pela Files API documentada. Confira se todo arquivo fornecido tem um registro revisado ou não resolvido e se as contagens conferem. O loop de eventos de exemplo não baixa nem valida o relatório em si.

## Limites que mudam o projeto

Os [limites de execução de fluxo de trabalho](https://platform.claude.com/docs/en/managed-agents/workflow-runs) documentados pela Anthropic permitem atualmente até 64 threads de fluxo trabalhando ao mesmo tempo em uma execução, mas a API não garante essa concorrência e o valor pode mudar. O limite de 1.000 agentes conta os agentes iniciados durante toda a vida da execução. Não é uma contagem de threads simultâneas. Se o fluxo tentar iniciar outro agente após alcançar esse total, a execução termina com `thread_limit_error`; novas tentativas de agentes que falharam podem criar threads adicionais.

Uma execução dura 24 horas por padrão, ou menos se seu agente definir um prazo menor. O tempo aguardando seu cliente também conta, e uma execução pausada ainda pode expirar. Uma sessão tem 10 execuções abertas por padrão, incluindo as ociosas. O orçamento de uso da sessão se aplica a todos os agentes do fluxo; quando é atingido, as execuções abertas pausam até que o orçamento seja aumentado ou removido. Planeje unidades menores de trabalho, salve pontos de controle em arquivos e faça a fase de conciliação informar itens inacabados em vez de fingir que foram revisados.

Em caso de falha, inspecione o `workflow_run.error` e a thread afetada. `program_error` pode indicar que o código do fluxo ou uma thread filha falhou; `thread_limit_error` identifica o teto de 1.000 agentes; `timeout_error` identifica o tempo de vida da execução. Se a execução alcançar o orçamento da sessão, aumente-o ou remova-o para retomá-la. Para interromper um fluxo, peça ao agente primário que pare suas execuções; interromper um turno da sessão não é, por si só, um comando de cancelamento da execução.

## Custo

A [documentação de preços](https://platform.claude.com/docs/en/about-claude/pricing) da Anthropic cobra do Managed Agents os tokens pelas tarifas do modelo escolhido e o tempo de sessão a **US$ 0,08 por hora de sessão em execução**. O tempo é contabilizado enquanto o status da sessão é `running`; períodos ociosos, reagendados ou encerrados não contam. Uma execução de fluxo não tem tarifa separada, mas o uso de tokens das threads é cobrado como parte da sessão. Pesquisas na web iniciadas em uma sessão custam US$ 10 por 1.000 buscas. O total exato depende do modelo, dos tokens de entrada e saída, das ferramentas e da duração da sessão; confira o uso no Console em vez de estimá-lo pelo teto de 1.000 agentes.

Na prática, comece com poucos arquivos, verifique se a saída do fluxo dá conta de cada um, inspecione as threads que falharam e só amplie a entrada quando a política de revisão e o custo forem aceitáveis. Fluxos gerenciados oferecem uma forma de coordenar trabalho paralelo assíncrono; eles não certificam as descobertas.

## A grande mudança

Desde 9 de outubro, um agente do Managed Agents pode escrever um programa de fluxo que o servidor executa em várias threads e fases de agentes. Desenvolvedores podem usar esse caminho para distribuir trabalho de forma delimitada e auditável enquanto a sessão principal acompanha o andamento. O recurso continua em beta, e os limites publicados não prometem que toda execução atingirá a concorrência máxima ou produzirá descobertas corretas.

## Fontes e leituras adicionais

- [Visão geral do Claude Managed Agents](https://platform.claude.com/docs/en/managed-agents/overview) — status beta, cabeçalho da API, acesso, sessões com estado, ferramentas e limites de retenção de dados.
- [Primeiros passos com Claude Managed Agents](https://platform.claude.com/docs/en/managed-agents/quickstart) — CLI, SDK, configuração de agente/ambiente, criação de sessão e exemplo de fluxo de eventos.
- [Orquestração multiagente](https://platform.claude.com/docs/en/managed-agents/multiagent-orchestration) — habilitar fluxos dinâmicos e escolher entre fluxos e subagentes.
- [Execuções de fluxo de trabalho](https://platform.claude.com/docs/en/managed-agents/workflow-runs) — eventos de execução, interpretação de resultados, recuperação, orçamentos e limites documentados.
- [Threads de sessão](https://platform.claude.com/docs/en/managed-agents/session-threads) — listar threads filhas associadas à execução e ler seus históricos de eventos.
- [Arquivos de sessão](https://platform.claude.com/docs/en/managed-agents/files) — entradas montadas, caminhos de saída, listagem de arquivos da sessão e downloads.
- [Notas de versão da Claude Platform](https://platform.claude.com/docs/en/release-notes/overview) — atualização de fluxos dinâmicos de 9 de outubro de 2026 e configuração beta.
- [Preços da Claude Platform](https://platform.claude.com/docs/en/about-claude/pricing) — cobrança por tokens e tarifas de execução da sessão.

## Sources

- [Visão geral do Claude Managed Agents](https://platform.claude.com/docs/en/managed-agents/overview) — Status beta atual, cabeçalho da API, acesso, sessões com estado e limites de retenção de dados.
- [Primeiros passos com Claude Managed Agents](https://platform.claude.com/docs/en/managed-agents/quickstart) — Configuração da CLI e do SDK, configuração de agente/ambiente e exemplos de sessão e fluxo de eventos.
- [Orquestração multiagente](https://platform.claude.com/docs/en/managed-agents/multiagent-orchestration) — Habilitação de fluxos de trabalho e diferença em relação a subagentes.
- [Execuções de fluxo de trabalho](https://platform.claude.com/docs/en/managed-agents/workflow-runs) — Mecânica de fluxos/execuções, eventos, interpretação do estado de saída, recuperação, orçamentos e limites.
- [Claude Platform release notes](https://platform.claude.com/docs/en/release-notes/overview) — Histórico datado da beta pública e atualização de fluxos dinâmicos de 9 de outubro de 2026; URL canônica corrigida.
- [Claude Platform pricing](https://platform.claude.com/docs/en/about-claude/pricing) — Preços de tokens do Managed Agents e de tempo de sessão.
- [Session threads](https://platform.claude.com/docs/en/managed-agents/session-threads) — Listagem de threads filhas associadas às execuções e leitura de seus históricos de eventos.
- [Session files](https://platform.claude.com/docs/en/managed-agents/files) — Entradas montadas, caminhos de saída, listagem e downloads de arquivos da sessão.

Edição em Markdown

Encontre uma matéria.

Explore o BIG CHANGE.

Encontre uma matéria.

Explore o BIG CHANGE.

Edição em Markdown

A visão ampla, no seu ritmo.

Sua privacidade, sua escolha.

Sua privacidade, sua escolha.