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 o 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 em 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. Para dar ao agente ferramentas de um servidor MCP dentro da sua rede sem executar um túnel, você também pode encapsular o servidor como ferramentas personalizadas servidas pelo seu worker.



Worker de ambiente

Um 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, 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 desperta em session.status_run_started e começa a fazer polling.

A CLI e o SDK fornecem 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 por padrão o diretório atual; 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.
• Saídas: em ambientes auto-hospedados, o prompt do sistema da sessão omite a instrução /mnt/session/outputs usada em sandboxes gerenciados pela Anthropic, então os entregáveis finais ficam onde quer que o agente os escreva no sistema de arquivos do seu sandbox, tipicamente sob o diretório de trabalho.



Antes de começar

Você precisa de:

• Um agente existente. Se você não tiver um, complete primeiro o Início rápido e anote seu ID de 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 nos passos 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. 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 contra 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, capturando 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 no processo.
  • 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: re-reivindica itens de trabalho que foram reivindicados mas nunca confirmados dentro desta quantidade 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 completar 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 poller de trabalho 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. O item de trabalho reivindicado não carrega os metadados da sessão, mas carrega o ID da sessão: seu script de spawn ou handler --on-work recupera a sessão (GET /v1/sessions/{session_id}) para ler o campo metadata e, em seguida, 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 helpers do SDK.



Sirva ferramentas personalizadas a partir do seu sandbox

Ferramentas personalizadas são ferramentas que seu próprio código executa: o agente emite um evento agent.custom_tool_use e espera por um user.custom_tool_result correspondente. O worker pode ser esse código e, como ele é executado dentro do seu sandbox, a ferramenta alcança os serviços internos, credenciais e saída de rede que você configurou para o sandbox, e nada mais. A chave de ambiente autoriza a publicação de resultados de ferramentas personalizadas, então sua chave de API do Claude fica fora do host do worker.

O worker responde apenas às ferramentas registradas nele. Uma ferramenta personalizada que é declarada no agente mas não registrada em nenhum worker ou cliente deixa a sessão pausada com um motivo de parada requires_action até que algo publique seu resultado; consulte Tratando chamadas de ferramentas personalizadas para o fluxo de eventos.



Encapsule um servidor MCP como ferramentas personalizadas

O conector MCP conecta-se a servidores MCP a partir do lado da Anthropic, então um servidor deve expor um endpoint HTTP que a Anthropic possa alcançar, diretamente ou através de um túnel MCP. Para usar um servidor que apenas sua rede pode alcançar, torne o worker o cliente MCP e declare as ferramentas do servidor como ferramentas personalizadas. O servidor MCP não precisa de conectividade de entrada de fora da sua rede; a Anthropic recebe as definições de ferramentas que você declara no agente, a entrada de cada chamada e o resultado que seu worker publica de volta. Em tempo de execução, o modelo chama uma ferramenta encapsulada como qualquer outra ferramenta personalizada:

1. O agente emite um evento agent.custom_tool_use.
2. O worker, dentro do seu sandbox, encaminha a chamada pela sua sessão MCP aberta para o servidor na sua rede.
3. O worker publica a resposta do servidor como o user.custom_tool_result.

Os helpers MCP do lado do cliente dos SDKs convertem as ferramentas do servidor nas ferramentas executáveis que o worker aceita; instale um SDK MCP junto com o SDK da Anthropic (pip install "anthropic[mcp]" "mcp>=1.24", npm install @modelcontextprotocol/sdk, go get github.com/modelcontextprotocol/go-sdk). Os exemplos conectam sem autenticação; para enviar credenciais, configure o cliente HTTP ou as opções de requisição que você entrega ao transporte MCP (http_client em Python, requestInit em TypeScript, HTTPClient em Go).

Tenha em mente o seguinte ao encapsular um servidor MCP:

