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 a saída de rede nunca saem do seu ambiente.

A execução de ferramentas permanece no seu host: o sistema de arquivos que o agente lê e escreve, 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 Claude é executado) para que o modelo possa ver os resultados e determinar o que fazer em seguida. Consulte o modelo de segurança para 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 com 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. 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 em 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, inicia 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 publica os resultados de volta.

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

A CLI e o SDK incluem workers pré-construídos. A CLI ant suporta apenas o padrão sempre ativo; o SDK suporta tanto sempre ativo quanto 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.



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 Claude possa localizar os arquivos de skill.
• /mnt/session/outputs: o harness do worker instrui Claude a escrever 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 escrevem 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 Início rápido primeiro e anote o ID do agente.
• Um host Linux com /bin/bash nesse caminho exato. A ferramenta bash do worker o invoca diretamente, sem consultar o PATH. O SDK TypeScript adicionalmente requer unzip e tar no PATH e Node.js 22 ou posterior; os SDKs Python e Go usam suas bibliotecas padrão para extração de arquivos e não têm requisitos adicionais de binários.
• A CLI ant ou um SDK da Anthropic (Python, TypeScript ou Go) no host do worker.
• Duas credenciais: uma chave de ambiente (gerada no Console nas etapas a seguir) autentica o worker em sua fila; sua chave de API do Claude cria sessões e lê estatísticas da fila de fora do host do worker. A geração de chaves é exclusiva do Console.



Execute um worker

Escolha sempre ativo para a configuração mais simples: um processo de longa duração faz polling da 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 do 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.
  • .handle_item(): trata um único item de trabalho reivindicado e encerra. Passe os identificadores de trabalho, sessão e ambiente explicitamente, ou deixe-o ler as variáveis ANTHROPIC_* que ant beta:worker poll --on-work define para o processo que ele inicia.
• work.poller(): faz polling da 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 o polling quando 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: reivindica novamente itens de trabalho que foram reivindicados mas nunca confirmados dentro desse número de milissegundos.
  • auto_stop: se deve publicar um sinal de parada para cada item de trabalho quando o corpo do seu loop terminar com ele. O poller Go não tem opção de desativação e sempre publica o sinal de parada, então bloqueie no corpo do loop até a sessão ser 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 só precisa da camada de execução.

Use o work poller diretamente quando quiser iniciar seu próprio processo por sessão, por exemplo, iniciando 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 pode baixar as skills da sessão. 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 o 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 baixadas para /workspace/skills/<name>/
    tools = beta_agent_toolset_20260401(env)



Verifique se o worker está conectado

A partir de um shell separado, com ANTHROPIC_API_KEY definido com 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 a profundidade da fila para a resposta completa de estatísticas e exemplos em outras linguagens.



Inicie uma sessão

Depois que seu worker estiver em execução, crie uma sessão que tenha como alvo o ambiente. Defina AGENT_ID com o ID do agente que você anotou em Antes de começar. 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 arquivos (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 (o poller da CLI envia o JSON do item de trabalho para o stdin do script, e os handlers do SDK podem lê-lo através dos endpoints de Environments Work) e prepara os arquivos no diretório de trabalho antes do início da execução das ferramentas.

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 helpers 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 a 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 crie alertas de 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 ainda enfileirado ou sendo processado, ou null quando não há nenhum.
• 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 pedir ao worker que está tratando uma sessão específica que a encerre de forma limpa. O worker finaliza qualquer chamada de ferramenta em andamento, publica um status final e libera a sessão. Passe force: true no corpo da requisição (com a CLI, passe --force) para interromper imediatamente em vez de esperar a conclusão da chamada de ferramenta atual.

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 com o ID do item de trabalho alvo antes de executar os exemplos a seguir. Para encontrar o ID de um item de trabalho, liste os itens de trabalho do ambiente através dos endpoints de Environments Work.

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