Como criar Claude Managed Agents com o Claude Sonnet 5

Já quis rodar um fluxo no estilo Claude Code a partir de um script em Python, em que o modelo trabalha dentro de um ambiente gerenciado com acesso a ferramentas, arquivos, skills e instruções?

Os Claude Managed Agents foram feitos para esse tipo de fluxo, ajudando você a criar agentes que executam tarefas de múltiplas etapas em um ambiente controlado.

Neste tutorial, vou mostrar como usar o Claude Sonnet 5, um modelo recente da Anthropic projetado para tarefas avançadas de raciocínio, programação e análise de dados. Ele dá ao agente a capacidade de inspecionar dados, usar ferramentas, escrever e executar código e produzir saídas estruturadas.

Você vai criar um Managed Agent, configurar o ambiente, fazer upload de um arquivo CSV e dar ao agente acesso a ferramentas e a uma skill de XLSX. 

O agente vai analisar os dados, gerar arquivos Python, JSON e Excel, verificar os resultados e disponibilizar as saídas finais para download.

Se você é totalmente novo em Claude, recomendo começar pelo curso Claude Code 101.

O que são Claude Managed Agents?

Claude Managed Agents é a infraestrutura gerenciada da Anthropic para rodar o Claude como um agente autônomo. 

Em vez de escrever seu próprio loop para enviar prompts, executar chamadas de ferramenta, salvar resultados e gerenciar a execução, você define o agente e deixa a Anthropic cuidar dessa infraestrutura. 

Ele é feito para tarefas mais longas, de várias etapas, nas quais o modelo pode precisar usar várias ferramentas antes de concluir o trabalho.

Os Managed Agents são estruturados em quatro partes principais:

• Agent: a configuração reutilizável que contém o modelo, o prompt de sistema, as ferramentas, servidores MCP e as skills.
• Environment: onde o agente roda, seja no sandbox em nuvem da Anthropic ou em um sandbox auto-hospedado.
• Session: uma instância em execução do agente que executa uma tarefa específica.
• Events: as mensagens, chamadas de ferramenta, resultados e atualizações de status trocados durante a execução da sessão.

1. pré-requisitos para o seu workspace do Claude Agent

Para acompanhar este tutorial, instale Python 3.12 ou superior e Jupyter Notebook no seu computador. Vamos usar um Jupyter Notebook para criar, rodar e inspecionar o Managed Agent passo a passo.

Você também vai precisar de uma conta no Anthropic Console. 

Crie uma nova chave de API no Console, adicione pelo menos US$ 5 em créditos de API e guarde a chave com segurança. 

Managed Agents podem fazer várias chamadas de modelo e de ferramentas em uma única sessão, então podem custar mais do que uma requisição padrão de API.

Armazene a chave como uma variável de ambiente ANTHROPIC_API_KEY em vez de adicioná-la diretamente ao notebook ou fazer commit no GitHub.

No macOS, Linux ou WSL, rode no terminal:

export ANTHROPIC_API_KEY="your-api-key-here"

No Windows PowerShell, use:

$env:ANTHROPIC_API_KEY="your-api-key-here"

2. configure o Anthropic Python SDK

Antes de criar um Managed Agent, instale o Anthropic Python SDK oficial e importe os módulos necessários para este notebook. 

O SDK fornece o cliente Anthropic, que você vai usar para criar agentes, ambientes, arquivos e sessões. 

%pip install -q --upgrade anthropic

Depois, carregue sua chave de API da Anthropic a partir de uma variável de ambiente. 

Manter a chave fora do notebook é mais seguro do que colocá-la diretamente no código, especialmente se você pretende compartilhar o projeto ou enviá-lo ao GitHub.

import os
from anthropic import Anthropic

api_key = os.environ.get("ANTHROPIC_API_KEY")
assert api_key, "Set ANTHROPIC_API_KEY in your environment or in a local .env file."

Managed Agents atualmente são acessados pela API beta da Anthropic. O beta flag managed-agents-2026-04-01 habilita esse recurso, embora o SDK oficial já envie automaticamente o header beta necessário para requisições de Managed Agents. 

Mantemos a flag no notebook porque ela será necessária depois para listar e baixar arquivos da sessão. 

BETA_FLAG = "managed-agents-2026-04-01"

client = Anthropic(api_key=api_key)

Por fim, crie um dicionário para armazenar os IDs de cada recurso criado durante o tutorial. 

Isso inclui o agente, o ambiente, o arquivo enviado e a sessão. Salvar esses IDs facilita a limpeza no fim, mesmo se algum passo posterior falhar.

