Claude Platform Docs
Managed AgentsSandboxes auto-hospedados

Referência de workers auto-hospedados

Referência para workers de sandbox auto-hospedados: flags da CLI ant, variáveis de ambiente, requisitos do host, caminhos do sistema de arquivos e opções dos helpers do SDK.

Esta página documenta os workers pré-construídos que atendem a um ambiente self_hosted. Para guias orientados a tarefas, comece com Sandboxes auto-hospedados e Implantar workers auto-hospedados.

Comandos e flags da CLI

ComandoDescrição
ant beta:worker pollReivindica itens de trabalho da fila do ambiente e executa cada sessão no próprio processo. Com --on-work, chama seu script para cada item de trabalho em vez disso.
ant beta:worker runProcessa uma sessão reivindicada e encerra. Use-o como o entrypoint de um sandbox por sessão.
FlagDescrição
--environment-idO ambiente a ser consultado em busca de trabalho. Também lê de ANTHROPIC_ENVIRONMENT_ID.
--environment-keyAutentica o worker com este ambiente. Também lê de ANTHROPIC_ENVIRONMENT_KEY.
--workdirDiretório onde o worker baixa as skills e onde as ferramentas leem e gravam arquivos. O padrão é . (o diretório atual). O diretório deve existir antes de o worker iniciar.
--on-workScript a ser chamado para cada item de trabalho reivindicado em vez de executar as ferramentas no próprio processo. Recebe os detalhes da sessão como variáveis de ambiente e o item de trabalho como JSON na entrada padrão.
--max-idleQuanto tempo o worker aguarda enquanto uma sessão está ociosa antes que ant beta:worker run encerre ou que ant beta:worker poll passe para o próximo item de trabalho. O tempo ocioso com um stop reason requires_action (motivo de parada) não é contabilizado. O padrão é 60s. Defina como 0 para desativar o tempo limite. Com um script --on-work, ant beta:worker poll ignora esta flag. Em vez disso, passe-a para o comando ant beta:worker run que seu script inicia.
--log-formatFormato de saída dos logs. Use json para ingestão de logs estruturados. O padrão é text.

Variáveis de ambiente

VariávelDescriçãoDefinida por
ANTHROPIC_ENVIRONMENT_IDO ambiente cuja fila o worker atende.Você, no host do worker. O poller a repassa ao script --on-work.
ANTHROPIC_ENVIRONMENT_KEYAutentica o worker na sua fila.Você, no host do worker. O poller a repassa ao script --on-work.
ANTHROPIC_SESSION_IDA sessão que um item de trabalho reivindicado representa.O poller, para o script --on-work.
ANTHROPIC_WORK_IDO item de trabalho reivindicado.O poller, para o script --on-work.
ANTHROPIC_WORK_SECRETO segredo do item de trabalho para a sessão dele.Você. O poller não a define. Consulte Encaminhar o segredo do item de trabalho.
ANTHROPIC_BASE_URLSubstitui o endpoint padrão da API. Opcional.Você, no host do worker.
ANTHROPIC_WEBHOOK_SIGNING_KEYVerifica os payloads de webhook recebidos.Você, em um host de handler de webhook.

Requisitos do host

WorkerRequisito
Todos os workersUm host Linux ou macOS com /bin/bash exatamente nesse caminho. A ferramenta bash do worker o executa diretamente, sem consultar o PATH. No macOS, esse é o Bash 3.2 do sistema.
SDK TypeScriptunzip e tar no PATH, e Node.js 22 ou posterior.
SDKs Python e GoNenhum binário adicional. Esses SDKs usam suas bibliotecas padrão para extração de arquivos compactados.

Memory stores (armazenamentos de memória) adicionam seus próprios requisitos.

No macOS, o volume raiz é somente leitura, então mkdir não consegue criar /workspace. Defina o diretório de trabalho do worker como um diretório no qual você possa gravar, como um diretório workspace no seu diretório pessoal. Para usar memory stores no macOS, primeiro prepare o host macOS.

Sistema de arquivos do sandbox

