Sandboxes auto-hospedados

Por padrão, o Managed Agents executa ferramentas e código dentro de sandboxes em nuvem gerenciados pela Anthropic. Os 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, o sistema de arquivos e a saída de rede do agente 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 gera 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 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 ser executado 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 executada 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, gera 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 incluem 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 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 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 nos sandboxes gerenciados pela Anthropic, então os entregáveis finais ficam onde quer que o agente os grave no sistema de arquivos do seu sandbox, normalmente sob o diretório de trabalho.



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. 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 binários adicionais.
• 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 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 é feita apenas no Console.



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, capturando sessões à medida que chegam.
  • .handle_item(): processa 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 gera.
• work.poller(): faz polling na fila de trabalho em seu nome e fornece 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 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 que foram reivindicados mas nunca confirmados dentro deste número de milissegundos.
  • auto_stop: se deve enviar um sinal de parada para cada item de trabalho assim que o corpo do seu loop terminar com ele. O poller 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á tiver reivindicado o trabalho e precisar 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 pode baixar as skills da sessão. beta_agent_toolset_20260401(env) recebe um AgentToolContext e retorna as implementações de ferramentas padrão (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 baixadas para /workspace/skills/<name>/
    tools = beta_agent_toolset_20260401(env)



Verificar se o worker está conectado

De um shell separado, com ANTHROPIC_API_KEY definido como 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. Defina AGENT_ID como 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 na fila 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. 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 então 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.



Servir ferramentas personalizadas 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 o envio 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 com ele. Uma ferramenta personalizada que é declarada no agente mas não registrada com nenhum worker ou cliente deixa a sessão pausada com um stop reason requires_action até que algo envie seu resultado; consulte Lidando com chamadas de ferramentas personalizadas para o fluxo de eventos.



Encapsular um servidor MCP como ferramentas personalizadas

O conector MCP conecta-se a servidores MCP 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, faça do 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 envia 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 através de sua sessão MCP aberta para o servidor na sua rede.
3. O worker envia 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ê passa para o transporte MCP (http_client em Python, requestInit em TypeScript, HTTPClient em Go).

Tenha o seguinte em mente 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, underscores e hífens (1–128 caracteres); uma descrição não vazia é obrigatória; 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 reutiliza um nome de ferramenta, nomeia uma ferramenta personalizada com o nome de uma ferramenta integrada do agente como bash ou read, ou usa 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 prefixado 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 JSON Schema que servidores MCP comumente emitem, como additionalProperties e title. Ela rejeita palavras-chave de referência como $ref em qualquer lugar no input_schema de uma ferramenta personalizada, então faça inline dos 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, underscores, pontos e hífens (1–64 caracteres).
• Falhas de ferramentas aparecem como resultados de ferramenta de erro. Quando o servidor MCP reporta um erro de ferramenta, o worker envia um resultado de ferramenta de 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 se torna um resultado de erro apenas quando o timeout padrão de requisição do SDK MCP TypeScript dispara (cerca de um minuto) ou quando o próprio backstop 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 envia 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 faz, 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 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 não 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 work item passa para stopping: o worker percebe isso no próximo heartbeat do lease, cancela a chamada de ferramenta em andamento da sessão e confirma o encerramento, momento em que o work item se torna stopped. Passe force: true no corpo da requisição (com a CLI, passe --force) para marcar o work item 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 como o ID do work item de destino antes de executar os exemplos a seguir. Para encontrar o ID de um work item, liste os work items 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