created = {"agent": None, "environment": None, "file": None, "session": None}
print("✓ Anthropic client initialized.")

O cliente está pronto. 

3. crie o Managed Agent

Um Managed Agent é a configuração reutilizável do seu fluxo. 

Ao criá-lo, você escolhe o modelo do Claude, escreve o prompt de sistema que define seu papel e instruções, e anexa as ferramentas e skills que ele pode usar. 

Depois, você pode reutilizar o mesmo agente em várias sessões em vez de recriar a configuração a cada vez. 

Vamos chamar nosso agente de Sonnet 5 Data Analyst e usar claude-sonnet-5. 

O prompt de sistema instrui que ele se comporte como um analista de dados criterioso: inspecione arquivos montados em /workspace, use execução de código para a análise, mantenha os resultados concisos e salve os arquivos finais em /mnt/session/outputs.

agent = client.beta.agents.create(
    name="Sonnet 5 Data Analyst",
    model="claude-sonnet-5",
    system=(
        "You are a meticulous data analyst. When asked about data, always read the "
        "file mounted at /workspace, analyse it with the code execution tool, and "
        "report concise, numeric results. Use the XLSX skill for spreadsheet work. "
        "Save final artifacts to /mnt/session/outputs."
    ),
    tools=[
        {"type": "agent_toolset_20260401"},
    ],
    skills=[{"type": "anthropic", "skill_id": "xlsx"}],
)

O agent_toolset_20260401 dá ao agente acesso às ferramentas nativas da Anthropic em uma sessão, enquanto a skill xlsx fornece orientações específicas para criar e analisar planilhas no Excel. 

A Anthropic também oferece skills prontas para workflows em PowerPoint, Word e PDF.

Por fim, salve o ID do agente. 

Você vai usá-lo ao criar uma sessão mais adiante, e ele também permite que a seção de limpeza arquive o agente quando o tutorial terminar.

created["agent"] = agent.id
print(f"✓ Created agent: {agent.id}")

Você deve ver uma saída semelhante a:

✓ Created agent: agent_01EVcgvQsAkLxNnJFp6aynwm

4. configure o Anthropic Cloud Sandbox

Agora, vamos criar o ambiente onde o Managed Agent roda durante uma sessão. 

Um ambiente funciona como um sandbox seguro, dando ao agente um espaço separado para ler arquivos montados, escrever código e executar comandos.

Vamos usar o ambiente em nuvem da Anthropic com rede limitada. O agente usará esse sandbox depois para analisar o arquivo CSV enviado com Python.

environment = client.beta.environments.create(
    name="code-exec-sandbox",
    config={"type": "cloud", "networking": {"type": "limited"}},
)

created["environment"] = environment.id
print(f"✓ Created environment: {environment.id}")

Após rodar a célula, você deve ver um ID de ambiente parecido com:

✓ Created environment: env_01FzWACEf9UJDL65ovBPA1zf

5. faça upload de dados com a Files API da Anthropic

Em seguida, vamos fazer upload do conjunto de dados que o agente vai analisar. 

Os Managed Agents usam a Files API da Anthropic para enviar arquivos locais, que podem ser montados dentro do ambiente da sessão.

Para este guia, estamos usando o dataset de exemplo com 12 linhas chamado sales_data.csv. 

Antes de enviar, verificamos se o arquivo existe e confirmamos que ele contém a quantidade esperada de linhas de dados.

from pathlib import Path

csv_path = Path("sales_data.csv")
assert csv_path.exists(), f"Missing input file: {csv_path.resolve()}"

row_count = sum(1 for _ in csv_path.open(encoding="utf-8")) - 1
assert row_count == 12, f"Expected 12 data rows, found {row_count}"

Depois enviamos o arquivo e guardamos seu ID para a limpeza posterior.

uploaded = client.beta.files.upload(file=csv_path)

created["file"] = uploaded.id
print(f"✓ Uploaded {csv_path}: {uploaded.id} ({row_count} rows)")

Após rodar a célula, você deve ver algo como:

✓ Uploaded sales_data.csv: file_011Cch3EubJkswPdo3gMBvM2 (12 rows)

6. inicialize uma sessão de execução do agente

Agora, vamos criar uma sessão. 

Uma sessão conecta o agente, o ambiente e os recursos de que ele precisa para uma tarefa específica. Aqui, montamos o arquivo CSV enviado em /workspace/sales_data.csv, para que o agente consiga acessá-lo de dentro do sandbox.

session = client.beta.sessions.create(
    agent=agent.id,
    environment_id=environment.id,
    resources=[
        {
            "type": "file",
            "file_id": uploaded.id,
            "mount_path": "/workspace/sales_data.csv",
        },
    ],
)

