Agentes GerenciadosPrimeiros passos

Comece a usar o Claude Managed Agents

Crie seu primeiro agente autônomo.

Este guia orienta você na criação de um agente, na configuração de um ambiente, no início de uma sessão e no streaming de respostas do agente.

Prefere um passo a passo interativo? Execute /claude-api managed-agents-onboard na versão mais recente do Claude Code para uma configuração guiada e perguntas e respostas interativas.

Conceitos principais

Conceito	Descrição
Agent (Agente)	O modelo, prompt do sistema, ferramentas, servidores MCP e skills
Environment (Ambiente)	Configuração de onde as sessões são executadas: um sandbox em nuvem gerenciado pela Anthropic ou um sandbox auto-hospedado em sua própria infraestrutura
Session (Sessão)	Uma instância de agente em execução dentro de um ambiente, realizando uma tarefa específica e gerando saídas
Events (Eventos)	Mensagens trocadas entre sua aplicação e o agente (turnos do usuário, resultados de ferramentas, atualizações de status)

Pré-requisitos

Uma conta no Console da Anthropic
Uma chave de API

Instalar a CLI

Verifique a instalação:

ant --version

Instalar o SDK

Defina sua chave de API como uma variável de ambiente:

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

Crie sua primeira sessão

Todas as requisições à Managed Agents API exigem o cabeçalho beta managed-agents-2026-04-01. O SDK define o cabeçalho beta automaticamente.

Crie um agente
Crie um agente que define o modelo, o prompt do sistema e as ferramentas disponíveis.
ant beta:agents create \ --name "Coding Assistant" \ --model '{id: claude-opus-4-8}' \ --system "You are a helpful coding assistant. Write clean, well-documented code." \ --tool '{type: agent_toolset_20260401}'
O tipo de ferramenta agent_toolset_20260401 habilita o conjunto completo de ferramentas de agente pré-construídas (bash, operações de arquivo, busca na web e mais). Consulte Ferramentas para a lista completa e opções de configuração por ferramenta.
Salve o agent.id retornado. Você o referenciará em cada sessão que criar.
Crie um ambiente
Um ambiente define o sandbox onde seu agente é executado.
ant beta:environments create \ --name "quickstart-env" \ --config '{type: cloud, networking: {type: unrestricted}}'
Salve o environment.id retornado. Você o referenciará em cada sessão que criar.
Para executar o sandbox em sua própria infraestrutura em vez de um sandbox na nuvem, consulte Sandboxes auto-hospedados.

Inicie uma sessão

Crie uma sessão que referencia seu agente e ambiente.

session = client.beta.sessions.create(
    agent=agent.id,
    environment_id=environment.id,
    title="Quickstart session",
)

print(f"Session ID: {session.id}")

Envie uma mensagem e faça streaming da resposta

Abra um stream, envie um evento de usuário e, em seguida, processe os eventos conforme eles chegam:

with client.beta.sessions.events.stream(session.id) as stream:
    # Envia a mensagem do usuário após o stream abrir
    client.beta.sessions.events.send(
        session.id,
        events=[
            {
                "type": "user.message",
                "content": [
                    {
                        "type": "text",
                        "text": "Create a Python script that generates the first 20 Fibonacci numbers and saves them to fibonacci.txt",
                    },
                ],
            },
        ],
    )

    # Processa eventos de streaming
    for event in stream:
        match event.type:
            case "agent.message":
                for block in event.content:
                    print(block.text, end="")
            case "agent.tool_use":
                print(f"\n[Using tool: {event.name}]")
            case "session.status_idle":
                print("\n\nAgent finished.")
                break

O agente escreve um script Python, o executa no sandbox e verifica se o arquivo de saída foi criado. Sua saída será semelhante a esta:

I'll create a Python script that generates the first 20 Fibonacci numbers and saves them to a file.
[Using tool: write]
[Using tool: bash]
The script ran successfully. Let me verify the output file.
[Using tool: bash]
fibonacci.txt contains the first 20 Fibonacci numbers (0 through 4181).

Agent finished.

O que está acontecendo

Quando você envia um evento de usuário, o Claude Managed Agents:

Provisiona um sandbox: A configuração do seu ambiente determina como ele é construído.
Executa o loop do agente: Claude determina quais ferramentas usar com base na sua mensagem.
Executa ferramentas: Gravações de arquivos, comandos bash e outras chamadas de ferramentas são executadas dentro do sandbox.
Faz streaming de eventos: Você recebe atualizações em tempo real enquanto o agente trabalha.
Fica ocioso: O agente emite um evento session.status_idle quando não tem mais nada a fazer.

Próximos passos

Defina seu agente

Crie configurações de agente reutilizáveis e versionadas

Configure ambientes

Personalize configurações de rede e sandbox

Ferramentas do agente

