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
| Comando | Descrição |
|---|---|
ant beta:worker poll | Reivindica 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 run | Processa uma sessão reivindicada e encerra. Use-o como o entrypoint de um sandbox por sessão. |
| Flag | Descrição |
|---|---|
--environment-id | O ambiente a ser consultado em busca de trabalho. Também lê de ANTHROPIC_ENVIRONMENT_ID. |
--environment-key | Autentica o worker com este ambiente. Também lê de ANTHROPIC_ENVIRONMENT_KEY. |
--workdir | Diretório onde as skills são baixadas e onde as ferramentas leem e gravam arquivos. O padrão é . (o diretório atual). |
--on-work | Script 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-idle | Quanto 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-format | Formato de saída dos logs. Use json para ingestão de logs estruturados. O padrão é text. |
Variáveis de ambiente
| Variável | Descrição | Definida por |
|---|---|---|
ANTHROPIC_ENVIRONMENT_ID | O ambiente cuja fila o worker atende. | Você, no host do worker. O poller a repassa ao script --on-work. |
ANTHROPIC_ENVIRONMENT_KEY | Autentica o worker na sua fila. | Você, no host do worker. O poller a repassa ao script --on-work. |
ANTHROPIC_SESSION_ID | A sessão que um item de trabalho reivindicado representa. | O poller, para o script --on-work. |
ANTHROPIC_WORK_ID | O item de trabalho reivindicado. | O poller, para o script --on-work. |
ANTHROPIC_WORK_SECRET | O segredo por sessão do item de trabalho. | Você. O poller não a define. Consulte Encaminhar o segredo do item de trabalho. |
ANTHROPIC_BASE_URL | Substitui o endpoint padrão da API. Opcional. | Você, no host do worker. |
ANTHROPIC_WEBHOOK_SIGNING_KEY | Verifica os payloads de webhook recebidos. | Você, em um host de handler de webhook. |
Requisitos do host
| Worker | Requisito |
|---|---|
| Todos os workers | Um host Linux ou macOS com /bin/bash exatamente nesse caminho. A ferramenta bash do worker o invoca diretamente, sem consultar o PATH. No macOS, esse é o Bash 3.2 do sistema. |
| SDK TypeScript | unzip e tar no PATH, e Node.js 22 ou posterior. |
| SDKs Python e Go | Nenhum 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
| Caminho | Conteúdo |
|---|---|
/workspace | O diretório de trabalho padrão do sistema para execução de ferramentas e download de skills. 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>/ | Um diretório por memory store anexado, no mount_path do store (por exemplo, /mnt/memory/user-preferences/). O worker cria esses diretórios quando reivindica a sessão e os remove quando a sessão termina. |
Em ambientes auto-hospedados, o prompt do sistema da sessão omite a instrução /mnt/session/outputs usada em sandboxes gerenciados pela Anthropic. 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.
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ê implementar o download de skills manualmente, será responsável por definir as permissões de execução.
Helpers do SDK
Os SDKs Python, TypeScript e Go fornecem três helpers com diferentes níveis de controle:
| Helper | O que faz | Use quando |
|---|---|---|
EnvironmentWorker | Cuida do polling, da configuração e da execução 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 o que acontece em cada sessão, por exemplo, iniciar 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 da camada de execução. |
EnvironmentWorker
| Método | Descrição |
|---|---|
run() | Executa indefinidamente, pegando as sessões à medida que chegam. |
handle_item() | Processa um único item de trabalho reivindicado e retorna. Passe explicitamente os identificadores do trabalho, da sessão e do ambiente e o work_secret, ou deixe-o ler as variáveis ANTHROPIC_*. |
| Opção | Descrição |
|---|---|
tools | Uma 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. |
memory_sync_interval | Com que frequência os memory stores anexados se reconciliam com o servidor enquanto a sessão é executada. Consulte Intervalo de sincronização. |
memory_sync_deletions | Se 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:
EnvironmentWorker(client, ..., tools=lambda env: [beta_bash_tool(env), my_custom_tool])Work poller
| Opção | Descrição |
|---|---|
drain | Se deve parar o polling quando a fila estiver vazia em vez de aguardar novo trabalho. |
block_ms | Quanto 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_ms | Reivindica novamente itens de trabalho que foram reivindicados, mas nunca confirmados dentro desse número de milissegundos. |
auto_stop | Se deve enviar um sinal de parada para cada item de trabalho quando o corpo do seu loop terminar de processá-lo. Defina como False quando o que quer que execute o item de trabalho envie a parada por conta própria. handle_item() faz isso, assim como um sandbox que você inicia e que é responsável pela chamada de parada. |
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 para /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ção | Descrição |
|---|---|
allowed_roots | Diretórios, além do diretório de trabalho, que as ferramentas de arquivo (read, write, edit, glob, grep) podem acessar. |
read_only_roots | Diretó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?