created["session"] = session.id
print(f"✓ Created session: {session.id}")

Você deve ver um ID de sessão semelhante a:

✓ Created session: sesn_015mNhrKhqqfe7u8VP6GuFdr

7. faça o streaming da resposta do agente

Agora, vamos enviar a tarefa para a sessão e transmitir em tempo real a atividade do agente enquanto ele trabalha. 

Criar uma sessão apenas prepara o agente e o sandbox; o agente começa a trabalhar quando recebe um evento user.message. 

O stream de eventos permite ver, em tempo real, as mensagens do agente, as chamadas de ferramentas e o status final da sessão. 

O prompt pede ao agente para analisar o CSV montado, escrever e rodar um script em Python, criar um resumo em JSON e montar um relatório em Excel. 

Também criamos três variáveis para coletar o texto do agente, registrar as ferramentas usadas e confirmar se a sessão terminou com sucesso.

agent_text_parts = []
tools_used = []
final_status = None

with client.beta.sessions.events.stream(session.id) as stream:
    # Send the user message once the stream is open.
    client.beta.sessions.events.send(
        session.id,
        events=[
            {
                "type": "user.message",
                "content": [
                    {
                        "type": "text",
                        "text": (
                            "Use the XLSX skill and analyze /workspace/sales_data.csv. "
                            "Write /mnt/session/outputs/analyze_sales.py, run that Python "
                            "script, and have it create /mnt/session/outputs/summary.json. "
                            "Also create /mnt/session/outputs/sales_report.xlsx with the "
                            "source data, monthly profit, and a summary sheet."
                        ),
                    }
                ],
            }
        ],
    )

    for event in stream:
        etype = getattr(event, "type", None)

        if etype == "agent.message":
            for block in event.content:
                txt = getattr(block, "text", None)
                if txt:
                    print(txt, end="")
                    agent_text_parts.append(txt)

        elif etype == "agent.tool_use":
            name = getattr(event, "name", "<tool>")
            print(f"\n[tool_use] {name}")
            tools_used.append(name)

        elif etype == "session.status_idle":
            final_status = "idle"
            print("\n\n✓ Agent finished; session is idle.")
            break

        elif etype == "session.status_error":
            final_status = "error"
            print("\n✗ Session reported an error.")
            break

print("Tools used:", tools_used)

Durante a execução, você deve ver eventos de ferramentas como read, bash, write e edit. 

Eles mostram que o agente está inspecionando as instruções e arquivos disponíveis, escrevendo o script de análise, rodando-o dentro do sandbox e corrigindo eventuais problemas.

Uma sessão fica ociosa quando o agente não tem mais trabalho a fazer. Neste exemplo, session.status_idle indica que a tarefa foi concluída, então paramos de escutar o stream. 

A Anthropic gerencia a execução de suas ferramentas nativas dentro do sandbox; você só precisa lidar com resultados de ferramenta quando usar ferramentas personalizadas. 

8. recupere os arquivos gerados e o histórico de eventos

Quando a sessão termina, podemos inspecionar o histórico de eventos salvo e baixar os arquivos criados pelo agente. 

O histórico de eventos traz um registro completo da sessão, incluindo requisições ao modelo, chamadas de ferramenta, resultados das ferramentas e mudanças de status.

history = client.beta.sessions.events.list(session.id, order="asc")

print("--- Session event history ---")
for event in history.data:
    print(event.type)

print(f"({len(history.data)} events total)")

Depois, listamos os arquivos anexados à sessão e baixamos os que estiverem marcados como disponíveis para download. Os arquivos são salvos localmente na pasta outputs.

import os

os.makedirs("outputs", exist_ok=True)

files = client.beta.files.list(scope_id=session.id, betas=[BETA_FLAG])
downloadable = [f for f in files.data if f.downloadable]

print(f"Found {len(downloadable)} downloadable file(s) for this session.")

downloaded_paths = []

for f in downloadable:
    try:
        content = client.beta.files.download(f.id, betas=[BETA_FLAG])
        local_path = os.path.join("outputs", f.filename)

        content.write_to_file(local_path)
        downloaded_paths.append(local_path)

        print(f"  downloaded {f.id} -> {local_path}")
    except Exception as exc:
        print(f"  skip {f.id}: {exc}")

Por fim, verificamos se todas as saídas esperadas foram baixadas com sucesso:

expected_outputs = {"analyze_sales.py", "summary.json", "sales_report.xlsx"}
downloaded_names = {os.path.basename(path) for path in downloaded_paths}

