Sandboxes auto-hospedados

Por padrão, o Managed Agents executa ferramentas e código dentro de sandboxes em nuvem gerenciados pela Anthropic. Sandboxes auto-hospedados mantêm a orquestração do lado da Anthropic, mas movem a execução de ferramentas para a infraestrutura que você controla, de modo que o código do agente, o sistema de arquivos e o tráfego de saída de rede nunca saiam do seu ambiente.

A execução de ferramentas permanece no seu host: o sistema de arquivos que o agente lê e grava, os processos que ele inicia e a rede que ele pode alcançar estão todos sob seu controle. As entradas e saídas das ferramentas ainda fluem para o plano de controle da Anthropic (onde o Claude é executado) para que o modelo possa ver os resultados e determinar o que fazer a seguir. Consulte o modelo de segurança para ver o limite completo do fluxo de dados.

Como difere dos ambientes em nuvem

A auto-hospedagem é uma boa opção quando o agente precisa operar sobre dados que não podem sair do limite da sua rede, alcançar serviços internos que não são roteáveis publicamente ou executar sob os próprios controles de conformidade e auditoria da sua organização.

Para elegibilidade de Zero Data Retention e HIPAA BAA, consulte API e retenção de dados.

Quando combinar com túneis MCP

A auto-hospedagem controla onde o código do agente é executado. Os túneis MCP controlam como a Anthropic alcança servidores MCP na sua rede. Eles são independentes: uma sessão executando nos sandboxes em nuvem da Anthropic ainda pode alcançar servidores MCP privados através de um túnel, e uma sessão auto-hospedada pode usar servidores MCP tunelados ou públicos. Use ambos quando quiser que a execução e o acesso a ferramentas permaneçam dentro do seu limite.

Worker de ambiente

Um "environment worker" (worker de ambiente) é um processo que você executa na sua própria infraestrutura. Ele recebe solicitações de execução de ferramentas da Anthropic e as executa localmente. O ambiente self_hosted atua como uma fila de trabalho: quando uma sessão é atribuída a ele, a Anthropic enfileira a sessão como um item de trabalho. Seu worker reivindica itens de trabalho dessa fila, cria um contexto de execução para cada um, baixa as skills do agente (recursos reutilizáveis baseados em sistema de arquivos que dão ao agente expertise específica de domínio), executa as chamadas de ferramentas e envia os resultados de volta.

Os itens de trabalho são reivindicados por meio de polling na fila do ambiente: seja por um worker sempre ativo que faz polling continuamente, ou por um handler acionado por webhook que desperta em session.status_run_started e começa a fazer polling.

Tanto a CLI quanto o SDK fornecem workers pré-construídos. A CLI ant suporta apenas o padrão sempre ativo; o SDK suporta tanto o sempre ativo quanto o acionado por webhook. Ambos são configuráveis: consulte Worker auto-hospedado na referência para as flags da CLI, e Helpers do SDK nesta página para as opções do SDK. Para mais controle, chame os endpoints de Environments Work diretamente e implemente seu próprio worker. No Claude Platform on AWS, o endpoint de listagem GET /v1/environments/{id}/work e seu equivalente no SDK não estão disponíveis atualmente; os outros endpoints de trabalho (poll, ack, heartbeat, stop, post results, get por item e stats) funcionam normalmente.

Sistema de arquivos do sandbox

• /workspace: o diretório de trabalho padrão do sistema para execução de ferramentas e download de skills. A flag --workdir da CLI usa o diretório atual como padrão; passe --workdir /workspace para corresponder ao padrão do sistema. As skills são baixadas para <workdir>/skills/<name>/. Se você usar um diretório de trabalho diferente, atualize o prompt do sistema do seu agente para que o Claude possa localizar os arquivos de skill.
• /mnt/session/outputs: o harness do worker instrui o Claude a gravar os entregáveis finais aqui. No modo sandbox, monte um diretório do host neste caminho para recuperar as saídas após o término da sessão. No modo in-process, as ferramentas de arquivo do worker gravam sob o diretório de trabalho, então este caminho não se aplica.

Antes de começar

Você precisa de:

• Um agente existente. Se você não tiver um, complete o Quickstart primeiro e anote o ID do agente.
• Um host Linux com /bin/bash nesse caminho exato. O SDK TypeScript requer adicionalmente unzip, tar e Node.js 22 ou posterior; o SDK Python usa a biblioteca padrão para extração de arquivos e não tem requisitos binários adicionais. Essas dependências são resolvidas em caminhos fixos e não respeitam substituições de PATH.
• A CLI ant ou um SDK da Anthropic (Python, TypeScript ou Go) no host do worker.
• Duas credenciais: uma chave de ambiente (gerada nas etapas a seguir) autentica o worker na sua fila; sua chave de API do Claude cria sessões e lê estatísticas da fila de fora do host do worker.

Executar um worker

Escolha sempre ativo para a configuração mais simples: um processo de longa duração faz polling na fila continuamente e precisa apenas de HTTPS de saída. Escolha acionado por webhook para evitar executar um poller ocioso; isso requer um endpoint de webhook que a Anthropic possa alcançar (consulte Webhooks para configuração de endpoint e verificação de assinatura).

Helpers do SDK

O SDK fornece três helpers em diferentes níveis de controle. EnvironmentWorker cobre a maioria dos casos de uso; desça para os helpers de nível mais baixo quando precisar iniciar seu próprio processo por sessão ou executar ferramentas em uma sessão já reivindicada.

• EnvironmentWorker: o worker pronto para uso. Lida com polling, configuração e execução de ponta a ponta.
  • .run(): executa indefinidamente, pegando sessões conforme elas chegam. Encerra de forma limpa em SIGTERM.
  • .handle_item(): pega uma sessão pendente, processa-a e encerra.
• work.poller(): faz polling na fila de trabalho em seu nome e entrega cada sessão reivindicada. Use isto quando quiser decidir o que acontece para cada sessão, por exemplo, iniciar um sandbox em vez de executar ferramentas in-process.
  • drain: se deve parar de fazer polling assim que a fila estiver vazia em vez de esperar por novo trabalho.
  • block_ms: quanto tempo esperar pela chegada de trabalho antes de retornar, em milissegundos. Deve estar entre 1 e 999 (espera por poll; o helper refaz o polling automaticamente). Passe null (None em Python, param.Null[int64]() em Go) para uma verificação não bloqueante; omitir o parâmetro usa o long-poll padrão de 999 ms.
  • reclaim_older_than_ms: reivindicar novamente itens de trabalho alocados a um worker que parou de responder.
  • auto_stop: se deve enviar um sinal de parada no item de trabalho após o iterador encerrar. O poller do Go não tem opção de desativação e sempre envia o sinal de parada, então bloqueie no corpo do loop até que a sessão seja concluída em vez de desanexar.
• client.beta.sessions.events.tool_runner(): executa chamadas de ferramentas para uma única sessão, dado o ID da sessão e uma lista de ferramentas. Use quando você já reivindicou o trabalho e precisa apenas da camada de execução.

Use o work poller diretamente quando quiser iniciar seu próprio processo por sessão, por exemplo, criando um sandbox para cada sessão reivindicada:

import asyncio
import os

from anthropic import AsyncAnthropic
from anthropic.types.beta.environments import BetaSelfHostedWork


async def launch_container(work: BetaSelfHostedWork) -> None:
    # Substitua pelo seu próprio inicializador de sandbox por sessão. Passe
    # ANTHROPIC_ENVIRONMENT_KEY para o sandbox iniciado, nunca
    # sua chave de API.
    print(f"claimed session {work.data.id}")


async def main() -> None:
    environment_key = os.environ["ANTHROPIC_ENVIRONMENT_KEY"]
    environment_id = os.environ["ANTHROPIC_ENVIRONMENT_ID"]
    async with AsyncAnthropic(auth_token=environment_key) as client:
        async for work in client.beta.environments.work.poller(
            environment_id=environment_id,
            environment_key=environment_key,
            auto_stop=False,  # the launched sandbox owns the stop call
        ):
            await launch_container(work)


asyncio.run(main())

AgentToolContext é o contexto de execução para chamadas de ferramentas. Ele define o diretório de trabalho e a política de caminhos, e opcionalmente baixa as skills da sessão quando usado como um context manager. beta_agent_toolset_20260401(env) recebe um AgentToolContext e retorna as implementações padrão de ferramentas (bash, read, write, edit, glob, grep).

Com EnvironmentWorker: ambos são gerenciados automaticamente. Passe uma factory tools para personalizar a lista de ferramentas:

EnvironmentWorker(client, ..., tools=lambda env: [beta_bash_tool(env), my_custom_tool])

Com work.poller() e tool_runner(): passe uma lista de ferramentas como tools para client.beta.sessions.events.tool_runner(). Para construir essa lista, configure AgentToolContext você mesmo e chame beta_agent_toolset_20260401(env):

from anthropic.lib.tools.agent_toolset import (
    AgentToolContext,
    beta_agent_toolset_20260401,
)

async with AgentToolContext(
    workdir="/workspace", client=client, session_id=work.data.id
) as env:
    # skills downloaded to /workspace/skills/<name>/
    tools = beta_agent_toolset_20260401(env)

Verificar se o worker está conectado

De um shell separado, usando sua chave de API do Claude (não a chave de ambiente), confirme que workers_polling é pelo menos 1:

ant beta:environments:work stats --environment-id "$ANTHROPIC_ENVIRONMENT_ID"

Se workers_polling permanecer em 0, o worker não está alcançando a fila: confirme que ANTHROPIC_ENVIRONMENT_KEY e ANTHROPIC_ENVIRONMENT_ID estão definidos no host do worker. Consulte Ler profundidade da fila para a resposta completa de estatísticas e exemplos em outras linguagens.

Iniciar uma sessão

Assim que seu worker estiver em execução, crie uma sessão que tenha como alvo o ambiente. A sessão entra na fila de trabalho do ambiente e espera lá até que um worker a reivindique; se nenhum worker estiver conectado, a sessão permanece enfileirada em vez de falhar.

A Anthropic não monta arquivos ou repositórios GitHub em sandboxes auto-hospedados. Para disponibilizar arquivos específicos da sessão, passe referências de arquivo (como um caminho S3 ou SHA de commit) no campo metadata da sessão. Seu script de spawn ou handler --on-work lê esses metadados do item de trabalho reivindicado (através dos endpoints de Environments Work) e prepara os arquivos no diretório de trabalho antes que a execução de ferramentas comece.

session = client.beta.sessions.create(
    agent=agent.id,
    environment_id=environment.id,
    metadata={"input_file": "s3://my-bucket/data.csv"},
)

Consulte Worker auto-hospedado na referência para a lista completa de flags da CLI, e Helpers do SDK para as opções de helper do SDK.

Monitoramento e operações

Essas chamadas são executadas a partir das suas ferramentas de monitoramento ou operações, autenticadas com sua chave de API do Claude, para observar e gerenciar a frota de workers. O loop de reivindicação e keep-alive é tratado dentro dos helpers do worker, então você não chama esses endpoints diretamente.

Ler profundidade da fila

work.stats retorna o estado da fila para um ambiente:

• depth é o número de itens aguardando para serem reivindicados. Escale sua frota de workers ou alerte sobre backlog com base nesse valor.
• pending é o número de itens que um worker reivindicou e está processando atualmente.
• oldest_queued_at é o timestamp do item mais antigo na fila, ou null se a fila estiver vazia.
• workers_polling é o número de workers que fizeram polling nos últimos 30 segundos. Use isso para alertas de liveness.

import os

import anthropic

client = anthropic.Anthropic()

stats = client.beta.environments.work.stats(os.environ["ANTHROPIC_ENVIRONMENT_ID"])
print(f"depth={stats.depth} pending={stats.pending}")

{
  "type": "work_queue_stats",
  "depth": 0,
  "pending": 0,
  "oldest_queued_at": null,
  "workers_polling": 0
}

Parar uma sessão de forma graciosa

Use work.stop para solicitar que o worker que está processando uma sessão específica a encerre de forma limpa. O worker finaliza qualquer chamada de ferramenta em andamento, envia um status final e libera a sessão. Passe force: true no corpo da requisição para interromper imediatamente em vez de esperar a chamada de ferramenta atual ser concluída.

Como essas chamadas são executadas a partir das suas ferramentas de operações e não do host do worker, ANTHROPIC_WORK_ID não é definido automaticamente. Defina-o como o ID do item de trabalho alvo antes de executar os exemplos a seguir.

import os

import anthropic

client = anthropic.Anthropic()

work = client.beta.environments.work.stop(
    os.environ["ANTHROPIC_WORK_ID"],
    environment_id=os.environ["ANTHROPIC_ENVIRONMENT_ID"],
)
print(work.state)

Próximos passos