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” (streaming) das respostas do agente.
Claude Code
Deixe o Claude Code configurar seu agente para você
/claude-api managed-agents-onboardConceitos principais
| Conceito | Descrição |
|---|---|
| Agent (agente) | O modelo, o prompt do sistema, as ferramentas, os servidores MCP e as 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) |
Antes de começar
Crie uma conta no Claude Console
Cadastre-se para obter uma conta no Claude Console ou faça login na conta que você já tem.
Escolha como se autenticar
Fazer login com a CLI é recomendado para desenvolvimento local.
CLIChave de API
Instale a CLI
brew install anthropics/tap/antPara ambientes Linux, baixe o binário da versão diretamente.
VERSION=2.12.1 OS=$(uname -s | tr '[:upper:]' '[:lower:]') case $(uname -m) in x86_64) ARCH=amd64 ;; aarch64) ARCH=arm64 ;; esac curl -fsSL "https://github.com/anthropics/anthropic-cli/releases/download/v${VERSION}/ant_${VERSION}_${OS}_${ARCH}.tar.gz" \ | sudo tar -xz -C /usr/local/bin antVocê pode encontrar todas as versões na página de releases do GitHub.
Você também pode instalar a CLI a partir do código-fonte com
go install, o que requer Go 1.26.10 ou posterior.go install github.com/anthropics/anthropic-cli/v2/cmd/ant@latestO
go installcoloca o binário em$(go env GOPATH)/bin. Adicione esse diretório ao seuPATHcaso ainda não esteja lá:export PATH="$PATH:$(go env GOPATH)/bin"Faça login
ant auth loginDepois que o login for concluído, os SDKs e a CLI usarão suas credenciais automaticamente.
Crie uma chave de API
Crie uma chave de API no Claude Console.
Defina a variável de ambiente
Os SDKs e a CLI leem sua chave a partir de
ANTHROPIC_API_KEY:export ANTHROPIC_API_KEY="your-api-key-here"
Para executar os exemplos da CLI, instale a CLI:
brew install anthropics/tap/antPara ambientes Linux, baixe o binário da versão diretamente.
VERSION=2.12.1
OS=$(uname -s | tr '[:upper:]' '[:lower:]')
case $(uname -m) in
x86_64) ARCH=amd64 ;;
aarch64) ARCH=arm64 ;;
esac
curl -fsSL "https://github.com/anthropics/anthropic-cli/releases/download/v${VERSION}/ant_${VERSION}_${OS}_${ARCH}.tar.gz" \
| sudo tar -xz -C /usr/local/bin antVocê pode encontrar todas as versões na página de releases do GitHub.
Você também pode instalar a CLI a partir do código-fonte com go install, o que requer Go 1.26.10 ou posterior.
go install github.com/anthropics/anthropic-cli/v2/cmd/ant@latestO go install coloca o binário em $(go env GOPATH)/bin. Adicione esse diretório ao seu PATH caso ainda não esteja lá:
export PATH="$PATH:$(go env GOPATH)/bin"Instale o SDK
pip install anthropicCrie sua primeira sessão
Crie um agente
Crie um agente que define o modelo, o “system prompt” (prompt do sistema) e as ferramentas disponíveis.
CLIant apply coding-assistant.mdcoding-assistant.md--- name: Coding Assistant model: claude-opus-5-5 tools: - type: agent_toolset_20260401 configs: - name: web_search enabled: false - name: web_fetch enabled: false --- You are a helpful coding assistant. Write clean, well-documented code.ant applyimprime o ID do agente e o registra emclaude-lock.json. Você o referenciará em todas as sessões que criar.O tipo de ferramenta
agent_toolset_20260401habilita as ferramentas de agente pré-construídas (bash, operações de arquivo, pesquisa na web e mais). Este exemplo desabilita a pesquisa na web e o web fetch porque a tarefa deste guia, escrever um script Python curto, não usa a web. Dê a um agente apenas as ferramentas de que ele precisa. Consulte Ferramentas para ver a lista completa e as opções de configuração por ferramenta.Crie um ambiente
Um ambiente define o “sandbox” (ambiente isolado) onde seu agente é executado. Este usa rede
limitedcom gerenciadores de pacotes permitidos, para que o código executado no sandbox possa acessar registros de pacotes e hosts de código públicos. Com redelimited, a listaallowed_hoststambém se aplica à pesquisa na web e ao web fetch, embora eles sejam executados fora do sandbox. Sem nenhum host listado, como neste ambiente, eles não retornam páginas nem resultados de pesquisa. Se o seu próprio agente usar essas ferramentas, adicione a essa lista os hosts de que ele precisa.CLIant apply environment.yamlenvironment.yaml# yaml-language-server: $schema=https://platform.claude.com/schemas/ant/beta/environment.json name: quickstart-env config: type: cloud networking: type: limited allow_package_managers: trueant applytambém registra o ID do ambiente emclaude-lock.json. Para criar o agente e o ambiente com um único comando, passe os dois arquivos:ant apply coding-assistant.md environment.yaml.Inicie uma sessão
Crie uma sessão que referencia seu agente e seu ambiente.
Pythonsession = 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 à medida que chegam:
Pythonwith 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: if block.type == "text": print(block.text, end="") case "agent.tool_use": print(f"\n[Using tool: {event.name}]") case "session.status_idle": print("\n\nAgent finished.") breakO agente escreve um script Python, executa-o 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_idlequando não tem mais nada a fazer.
Construa um aplicativo completo
Cada um destes inícios rápidos combina o Claude Managed Agents com um framework de chat popular para criar um aplicativo completo e executável. Em cada um deles, o framework renderiza a interface de chat enquanto uma sessão gerenciada executa o loop do agente no lado do servidor: a sessão mantém a transcrição, executa ferramentas em um sandbox e faz streaming dos eventos que o front-end renderiza.
Um analista de pesquisa em um chat no navegador construído com o Chat SDK da Vercel. Cada conversa é uma sessão persistente que faz streaming de sua resposta enquanto um feed ao vivo mostra as chamadas de ferramentas. Trocar o adaptador do Chat SDK move o mesmo handler para Slack, Teams, Discord ou WhatsApp.
Um analista de planilhas em um chat construído com primitivas do assistant-ui. As sessões são a lista de threads, um reducer transforma o log de eventos da sessão em mensagens e cards de ferramentas, e cada comando bash renderiza uma verificação inline de Permitir/Negar antes de ser executado.
Um assistente de finanças pessoais em um chat do CopilotKit. O adaptador AG-UI para o Claude Managed Agents mapeia cada thread de chat para uma sessão gerenciada e faz streaming das respostas token por token, e ferramentas personalizadas renderizam gráficos interativos inline na conversa.
Próximos passos
Crie configurações de agente reutilizáveis e versionadas
Personalize as configurações de rede e do sandbox
Habilite ferramentas específicas para seu agente
Trate eventos e direcione o agente enquanto ele é executado
Execute seu agente em um agendamento cron recorrente
Destile um corpus de documentos uma única vez em uma wiki de conhecimento e, em seguida, responda a perguntas repetidas a partir dela por uma fração do custo
Esta página foi útil?