CaminhoConteúdo
/workspaceO diretório de trabalho usado nos exemplos das páginas de sandboxes auto-hospedados. Ele não é o padrão do worker: o worker usa o diretório atual, a menos que você defina --workdir ou workdir. Os sandboxes em nuvem da Anthropic mantêm skills e repositórios em /workspace. Se você usar um diretório de trabalho diferente, atualize o prompt do sistema do seu agente para que Claude consiga localizar os arquivos das skills.
<workdir>/skills/<name>/As skills baixadas do agente.
/mnt/memory/<store>/Uma cópia local de cada memory store anexado, um diretório por store. A API retorna o caminho completo de cada diretório no campo mount_path do recurso de memory store da sessão (por exemplo, /mnt/memory/user-preferences/).

O worker cria os diretórios dos memory stores quando reivindica uma sessão. Ele os remove quando termina de atender a essa sessão ou quando você parar o worker de forma controlada. Isso remove apenas as cópias locais, e as memórias permanecem no store.

As skills podem incluir executáveis que o agente pode executar diretamente. Os workers da CLI e do SDK preservam as permissões de execução registradas no pacote da skill ao extraí-lo. Se você mesmo baixar as skills, defina você mesmo as permissões de execução delas.

Quando o worker termina de atender a uma sessão

O worker termina de atender a uma sessão em qualquer um destes casos:

  • A sessão termina.
  • Você para o item de trabalho da sessão.
  • A sessão permanece ociosa pelo “idle limit” (limite de ociosidade) do worker. A própria sessão permanece aberta. Quando você então enviar a ela um novo evento, como uma mensagem do usuário, o mesmo worker ou outro a reivindica. Esse worker baixa os stores novamente.

O limite de ociosidade é de 60 segundos por padrão. Para alterá-lo, use --max-idle para o worker da CLI ant ou max_idle para o EnvironmentWorker. O chart do Helm cma-sandboxes inicia seus workers com um limite de 30 minutos em vez disso. Para alterar esse limite, altere a configuração sandbox.idleTimeout do chart.

Entregáveis finais

Sandboxes auto-hospedados não têm o diretório /mnt/session/outputs. Nos sandboxes na nuvem da Anthropic, o prompt do sistema da sessão instrui o agente a copiar os entregáveis finais para lá. Em ambientes auto-hospedados, o prompt do sistema omite essa instrução. Os entregáveis finais ficam onde quer que o agente os grave, normalmente sob o diretório de trabalho, e o worker não faz upload deles.

Para reunir os entregáveis finais em um só lugar, informe o caminho completo de um diretório no prompt do sistema do seu agente. Escolha um diretório no qual as ferramentas de arquivo do worker possam gravar:

  • Dentro do diretório de trabalho: por exemplo, /workspace/outputs se o diretório de trabalho for /workspace.
  • Em qualquer outro lugar, somente com um worker do SDK: adicione o diretório a allowed_roots. Consulte AgentToolContext e o conjunto de ferramentas do agente.

Helpers do SDK

Os SDKs Python, TypeScript e Go fornecem três helpers com diferentes níveis de controle:

HelperO que fazUse quando
EnvironmentWorkerCuida do polling, da configuração e da execução de ferramentas de ponta a ponta.Na maioria dos casos.
work.poller()Consulta a fila de trabalho e entrega a você cada sessão reivindicada.Você determina como tratar cada sessão, por exemplo, iniciando um sandbox em vez de executar as ferramentas no próprio processo.
client.beta.sessions.events.tool_runner()Executa chamadas de ferramentas para uma única sessão, dados o ID da sessão e uma lista de ferramentas.Você já reivindicou o trabalho e só precisa executar as ferramentas.

EnvironmentWorker