assert expected_outputs <= downloaded_names, (
    f"Missing expected outputs: {sorted(expected_outputs - downloaded_names)}"
)

O script Python, o resumo em JSON e o relatório em Excel gerados agora estão disponíveis localmente na pasta outputs.

9. analise as saídas em Python, JSON e Excel

Depois que o agente conclui a tarefa, os arquivos gerados são baixados para o diretório local outputs/. 

Esses arquivos mostram que o agente fez mais do que retornar um texto: ele escreveu e executou código, criou dados estruturados e produziu um relatório em planilha que pode ser revisado de forma independente.

As capturas abaixo mostram os três artefatos gerados.

Este arquivo contém o código de análise que o agente escreveu e executou, deixando o fluxo reproduzível e fácil de inspecionar.

Este arquivo armazena os resultados em um formato estruturado que pode ser usado por dashboards, APIs ou outros programas.

Este arquivo do Excel apresenta visualmente os cálculos mensais, com receita, custos, lucro, margens, totais e um gráfico.

Para as 12 linhas em sales_data.csv, os resultados verificados são:

• Receita total: US$ 32.900
• Custos totais: US$ 14.750
• Lucro total: US$ 18.150
• Lucro médio mensal: US$ 1.512,50
• Melhor mês: dezembro (lucro de US$ 2.550)
• Pior mês: janeiro (lucro de US$ 400)

A planilha é orientada por fórmulas, em vez de depender apenas de valores fixos. 

Durante a execução, o agente leu as instruções da skill de XLSX anexada, criou a planilha, recalcou com o LibreOffice, conferiu as fórmulas e corrigiu um problema de referência circular antes de concluir a tarefa.

10. faça a limpeza dos recursos da Managed Agent API

Os recursos de um Managed Agent permanecem disponíveis até você removê-los, então é importante limpá-los quando a tarefa terminar. 

Recursos ativos, especialmente sessões e ambientes em execução, podem continuar gerando custos se forem deixados ligados.

Uma sessão precisa estar ociosa antes de poder ser excluída. 

Neste passo final, excluímos a sessão, o arquivo enviado e o ambiente, e depois arquivamos o agente. 

Cada ação de limpeza está envolvida em uma função auxiliar para que uma falha não impeça a remoção dos demais recursos.

def safe(label, fn):
    try:
        fn()
        print(f"✓ deleted {label}")
    except Exception as exc:
        print(f"· could not delete {label}: {exc}")

if created["session"]:
    safe("session", lambda: client.beta.sessions.delete(created["session"]))

if created["file"]:
    safe("file", lambda: client.beta.files.delete(created["file"]))

if created["environment"]:
    safe("environment", lambda: client.beta.environments.delete(created["environment"]))

if created["agent"]:
    safe("agent (archived)", lambda: client.beta.agents.archive(created["agent"]))

print("\n🎉 Cleanup complete. The agent is archived; other resources were deleted.")

Você deve ver uma saída semelhante a:

✓ deleted session
✓ deleted file
✓ deleted environment
✓ deleted agent (archived)

🎉 Cleanup complete. The agent is archived; other resources were deleted.

O projeto completo, incluindo o notebook, o CSV de exemplo e as instruções de setup, está disponível no GitHub. 

Você pode clonar o repositório e reexecutar o notebook para reproduzir os resultados deste guia.

considerações finais

Achei fácil configurar e trabalhar com os Claude Managed Agents. 

Você cria um agente, dá a ele as ferramentas, skills e o sandbox de que precisa e, então, o executa por meio de uma sessão. 

A partir daí, ele consegue cuidar de um fluxo completo, como escrever código, criar arquivos, checar suas próprias saídas e devolver os resultados finais.

Primeiro tentei usar um Modal Sandbox porque eu queria um ambiente externo mais flexível. 

Porém, a configuração ficou complexa demais para o escopo deste guia, então decidi manter o projeto focado no sandbox em nuvem gerenciado da Anthropic.

O principal ponto negativo para mim foi o custo. Rodei este exemplo duas vezes usando um CSV pequeno, com apenas 12 linhas, e o custo ficou em torno de US$ 0,25. 

O dashboard mostrou a cobrança pelo modelo, mas não encontrei um detalhamento fino. Para uma tarefa simples de cálculo e planilha, isso parece caro comparado a opções open source de menor custo.

No geral, este projeto mostra todo o workflow de um Managed Agent: criar um agente, fazer upload de um CSV, rodar Python em um sandbox gerenciado, gerar relatórios em JSON e Excel, verificar as saídas, baixar os arquivos e limpar os recursos ao final.