• As ferramentas são declaradas, não descobertas em tempo de execução. O worker lista as ferramentas do servidor MCP uma vez na inicialização e não pode adicionar ferramentas a uma sessão em execução. Quando as ferramentas do servidor mudarem, declare-as novamente, no agente ou em uma sessão ociosa através de Atualizando a configuração do agente, e reinicie o worker.
• Nomes e descrições devem se adequar à API do Managed Agents. Nomes de ferramentas personalizadas são únicos por agente e usam letras, dígitos, sublinhados e hifens (1–128 caracteres); uma descrição é obrigatória (1–4.096 caracteres); e o array tools de um agente aceita no máximo 128 entradas (cada ferramenta encapsulada é uma entrada, e o conjunto de ferramentas integrado é mais uma). A API rejeita uma declaração que reutilize um nome de ferramenta, nomeie uma ferramenta personalizada com o nome de uma ferramenta integrada do agente como bash ou read, ou use o prefixo reservado mcp__. Os helpers MCP mantêm os nomes e descrições do servidor, então renomeie ou reduza onde necessário. Quando dois servidores expõem o mesmo nome de ferramenta, defina o wrapper você mesmo sob um nome com prefixo e faça-o chamar o nome original da ferramenta do servidor.
• A maioria dos schemas passa sem alterações. A API aceita as palavras-chave de JSON Schema que servidores MCP comumente emitem, como additionalProperties e title. Ela rejeita palavras-chave de referência como $ref em qualquer lugar do input_schema de uma ferramenta personalizada, então coloque inline os schemas que geradores como pydantic fatoram em $defs. Ela também rejeita oneOf, anyOf e allOf no nível superior, e nomes de propriedades fora de letras, dígitos, sublinhados, pontos e hifens (1–64 caracteres).
• Falhas de ferramentas aparecem como resultados de ferramenta com erro. Quando o servidor MCP reporta um erro de ferramenta, o worker publica um resultado de ferramenta com erro ao qual o modelo pode reagir. Conteúdo MCP sem equivalente de resultado de ferramenta, como blocos de áudio e links de recursos, também aparece como erro. Defina um timeout no cliente MCP para uma falha mais rápida e clara, como o exemplo do worker Python faz com read_timeout_seconds. Sem um, uma chamada travada só se torna um resultado de erro quando o timeout de requisição padrão do SDK MCP TypeScript dispara (cerca de um minuto) ou quando o próprio mecanismo de segurança do worker dispara: cerca de dois minutos e meio em Python, e dois minutos em Go, onde o worker cancela uma chamada de ferramenta que ultrapassa seu padrão de 120 segundos e publica um resultado de erro.
• Encapsule servidores que você opera ou confia. O nome, a descrição e os resultados de uma ferramenta encapsulada entram no contexto do modelo como os de qualquer outra ferramenta: entrada não confiável que pode influenciar o que o agente faz com suas outras ferramentas, incluindo bash no host do worker. Declare apenas as ferramentas que você pretende que o agente use.
• Políticas de permissão não se aplicam a ferramentas personalizadas. Políticas de permissão governam os conjuntos de ferramentas integrados e MCP; o worker executa toda chamada de ferramenta encapsulada que o modelo fizer, então coloque qualquer etapa de aprovação no seu próprio código de ferramenta.



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 esperando para serem reivindicados. Escale sua frota de workers ou alerte sobre backlog com base neste valor.
• pending é o número de itens reivindicados por um worker mas ainda não confirmados. Os helpers do worker confirmam cada item antes de processá-lo, então este valor permanece próximo de zero em operação normal; um valor diferente de zero sustentado significa que um worker travou entre reivindicar e confirmar.
• oldest_queued_at é o timestamp do item mais antigo ainda na fila, esperando para ser reivindicado ou reivindicado mas ainda não confirmado, ou null quando não há nenhum.
• workers_polling é o número de workers que fizeram polling nos últimos 30 segundos. Use isto 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
}



Interromper uma sessão de forma controlada

Use work.stop para solicitar que o worker responsável por uma sessão específica a encerre. Por padrão, o item de trabalho passa para stopping: o worker percebe no próximo heartbeat de lease, cancela a chamada de ferramenta em andamento da sessão e confirma o encerramento, momento em que o item de trabalho se torna stopped. Passe force: true no corpo da requisição (com a CLI, passe --force) para marcar o item de trabalho como stopped imediatamente, em vez de aguardar a confirmação do worker.

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

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