Habilite ferramentas específicas para seu agente

Stream de eventos da sessão

Manipule eventos e direcione o agente durante a execução

Implantações agendadas

Execute seu agente em um agendamento cron recorrente

Was this page helpful?

Conceitos principais

Conceito	Descrição
Agent (Agente)	O modelo, prompt do sistema, ferramentas, servidores MCP e skills
Environment (Ambiente)	Configuração de onde as sessões são executadas: um sandbox em nuvem gerenciado pela Anthropic ou um sandbox auto-hospedado em sua própria infraestrutura
Session (Sessão)	Uma instância de agente em execução dentro de um ambiente, realizando uma tarefa específica e gerando saídas
Events (Eventos)	Mensagens trocadas entre sua aplicação e o agente (turnos do usuário, resultados de ferramentas, atualizações de status)

Crie sua primeira sessão

Todas as requisições à Managed Agents API exigem o cabeçalho beta managed-agents-2026-04-01. O SDK define o cabeçalho beta automaticamente.

Crie um agente
Crie um agente que define o modelo, o prompt do sistema e as ferramentas disponíveis.
ant beta:agents create \ --name "Coding Assistant" \ --model '{id: claude-opus-4-8}' \ --system "You are a helpful coding assistant. Write clean, well-documented code." \ --tool '{type: agent_toolset_20260401}'
O tipo de ferramenta agent_toolset_20260401 habilita o conjunto completo de ferramentas de agente pré-construídas (bash, operações de arquivo, busca na web e mais). Consulte Ferramentas para a lista completa e opções de configuração por ferramenta.
Salve o agent.id retornado. Você o referenciará em cada sessão que criar.
Crie um ambiente
Um ambiente define o sandbox onde seu agente é executado.
ant beta:environments create \ --name "quickstart-env" \ --config '{type: cloud, networking: {type: unrestricted}}'
Salve o environment.id retornado. Você o referenciará em cada sessão que criar.
Para executar o sandbox em sua própria infraestrutura em vez de um sandbox na nuvem, consulte Sandboxes auto-hospedados.

Inicie uma sessão

Crie uma sessão que referencia seu agente e ambiente.

session = client.beta.sessions.create(
    agent=agent.id,
    environment_id=environment.id,
    title="Quickstart session",
)

print(f"Session ID: {session.id}")

Envie uma mensagem e faça streaming da resposta

Abra um stream, envie um evento de usuário e, em seguida, processe os eventos conforme eles chegam:

with client.beta.sessions.events.stream(session.id) as stream:
    # Envia a mensagem do usuário após o stream abrir
    client.beta.sessions.events.send(
        session.id,
        events=[
            {
                "type": "user.message",
                "content": [
                    {
                        "type": "text",
                        "text": "Create a Python script that generates the first 20 Fibonacci numbers and saves them to fibonacci.txt",
                    },
                ],
            },
        ],
    )

    # Processa eventos de streaming
    for event in stream:
        match event.type:
            case "agent.message":
                for block in event.content:
                    print(block.text, end="")
            case "agent.tool_use":
                print(f"\n[Using tool: {event.name}]")
            case "session.status_idle":
                print("\n\nAgent finished.")
                break

O agente escreve um script Python, o executa no sandbox e verifica se o arquivo de saída foi criado. Sua saída será semelhante a esta:

I'll create a Python script that generates the first 20 Fibonacci numbers and saves them to a file.
[Using tool: write]
[Using tool: bash]
The script ran successfully. Let me verify the output file.
[Using tool: bash]
fibonacci.txt contains the first 20 Fibonacci numbers (0 through 4181).

Agent finished.

O que está acontecendo

Quando você envia um evento de usuário, o Claude Managed Agents:

Provisiona um sandbox: A configuração do seu ambiente determina como ele é construído.

Executa o loop do agente: Claude determina quais ferramentas usar com base na sua mensagem.

Executa ferramentas: Gravações de arquivos, comandos bash e outras chamadas de ferramentas são executadas dentro do sandbox.

Faz streaming de eventos: Você recebe atualizações em tempo real enquanto o agente trabalha.

Fica ocioso: O agente emite um evento session.status_idle quando não tem mais nada a fazer.

Conceitos principais

Pré-requisitos

Instalar a CLI

Instalar o SDK

Crie sua primeira sessão

O que está acontecendo

Próximos passos

Conceitos principais

Pré-requisitos

Instalar a CLI

Instalar o SDK

Crie sua primeira sessão

O que está acontecendo

Próximos passos

Conceitos principais

Pré-requisitos

Instalar a CLI

Instalar o SDK

Crie sua primeira sessão

O que está acontecendo

Próximos passos

Conceitos principais

Pré-requisitos

Instalar a CLI

Instalar o SDK

Crie sua primeira sessão

O que está acontecendo

Próximos passos