--- title: Referência de workers auto-hospedados url: https://platform.claude.com/docs/pt-BR/managed-agents/self-hosted-sandboxes-reference description: "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." featureMetadata: topic: title: Managed Agents url: https://platform.claude.com/docs/en/managed-agents/overview status: beta betaHeader: managed-agents-2026-04-01 --- 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](https://platform.claude.com/docs/pt-BR/managed-agents/self-hosted-sandboxes) e [Implantar workers auto-hospedados](https://platform.claude.com/docs/pt-BR/managed-agents/self-hosted-sandboxes-workers). ## 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 esperar depois que a sessão fica ociosa com um [stop reason](https://platform.claude.com/docs/pt-BR/build-with-claude/handling-stop-reasons) (motivo de parada) `end_turn` antes de encerrar. O padrão é `60s`. | | `--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](https://platform.claude.com/docs/pt-BR/managed-agents/self-hosted-sandboxes-workers#forward-the-work-items-secret). | | `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 com `/bin/bash` exatamente nesse caminho. A ferramenta bash do worker o invoca diretamente, sem consultar o `PATH`. | | 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](https://platform.claude.com/docs/pt-BR/managed-agents/self-hosted-sandboxes-memory#requirements) (armazenamentos de memória) adicionam seus próprios requisitos. ## 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. | | `/skills//` | As skills baixadas do agente. | | `/mnt/memory//` | Um diretório por memory store anexado, no `mount_path` (java, php: `mountPath`; csharp, go: `MountPath`) 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`](https://platform.claude.com/docs/pt-BR/managed-agents/self-hosted-sandboxes-reference#environment-worker) | Cuida do polling, da configuração e da execução de ponta a ponta. | Na maioria dos casos. | | [`work.poller()` (go: `environments.NewWorkPoller()`)](https://platform.claude.com/docs/pt-BR/managed-agents/self-hosted-sandboxes-reference#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()` (typescript: `client.beta.sessions.events.toolRunner()`; go: `client.Beta.Sessions.Events.NewToolRunner()`)](https://platform.claude.com/docs/pt-BR/managed-agents/self-hosted-sandboxes-reference#session-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()` (go: `Run()`) | Executa indefinidamente, pegando as sessões à medida que chegam. | | `handle_item()` (typescript: `handleItem()`; go: `HandleItem()`) | 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` (typescript: `workSecret`; go: `WorkSecret`), ou deixe-o ler as [variáveis `ANTHROPIC_*`](https://platform.claude.com/docs/pt-BR/managed-agents/self-hosted-sandboxes-reference#environment-variables). | | Opção | Descrição | | -------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `tools` (go: `ToolsFunc`) | 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` (typescript: `memorySyncIntervalMs`; go: `MemorySyncInterval`) | Com que frequência os memory stores anexados se reconciliam com o servidor enquanto a sessão é executada. Consulte [Intervalo de sincronização](https://platform.claude.com/docs/pt-BR/managed-agents/self-hosted-sandboxes-memory#sync-interval). | | `memory_sync_deletions` (typescript: `memorySyncDeletions`; go: `MemorySyncDeletions`) | Se os arquivos que o agente exclui localmente também são excluídos do store. Consulte [Exclusões](https://platform.claude.com/docs/pt-BR/managed-agents/self-hosted-sandboxes-memory#deletions). | O `EnvironmentWorker` gerencia o `AgentToolContext` e o conjunto de ferramentas automaticamente. Passe uma factory `tools` (go: `ToolsFunc`) para personalizar a lista de ferramentas: ```python Python EnvironmentWorker(client, ..., tools=lambda env: [beta_bash_tool(env), my_custom_tool]) ``` ```typescript TypeScript new EnvironmentWorker({ client, environmentId, environmentKey, tools: (ctx) => [betaBashTool(ctx), myCustomTool] }); ``` O SDK C# não tem `EnvironmentWorker`. Para responder a chamadas de ferramentas personalizadas a partir do seu próprio código, envie cada resultado no stream de eventos da sessão, como em [Retornar um resultado de ferramenta personalizada](https://platform.claude.com/docs/pt-BR/managed-agents/events-and-streaming#return-a-custom-tool-result). ```go Go worker := environments.NewEnvironmentWorker(client, environments.EnvironmentWorkerOptions{ EnvironmentID: environmentID, EnvironmentKey: environmentKey, ToolsFunc: func(env *agenttoolset.AgentToolContext) []anthropic.BetaTool { return []anthropic.BetaTool{agenttoolset.BetaBashTool(env), myCustomTool} }, }) ``` O SDK Java não tem `EnvironmentWorker`. Para responder a chamadas de ferramentas personalizadas a partir do seu próprio código, envie cada resultado no stream de eventos da sessão, como em [Retornar um resultado de ferramenta personalizada](https://platform.claude.com/docs/pt-BR/managed-agents/events-and-streaming#return-a-custom-tool-result). O SDK PHP não tem `EnvironmentWorker`. Para responder a chamadas de ferramentas personalizadas a partir do seu próprio código, envie cada resultado no stream de eventos da sessão, como em [Retornar um resultado de ferramenta personalizada](https://platform.claude.com/docs/pt-BR/managed-agents/events-and-streaming#return-a-custom-tool-result). O SDK Ruby não tem `EnvironmentWorker`. Para responder a chamadas de ferramentas personalizadas a partir do seu próprio código, envie cada resultado no stream de eventos da sessão, como em [Retornar um resultado de ferramenta personalizada](https://platform.claude.com/docs/pt-BR/managed-agents/events-and-streaming#return-a-custom-tool-result). ### Work poller | Opção | Descrição | | ------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `drain` (go: `Drain`) | Se deve parar o polling quando a fila estiver vazia em vez de aguardar novo trabalho. | | `block_ms` (typescript: `blockMs`; go: `BlockMs`) | Quanto tempo cada consulta aguarda a chegada de trabalho antes de retornar, em milissegundos. Deve estar entre 1 e 999; o helper refaz a consulta automaticamente. Passe `null` (python: `None`; go: `param.Null[int64]()`) para uma verificação não bloqueante. O padrão é um long-poll de 999 ms. | | `reclaim_older_than_ms` (typescript: `reclaimOlderThanMs`; go: `ReclaimOlderThanMs`) | Reivindica novamente itens de trabalho que foram reivindicados, mas nunca confirmados dentro desse número de milissegundos. | | `auto_stop` (typescript: `autoStop`; go: `AutoStop`) | 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` (python: `False`; go: `param.NewOpt(false)`) quando o que quer que execute o item de trabalho envie a parada por conta própria. `handle_item()` (typescript: `handleItem()`; go: `HandleItem()`) 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](https://platform.claude.com/docs/pt-BR/managed-agents/self-hosted-sandboxes-workers#launch-sandboxes-from-the-sdk-poller). ### Session tool runner `client.beta.sessions.events.tool_runner()` (typescript: `client.beta.sessions.events.toolRunner()`; go: `client.Beta.Sessions.Events.NewToolRunner()`) recebe uma lista de ferramentas como `tools` (go: `Tools`). Para construir essa lista, configure o `AgentToolContext` você mesmo e chame `beta_agent_toolset_20260401(env)` (typescript: `betaAgentToolset20260401(ctx)`; go: `agenttoolset.BetaAgentToolset20260401(env)`): ```python Python 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// tools = beta_agent_toolset_20260401(env) ``` ```typescript TypeScript import { setupSkills, betaAgentToolset20260401 } from "@anthropic-ai/sdk/tools/agent-toolset/node"; const ctx = { workdir: "/workspace", client, sessionId: work.data.id }; await setupSkills(ctx); const tools = betaAgentToolset20260401(ctx); ``` O SDK C# não tem `AgentToolContext`. ```go Go env := &agenttoolset.AgentToolContext{Workdir: "/workspace"} if err := env.SetupSkills(ctx, client, work.Data.ID); err != nil { panic(err) } // skills baixadas para /workspace/skills// tools := agenttoolset.BetaAgentToolset20260401(env) ``` O SDK Java não tem `AgentToolContext`. O SDK PHP não tem `AgentToolContext`. O SDK Ruby não tem `AgentToolContext`. ### 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` (typescript: `allowedRoots`; go: `AllowedRoots`) | Diretórios, além do diretório de trabalho, que as ferramentas de arquivo (`read`, `write`, `edit`, `glob`, `grep`) podem acessar. | | `read_only_roots` (typescript: `readOnlyRoots`; go: `ReadOnlyRoots`) | 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` (typescript: `allowedRoots`; go: `AllowedRoots`), e os diretórios dos stores anexados com `access: "read_only"` a `read_only_roots` (typescript: `readOnlyRoots`; go: `ReadOnlyRoots`). 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)` (typescript: `betaAgentToolset20260401(ctx)`; go: `agenttoolset.BetaAgentToolset20260401(env)`) recebe um `AgentToolContext` e retorna as implementações de ferramentas padrão (`bash`, `read`, `write`, `edit`, `glob`, `grep`).