MétodoDescrição
run()Executa indefinidamente, pegando as sessões à medida que chegam.
handle_item()Processa um único item de trabalho já reivindicado por um poller. O poller pode ser ant beta:worker poll --on-work ou seu próprio código. O método retorna quando o worker termina de atender à sessão do item. Você pode passar work_id, session_id, environment_id e work_secret. Para cada um que você omitir, o método lê a variável ANTHROPIC_* correspondente.
OpçãoDescrição
toolsUma factory que recebe o AgentToolContext da sessão e retorna a lista de ferramentas. O padrão é o conjunto de ferramentas padrão do agente.
max_idleQuanto tempo o worker aguarda enquanto uma sessão está ociosa antes de terminar de atender à sessão. O tempo ocioso com um stop reason requires_action (motivo de parada) não é contabilizado. O padrão é 60 segundos. Para aguardar 5 minutos, defina como 300. Para desativar o limite, defina como None.
memory_sync_intervalO tempo mínimo entre duas sincronizações dos memory stores anexados enquanto a sessão é executada. O worker verifica o intervalo após cada chamada a uma ferramenta executada no seu sandbox, não por um temporizador. O padrão é 15 segundos. Consulte Intervalo de sincronização.
memory_sync_deletionsSe os arquivos que o agente exclui localmente também são excluídos do store. Consulte Exclusões.

O EnvironmentWorker gerencia o AgentToolContext e o conjunto de ferramentas automaticamente. Passe uma factory tools para personalizar a lista de ferramentas:

import asyncio
import contextlib
import os
import signal
from anthropic import AsyncAnthropic, beta_async_tool
from anthropic.lib.environments import EnvironmentWorker
from anthropic.lib.tools.agent_toolset import beta_bash_tool


@beta_async_tool
async def get_order_status(order_id: str) -> str:
    """Look up an order in the internal fulfillment system by order ID."""
    return f"Order {order_id}: shipped"


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:
        worker = EnvironmentWorker(
            client,
            environment_id=environment_id,
            environment_key=environment_key,
            # Liste todas as ferramentas que o agente pode chamar. O worker não responde a nenhuma outra ferramenta.
            tools=lambda env: [beta_bash_tool(env), get_order_status],
        )
        task = asyncio.create_task(worker.run())
        loop = asyncio.get_running_loop()
        for signum in (signal.SIGINT, signal.SIGTERM):
            loop.add_signal_handler(signum, task.cancel)
        with contextlib.suppress(asyncio.CancelledError):
            await task


asyncio.run(main())

Work poller

OpçãoDescrição
drainSe deve parar o polling quando a fila estiver vazia em vez de aguardar novo trabalho.
block_msQuanto tempo cada poll espera a chegada de trabalho antes de retornar, em milissegundos. Deve estar entre 1 e 999. O helper refaz o poll automaticamente. Passe None para uma verificação não bloqueante. O padrão é um long-poll de 999ms.
reclaim_older_than_msReivindica novamente itens de trabalho que foram reivindicados, mas nunca confirmados dentro desse número de milissegundos.
auto_stopSe o poller envia um sinal de parada para cada item de trabalho quando o corpo do seu loop terminar de processá-lo. O padrão é True. Defina como False nos dois casos descritos após esta tabela.

Defina auto_stop como False em dois casos:

  1. Seu loop chama handle_item(), que envia a parada por conta própria.
  2. Seu loop inicia um sandbox para o item e segue em frente. O worker nesse sandbox deve enviar a parada quando o trabalho da sessão terminar, como fazem ant beta:worker run e handle_item().

Para um exemplo completo, consulte Iniciar sandboxes a partir do poller do SDK.

Tool runner de sessão

client.beta.sessions.events.tool_runner() recebe uma lista de ferramentas como tools. 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 em /workspace/skills/<name>/
    tools = beta_agent_toolset_20260401(env)

AgentToolContext e o conjunto de ferramentas do agente

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.

OpçãoDescrição
allowed_rootsDiretórios, além do diretório de trabalho, que as ferramentas de arquivo (read, write, edit, glob, grep) podem acessar.
read_only_rootsDiretórios sob os quais write e edit recusam caminhos.

O EnvironmentWorker adiciona por conta própria os diretórios dos memory stores da sessão a allowed_roots, e os diretórios dos stores anexados com access: "read_only" a read_only_roots.

O confinamento é uma proteção apenas para as ferramentas de arquivo, não um sandbox. Ele não restringe o bash.

beta_agent_toolset_20260401(env) recebe um AgentToolContext e retorna as implementações de ferramentas padrão (bash, read, write, edit, glob, grep).

Esta página foi útil?