--- title: Implantar workers auto-hospedados url: https://platform.claude.com/docs/pt-BR/managed-agents/self-hosted-sandboxes-workers description: "Escolha como os workers de sandbox auto-hospedados reivindicam trabalho e onde as sessões são executadas: sempre ativos ou acionados por webhook, em um único processo ou em um sandbox por sessão." featureMetadata: topic: title: Managed Agents url: https://platform.claude.com/docs/en/managed-agents/overview status: beta betaHeader: managed-agents-2026-04-01 --- O [início rápido](https://platform.claude.com/docs/pt-BR/managed-agents/self-hosted-sandboxes#quickstart) executa um worker da CLI `ant` que faz polling continuamente e executa todas as sessões em um único processo. Esta página aborda as outras formas de executar um worker e como escolher entre elas. ## Escolher um padrão de implantação Ao implantar workers, você precisa fazer duas escolhas: como o worker reivindica trabalho e onde cada sessão é executada. **Como o worker reivindica trabalho:** * **Sempre ativo:** Um processo de longa duração faz polling da fila continuamente e precisa apenas de HTTPS de saída. Esta é a configuração mais simples. * **Acionado por webhook:** Um handler é ativado em `session.status_run_started` e começa a fazer polling. Isso evita um poller ocioso, mas requer um endpoint de [webhook](https://platform.claude.com/docs/pt-BR/managed-agents/webhooks) que a Anthropic consiga alcançar. **Onde cada sessão é executada:** * **No próprio processo:** O worker que reivindica uma sessão também executa suas chamadas de ferramentas, em um diretório de trabalho compartilhado. * **Sandbox por sessão:** Um poller inicia um sandbox novo para cada sessão reivindicada. Escolha esta opção para um isolamento mais forte: um sistema de arquivos novo, limites de recursos ou controles de rede por sessão. Os workers da CLI e do SDK suportam combinações diferentes: | Capacidade | CLI `ant` | SDK (Python, TypeScript, Go) | | ---------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------- | ----------------------------------- | | Polling sempre ativo | Sim | Sim | | Acionado por webhook | Não | Sim | | Sandbox por sessão | Sim | Sim | | [Memory stores](https://platform.claude.com/docs/pt-BR/managed-agents/self-hosted-sandboxes-memory) | Sim, com configurações de sincronização padrão | Sim, com sincronização configurável | | [Ferramentas personalizadas](https://platform.claude.com/docs/pt-BR/managed-agents/self-hosted-sandboxes-custom-tools) | Não | Sim | Consulte a [Referência de workers auto-hospedados](https://platform.claude.com/docs/pt-BR/managed-agents/self-hosted-sandboxes-reference) para ver todas as flags da CLI e opções do SDK. Para ter mais controle, chame diretamente os [endpoints Environments Work](https://platform.claude.com/docs/pt-BR/api/beta/environments/work) e implemente seu próprio worker. ## Executar um worker sempre ativo Inicie um worker que faz polling da fila continuamente. Ele se autentica com a [chave de ambiente](https://platform.claude.com/docs/pt-BR/managed-agents/self-hosted-sandboxes#run-your-first-session) do início rápido: ```bash CLI ant beta:worker poll --workdir /workspace ``` ```python Python import asyncio import contextlib import os import signal from anthropic import AsyncAnthropic from anthropic.lib.environments import EnvironmentWorker 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, workdir="/workspace", ) task = asyncio.create_task(worker.run()) # Cancelar a tarefa, em vez de matar o processo, permite que o worker pare seu # item de trabalho em andamento e envie os arquivos de memória alterados antes de sair. 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()) ``` ```typescript TypeScript import Anthropic from "@anthropic-ai/sdk"; import { EnvironmentWorker } from "@anthropic-ai/sdk/helpers/beta/environments"; const environmentKey = process.env.ANTHROPIC_ENVIRONMENT_KEY!; const environmentId = process.env.ANTHROPIC_ENVIRONMENT_ID!; const client = new Anthropic({ authToken: environmentKey }); const controller = new AbortController(); // Abortar em qualquer dos sinais permite que o worker envie arquivos de memória alterados e remova seus // diretórios de armazenamento antes que o processo termine. process.once("SIGINT", () => controller.abort()); process.once("SIGTERM", () => controller.abort()); await new EnvironmentWorker({ client, environmentId, environmentKey, workdir: "/workspace", signal: controller.signal }).run(); ``` O SDK C# não possui `EnvironmentWorker`. Em vez disso, execute o worker da CLI `ant`: `ant beta:worker poll --workdir /workspace`. ```go Go package main import ( "context" "log" "os" "os/signal" "syscall" "github.com/anthropics/anthropic-sdk-go" "github.com/anthropics/anthropic-sdk-go/lib/environments" "github.com/anthropics/anthropic-sdk-go/option" ) func main() { environmentKey := os.Getenv("ANTHROPIC_ENVIRONMENT_KEY") environmentID := os.Getenv("ANTHROPIC_ENVIRONMENT_ID") ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM) defer stop() client := anthropic.NewClient(option.WithAuthToken(environmentKey)) worker := environments.NewEnvironmentWorker(client, environments.EnvironmentWorkerOptions{ EnvironmentID: environmentID, EnvironmentKey: environmentKey, Workdir: "/workspace", }) if err := worker.Run(ctx); err != nil { log.Fatalf("worker: %v", err) } } ``` O SDK Java não possui `EnvironmentWorker`. Em vez disso, execute o worker da CLI `ant`: `ant beta:worker poll --workdir /workspace`. O SDK PHP não possui `EnvironmentWorker`. Em vez disso, execute o worker da CLI `ant`: `ant beta:worker poll --workdir /workspace`. O SDK Ruby não possui `EnvironmentWorker`. Em vez disso, execute o worker da CLI `ant`: `ant beta:worker poll --workdir /workspace`. ## Acionar workers a partir de webhooks No [Console](https://platform.claude.com/settings/workspaces/default/webhooks), defina um endpoint de webhook que escute eventos `session.status_run_started`. Consulte [Webhooks](https://platform.claude.com/docs/pt-BR/managed-agents/webhooks) para mais detalhes. Junto com o ID e a chave do ambiente do [início rápido](https://platform.claude.com/docs/pt-BR/managed-agents/self-hosted-sandboxes#run-your-first-session), exporte a chave de assinatura do webhook no host do seu handler. O handler a usa para verificar os payloads recebidos. ```bash export ANTHROPIC_WEBHOOK_SIGNING_KEY="whsec_..." ``` Invoque o worker quando `session.status_run_started` for disparado. O handler esvazia a fila e entrega cada item de trabalho reivindicado para `handle_item()` (typescript: `handleItem()`; go: `HandleItem()`), que baixa skills, executa chamadas de ferramentas, envia os resultados de volta e retorna. Para verificar assinaturas de webhook, instale o extra de webhooks: `pip install "anthropic[webhooks]"`. ```python Python import asyncio import os import anthropic import standardwebhooks # installed by the anthropic[webhooks] extra environment_key = os.environ["ANTHROPIC_ENVIRONMENT_KEY"] environment_id = os.environ["ANTHROPIC_ENVIRONMENT_ID"] client = anthropic.AsyncAnthropic( auth_token=environment_key, ) # Cancelado por shutdown() para que um item de trabalho em andamento possa enviar arquivos de memória alterados e # remover seus diretórios de store antes que o processo termine. inflight: set[asyncio.Task[None]] = set() # Aguarde isto no hook de encerramento do host, como um shutdown de lifespan ASGI (o código após # `yield` em um lifespan do FastAPI), que o uvicorn executa no SIGTERM. O uvicorn deixa requisições abertas # terminarem antes desse hook rodar, então defina --timeout-graceful-shutdown para limitar a espera. async def shutdown() -> None: for task in inflight: task.cancel() await asyncio.gather(*inflight, return_exceptions=True) async def handle(raw: bytes, headers: dict[str, str]) -> tuple[dict[str, str], int]: try: event = client.beta.webhooks.unwrap(raw.decode(), headers=headers) except standardwebhooks.WebhookVerificationError: return {"error": "signature verification failed"}, 401 if event.data.type != "session.status_run_started": return {"status": "ignored"}, 200 task = asyncio.create_task(run_queued_work()) inflight.add(task) task.add_done_callback(inflight.discard) try: # Protegido (shield): uma entrega descartada ou expirada não deve cancelar o item; shutdown() faz isso. await asyncio.shield(task) except asyncio.CancelledError: return {"status": "shutting down"}, 503 return {"status": "ok"}, 200 async def run_queued_work() -> None: async for work in client.beta.environments.work.poller( environment_id=environment_id, environment_key=environment_key, block_ms=None, reclaim_older_than_ms=2000, drain=True, auto_stop=False, ): await client.beta.environments.work.worker(workdir="/workspace").handle_item( work_id=work.id, environment_id=environment_id, session_id=work.data.id, environment_key=environment_key, # O segredo por sessão é o que permite ao worker montar os memory stores da sessão. work_secret=work.secret, ) ``` ```typescript TypeScript import Anthropic from "@anthropic-ai/sdk"; const environmentKey = process.env.ANTHROPIC_ENVIRONMENT_KEY!; const environmentId = process.env.ANTHROPIC_ENVIRONMENT_ID!; const client = new Anthropic({ authToken: environmentKey }); // Chame shutdown.abort() no handler SIGTERM/SIGINT do host, junto com o fechamento do servidor, // depois aguarde as chamadas handle() em andamento antes de sair: o abort permite que um item de trabalho em execução // envie arquivos de memória alterados e remova seus diretórios de store primeiro. export const shutdown = new AbortController(); export async function handle(req: Request): Promise { // Nunca confirme uma entrega cujo trabalho não será executado aqui; um 503 faz o remetente tentar novamente. if (shutdown.signal.aborted) { return Response.json({ status: "shutting down" }, { status: 503 }); } const body = await req.text(); let event; try { event = client.beta.webhooks.unwrap(body, { headers: Object.fromEntries(req.headers) }); } catch { return new Response("signature verification failed", { status: 401 }); } if (event.data.type !== "session.status_run_started") { return Response.json({ status: "ignored" }); } for await (const work of client.beta.environments.work.poller({ environmentId, environmentKey, blockMs: null, reclaimOlderThanMs: 2000, drain: true, autoStop: false, signal: shutdown.signal })) { await client.beta.environments.work.worker({ workdir: "/workspace" }).handleItem({ workId: work.id, environmentId, sessionId: work.data.id, environmentKey, // O segredo por sessão é o que permite ao worker montar os stores de memória da sessão. workSecret: work.secret ?? undefined, signal: shutdown.signal }); } // O poller e handleItem retornam silenciosamente no abort, então um drain interrompido chega aqui. if (shutdown.signal.aborted) { return Response.json({ status: "shutting down" }, { status: 503 }); } return Response.json({ status: "ok" }); } ``` O SDK C# não possui `EnvironmentWorker`. Para processar itens de trabalho a partir do seu próprio código, chame os [endpoints Environments Work](https://platform.claude.com/docs/pt-BR/api/beta/environments/work). ```go Go package main import ( "context" "encoding/json" "errors" "io" "log/slog" "net/http" "os" "os/signal" "syscall" "github.com/anthropics/anthropic-sdk-go" "github.com/anthropics/anthropic-sdk-go/lib/environments" "github.com/anthropics/anthropic-sdk-go/option" "github.com/anthropics/anthropic-sdk-go/packages/param" ) var ( environmentKey = os.Getenv("ANTHROPIC_ENVIRONMENT_KEY") environmentID = os.Getenv("ANTHROPIC_ENVIRONMENT_ID") client = anthropic.NewClient( option.WithAuthToken(environmentKey), option.WithWebhookKey(os.Getenv("ANTHROPIC_WEBHOOK_SIGNING_KEY")), ) worker = environments.NewEnvironmentWorker(client, environments.EnvironmentWorkerOptions{ Workdir: "/workspace", }) // Cancelado em SIGINT ou SIGTERM (definido em main) para que um item de trabalho em andamento possa // enviar arquivos de memória alterados e remover seus diretórios de store antes de sair. shutdown context.Context ) func handle(w http.ResponseWriter, r *http.Request) { body, err := io.ReadAll(r.Body) if err != nil { http.Error(w, "bad request", http.StatusBadRequest) return } event, err := client.Beta.Webhooks.Unwrap(body, r.Header) if err != nil { http.Error(w, "signature verification failed", http.StatusUnauthorized) return } if event.Data.Type != "session.status_run_started" { json.NewEncoder(w).Encode(map[string]string{"status": "ignored"}) return } // O SDK Go não fornece uma conveniência RunOne: drene os itens pendentes // com WorkPoller e execute cada um com HandleItem. // Desvincule de r.Context(): a sessão pode durar mais que o timeout de entrega do webhook. // O contexto de encerramento do processo ainda finaliza o item corretamente em SIGTERM. ctx := shutdown poller := environments.NewWorkPoller(ctx, client, environments.WorkPollerOptions{ EnvironmentID: environmentID, EnvironmentKey: environmentKey, BlockMs: param.Null[int64](), ReclaimOlderThanMs: param.NewOpt[int64](2000), Drain: true, AutoStop: param.NewOpt(false), }) defer poller.Close() for poller.Next() { item := poller.Current() if err := worker.HandleItem(ctx, environments.HandleItemOptions{ WorkID: item.ID, EnvironmentID: item.EnvironmentID, SessionID: item.Data.ID, EnvironmentKey: environmentKey, // O segredo por sessão é o que permite ao worker montar os stores de memória da sessão. WorkSecret: item.Secret, }); err != nil { slog.Error("handle work item", "work_id", item.ID, "err", err) http.Error(w, "internal error", http.StatusInternalServerError) return } } if err := poller.Err(); err != nil { slog.Error("poll work queue", "err", err) http.Error(w, "internal error", http.StatusInternalServerError) return } json.NewEncoder(w).Encode(map[string]string{"status": "ok"}) } func main() { ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM) defer stop() shutdown = ctx server := &http.Server{Addr: ":8080"} http.HandleFunc("POST /webhook", handle) go func() { if err := server.ListenAndServe(); err != nil && !errors.Is(err, http.ErrServerClosed) { slog.Error("http server", "err", err) os.Exit(1) } }() // Ao receber um sinal, pare de aceitar entregas e retorne somente após os handlers em andamento // e, portanto, a desmontagem de memória de seus itens de trabalho, terem terminado. <-ctx.Done() if err := server.Shutdown(context.Background()); err != nil { slog.Error("http shutdown", "err", err) } } ``` O SDK Java não possui `EnvironmentWorker`. Para processar itens de trabalho a partir do seu próprio código, chame os [endpoints Environments Work](https://platform.claude.com/docs/pt-BR/api/beta/environments/work). O SDK PHP não possui `EnvironmentWorker`. Para processar itens de trabalho a partir do seu próprio código, chame os [endpoints Environments Work](https://platform.claude.com/docs/pt-BR/api/beta/environments/work). O SDK Ruby não possui `EnvironmentWorker`. Para processar itens de trabalho a partir do seu próprio código, chame os [endpoints Environments Work](https://platform.claude.com/docs/pt-BR/api/beta/environments/work). Como o próprio handler reivindica o trabalho, ele deve [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), como o argumento `work_secret` (typescript: `workSecret`; go: `WorkSecret`) faz aqui. Este handler executa todos os itens reivindicados em um único processo em um único host. Se suas sessões anexam o mesmo memory store, consulte [Isolar sessões que compartilham um store](https://platform.claude.com/docs/pt-BR/managed-agents/self-hosted-sandboxes-memory#isolate-sessions-that-share-a-store). ## Executar um sandbox por sessão Um poller no host reivindica trabalho e chama seu script uma vez por item de trabalho. O script inicia um sandbox para essa única sessão. Instale o `ant` e defina `ant beta:worker run` como entrypoint. Quando um sandbox é iniciado, ele lê os detalhes da sessão a partir de variáveis de ambiente, processa essa sessão e encerra. A imagem base deve fornecer `/bin/bash`; o `curl` é usado apenas no momento do build. ```dockerfile FROM your-base-image ARG ANT_VERSION=1.42.0 ARG TARGETARCH RUN ARCH=$([ "$TARGETARCH" = "arm64" ] && echo arm64 || echo amd64) && \ curl -fsSL "https://github.com/anthropics/anthropic-cli/releases/download/v${ANT_VERSION}/ant_${ANT_VERSION}_linux_${ARCH}.tar.gz" \ | tar -xz -C /usr/local/bin ant WORKDIR /workspace VOLUME /workspace ENTRYPOINT ["ant", "beta:worker", "run"] ``` O script encaminha os detalhes da sessão para um sandbox novo. Ele requer `jq` no host do poller. ```bash #!/bin/bash # spawn.sh: chamado uma vez por item de trabalho reivindicado # O item de trabalho reivindicado chega como JSON via stdin. ANTHROPIC_WORK_SECRET="$(jq -r '.secret // empty')" export ANTHROPIC_WORK_SECRET mkdir -p "/host/outputs/$ANTHROPIC_SESSION_ID" exec docker run --rm \ -e ANTHROPIC_SESSION_ID -e ANTHROPIC_ENVIRONMENT_KEY \ -e ANTHROPIC_WORK_ID -e ANTHROPIC_ENVIRONMENT_ID -e ANTHROPIC_BASE_URL \ -e ANTHROPIC_WORK_SECRET \ -v "/host/outputs/$ANTHROPIC_SESSION_ID":/workspace \ your-image ``` O poller define as variáveis `ANTHROPIC_*` que o script encaminha, exceto o segredo. Consulte [Variáveis de ambiente](https://platform.claude.com/docs/pt-BR/managed-agents/self-hosted-sandboxes-reference#environment-variables). `/host/outputs` é um diretório do host que você escolhe. Montá-lo em `/workspace` permite recuperar os entregáveis da sessão depois que o sandbox encerra. A montagem também captura a árvore `skills/` baixada e quaisquer arquivos intermediários. ```bash ant beta:worker poll --on-work ./spawn.sh ``` ### Encaminhar o segredo do item de trabalho Cada item de trabalho reivindicado pode carregar um `secret` (csharp, go: `Secret`) por sessão, emitido pela Anthropic. O worker que executa a sessão precisa dele para montar [memory stores](https://platform.claude.com/docs/pt-BR/managed-agents/self-hosted-sandboxes-memory). Um worker que reivindica e executa sessões em um único processo (`ant beta:worker poll` sem `--on-work`, ou `EnvironmentWorker` com `run()` (go: `Run()`)) repassa o segredo por conta própria. Quando seu próprio código fica entre a reivindicação e o worker, você o encaminha: | Você reivindica trabalho com | O segredo chega como | Passe-o para o worker como | | ------------------------------------------------------------- | ---------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `ant beta:worker poll --on-work` | O campo `secret` do JSON do item de trabalho na entrada padrão do seu script | `ANTHROPIC_WORK_SECRET` no ambiente do sandbox | | O `work.poller()` (go: `environments.NewWorkPoller()`) do SDK | O campo `secret` (go: `Secret`) de cada item de trabalho reivindicado | `ANTHROPIC_WORK_SECRET` no ambiente do sandbox, ou o argumento `work_secret` (typescript: `workSecret`; go: `WorkSecret`) para `handle_item()` (typescript: `handleItem()`; go: `HandleItem()`) | Passe o segredo apenas para o sandbox que atende essa sessão e nunca o registre em logs. Consulte [Modelo de segurança](https://platform.claude.com/docs/pt-BR/managed-agents/self-hosted-sandboxes-security) para ver como ele se relaciona com a chave de ambiente. ### Iniciar sandboxes a partir do poller do SDK Para reivindicar trabalho a partir do seu próprio código em vez de `ant beta:worker poll --on-work`, use `work.poller()` (go: `environments.NewWorkPoller()`). Ele faz polling da fila e entrega cada sessão reivindicada, e você inicia o sandbox: Reivindicar trabalho em um loop e iniciar um sandbox para cada sessão exige mais lógica do que um único comando de shell. A partir do shell, execute `ant beta:worker poll --on-work` com um script de spawn, como em [Executar um sandbox por sessão](https://platform.claude.com/docs/pt-BR/managed-agents/self-hosted-sandboxes-workers#run-one-sandbox-per-session). Para reivindicar trabalho a partir do shell e iniciar um sandbox para cada sessão, execute `ant beta:worker poll --on-work` com um script de spawn, como em [Executar um sandbox por sessão](https://platform.claude.com/docs/pt-BR/managed-agents/self-hosted-sandboxes-workers#run-one-sandbox-per-session). ```python Python import asyncio import os from anthropic import AsyncAnthropic from anthropic.types.beta.environments import BetaSelfHostedWork SANDBOX_ENV = ( "ANTHROPIC_ENVIRONMENT_ID", "ANTHROPIC_ENVIRONMENT_KEY", "ANTHROPIC_WORK_ID", "ANTHROPIC_SESSION_ID", "ANTHROPIC_WORK_SECRET", "ANTHROPIC_BASE_URL", # forwarded only when set on this host ) async def launch_container(work: BetaSelfHostedWork) -> None: print(f"claimed session {work.data.id}") # Substitua `docker run` pelo seu próprio inicializador de sandbox. Repasse a chave do # ambiente (nunca sua chave de API) e o segredo por sessão do item de trabalho: o worker # interno precisa do segredo para montar os armazenamentos de memória da sessão. env = os.environ | { "ANTHROPIC_WORK_ID": work.id, "ANTHROPIC_SESSION_ID": work.data.id, "ANTHROPIC_WORK_SECRET": work.secret or "", } forward = [arg for name in SANDBOX_ENV for arg in ("-e", name)] launcher = await asyncio.create_subprocess_exec( "docker", "run", "--rm", "--detach", *forward, "your-image", env=env ) await launcher.wait() 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()) ``` ```typescript TypeScript import { spawn } from "node:child_process"; import { once } from "node:events"; import Anthropic from "@anthropic-ai/sdk"; import { WorkPoller } from "@anthropic-ai/sdk/helpers/beta/environments"; import type { BetaSelfHostedWork } from "@anthropic-ai/sdk/resources/beta/environments"; const SANDBOX_ENV = [ "ANTHROPIC_ENVIRONMENT_ID", "ANTHROPIC_ENVIRONMENT_KEY", "ANTHROPIC_WORK_ID", "ANTHROPIC_SESSION_ID", "ANTHROPIC_WORK_SECRET", "ANTHROPIC_BASE_URL" // forwarded only when set on this host ]; const environmentKey = process.env.ANTHROPIC_ENVIRONMENT_KEY!; const environmentId = process.env.ANTHROPIC_ENVIRONMENT_ID!; const client = new Anthropic({ authToken: environmentKey }); async function launchContainer(work: BetaSelfHostedWork): Promise { console.log(`claimed session ${work.data.id}`); // Substitua `docker run` pelo seu próprio inicializador de sandbox. Repasse a chave do // ambiente (nunca sua chave de API) e o segredo por sessão do item de trabalho: o worker // interno precisa do segredo para montar os armazenamentos de memória da sessão. const env = { ...process.env, ANTHROPIC_WORK_ID: work.id, ANTHROPIC_SESSION_ID: work.data.id, ANTHROPIC_WORK_SECRET: work.secret ?? "" }; const forward = SANDBOX_ENV.flatMap((name) => ["-e", name]); const launcher = spawn("docker", ["run", "--rm", "--detach", ...forward, "your-image"], { env, stdio: "inherit" }); await once(launcher, "close"); } const poller = new WorkPoller({ client, environmentId, environmentKey, autoStop: false // the launched sandbox owns the stop call }); for await (const work of poller) { await launchContainer(work); } ``` O SDK C# não possui um helper que faça polling de trabalho. Para reivindicar trabalho a partir do seu próprio código, chame os [endpoints Environments Work](https://platform.claude.com/docs/pt-BR/api/beta/environments/work). ```go Go package main import ( "context" "fmt" "log" "os" "os/exec" "github.com/anthropics/anthropic-sdk-go" "github.com/anthropics/anthropic-sdk-go/lib/environments" "github.com/anthropics/anthropic-sdk-go/option" "github.com/anthropics/anthropic-sdk-go/packages/param" ) var sandboxEnv = []string{ "ANTHROPIC_ENVIRONMENT_ID", "ANTHROPIC_ENVIRONMENT_KEY", "ANTHROPIC_WORK_ID", "ANTHROPIC_SESSION_ID", "ANTHROPIC_WORK_SECRET", "ANTHROPIC_BASE_URL", // forwarded only when set on this host } func launchContainer(ctx context.Context, work *anthropic.BetaSelfHostedWork) error { fmt.Printf("claimed session %s\n", work.Data.ID) // Substitua `docker run` pelo seu próprio inicializador de sandbox. Repasse a chave do // ambiente (nunca sua chave de API) e o segredo por sessão do item de trabalho: o worker // interno precisa do segredo para montar os armazenamentos de memória da sessão. args := []string{"run", "--rm", "--detach"} for _, name := range sandboxEnv { args = append(args, "-e", name) } launcher := exec.CommandContext(ctx, "docker", append(args, "your-image")...) launcher.Env = append(os.Environ(), "ANTHROPIC_WORK_ID="+work.ID, "ANTHROPIC_SESSION_ID="+work.Data.ID, "ANTHROPIC_WORK_SECRET="+work.Secret, ) launcher.Stdout, launcher.Stderr = os.Stdout, os.Stderr return launcher.Run() } func main() { environmentID := os.Getenv("ANTHROPIC_ENVIRONMENT_ID") environmentKey := os.Getenv("ANTHROPIC_ENVIRONMENT_KEY") client := anthropic.NewClient(option.WithAuthToken(environmentKey)) ctx := context.Background() poller := environments.NewWorkPoller(ctx, client, environments.WorkPollerOptions{ EnvironmentID: environmentID, EnvironmentKey: environmentKey, AutoStop: param.NewOpt(false), // the launched sandbox owns the stop call }) defer poller.Close() for work, err := range poller.All() { if err != nil { log.Fatal(err) } if err := launchContainer(ctx, work); err != nil { log.Fatal(err) } } } ``` O SDK Java não possui um helper que faça polling de trabalho. Para reivindicar trabalho a partir do seu próprio código, chame os [endpoints Environments Work](https://platform.claude.com/docs/pt-BR/api/beta/environments/work). O SDK PHP não possui um helper que faça polling de trabalho. Para reivindicar trabalho a partir do seu próprio código, chame os [endpoints Environments Work](https://platform.claude.com/docs/pt-BR/api/beta/environments/work). O SDK Ruby não possui um helper que faça polling de trabalho. Para reivindicar trabalho a partir do seu próprio código, chame os [endpoints Environments Work](https://platform.claude.com/docs/pt-BR/api/beta/environments/work). ### Executar o worker do SDK dentro do sandbox Substitua o entrypoint `ant beta:worker run` por um entrypoint do SDK quando o sandbox precisar [servir ferramentas personalizadas](https://platform.claude.com/docs/pt-BR/managed-agents/self-hosted-sandboxes-custom-tools) ou usar [configurações de sincronização de memória não padrão](https://platform.claude.com/docs/pt-BR/managed-agents/self-hosted-sandboxes-memory#configure-sync). O entrypoint constrói `EnvironmentWorker` e chama `handle_item()` (typescript: `handleItem()`; go: `HandleItem()`), que lê as mesmas variáveis `ANTHROPIC_*` que o script de spawn encaminha. ```python Python import asyncio import contextlib import os import signal from anthropic import AsyncAnthropic from anthropic.lib.environments import EnvironmentWorker async def main() -> None: async with AsyncAnthropic( auth_token=os.environ["ANTHROPIC_ENVIRONMENT_KEY"] ) as client: worker = EnvironmentWorker(client, workdir="/workspace") # Sem argumentos, handle_item() lê as variáveis ANTHROPIC_* que o script de spawn # encaminhou, incluindo ANTHROPIC_WORK_SECRET. task = asyncio.create_task(worker.handle_item()) # Cancelar a tarefa quando o contêiner é parado permite que o worker envie # os arquivos de memória alterados e remova os diretórios de armazenamento antes de sair. 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()) ``` ```typescript TypeScript import Anthropic from "@anthropic-ai/sdk"; import { EnvironmentWorker } from "@anthropic-ai/sdk/helpers/beta/environments"; const client = new Anthropic({ authToken: process.env.ANTHROPIC_ENVIRONMENT_KEY }); const controller = new AbortController(); // Abortar quando o contêiner é parado permite que o worker envie os arquivos de memória // alterados e remova os diretórios de armazenamento antes de sair. process.once("SIGTERM", () => controller.abort()); process.once("SIGINT", () => controller.abort()); // Sem argumentos, handleItem() lê as variáveis ANTHROPIC_* que o script de spawn // encaminhou, incluindo ANTHROPIC_WORK_SECRET. await new EnvironmentWorker({ client, workdir: "/workspace", signal: controller.signal }).handleItem(); ``` O SDK C# não possui `EnvironmentWorker`. ```go Go package main import ( "context" "log" "os" "os/signal" "syscall" "github.com/anthropics/anthropic-sdk-go" "github.com/anthropics/anthropic-sdk-go/lib/environments" "github.com/anthropics/anthropic-sdk-go/option" ) func main() { // Cancelar o contexto quando o contêiner é parado permite que o worker envie // arquivos de memória alterados e remova os diretórios do store antes de sair. ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM) defer stop() client := anthropic.NewClient(option.WithAuthToken(os.Getenv("ANTHROPIC_ENVIRONMENT_KEY"))) worker := environments.NewEnvironmentWorker(client, environments.EnvironmentWorkerOptions{ Workdir: "/workspace", }) // Com opções de valor zero, HandleItem lê as variáveis ANTHROPIC_* que o script // de spawn encaminhou, incluindo ANTHROPIC_WORK_SECRET. if err := worker.HandleItem(ctx, environments.HandleItemOptions{}); err != nil { log.Fatalf("worker: %v", err) } } ``` O SDK Java não possui `EnvironmentWorker`. O SDK PHP não possui `EnvironmentWorker`. O SDK Ruby não possui `EnvironmentWorker`. ## Preparar arquivos para uma sessão A Anthropic não monta arquivos nem repositórios do GitHub em sandboxes auto-hospedados. Para disponibilizar arquivos específicos da sessão: 1. Passe referências de arquivos, como um caminho do S3 ou um SHA de commit, no campo `metadata` da sessão. 2. No seu script de spawn ou handler `--on-work`, recupere a sessão (`GET /v1/sessions/{session_id}`) e leia `metadata`. O item de trabalho reivindicado carrega o ID da sessão, mas não os metadados. 3. Prepare os arquivos no diretório de trabalho antes que a execução das ferramentas comece. ```bash cURL curl -sS --fail-with-body https://api.anthropic.com/v1/sessions \ -H "x-api-key: $ANTHROPIC_API_KEY" \ -H "anthropic-version: 2023-06-01" \ -H "anthropic-beta: managed-agents-2026-04-01" \ -H "content-type: application/json" \ -d '{ "agent": "'"$AGENT_ID"'", "environment_id": "'"$ANTHROPIC_ENVIRONMENT_ID"'", "metadata": {"input_file": "s3://my-bucket/data.csv"} }' ``` ```bash CLI ant beta:sessions create \ --agent "$AGENT_ID" \ --environment-id "$ANTHROPIC_ENVIRONMENT_ID" \ --metadata '{"input_file": "s3://my-bucket/data.csv"}' ``` ```python Python session = client.beta.sessions.create( agent=agent.id, environment_id=environment.id, metadata={"input_file": "s3://my-bucket/data.csv"}, ) ``` ```typescript TypeScript const session = await client.beta.sessions.create({ agent: agent.id, environment_id: environment.id, metadata: { input_file: "s3://my-bucket/data.csv" } }); ``` ```csharp C# var session = await client.Beta.Sessions.Create(new() { Agent = agent.ID, EnvironmentID = environment.ID, Metadata = new Dictionary { ["input_file"] = "s3://my-bucket/data.csv" }, }); ``` ```go Go session, err := client.Beta.Sessions.New(ctx, anthropic.BetaSessionNewParams{ Agent: anthropic.BetaSessionNewParamsAgentUnion{OfString: anthropic.String(agent.ID)}, EnvironmentID: environment.ID, Metadata: map[string]string{ "input_file": "s3://my-bucket/data.csv", }, }) if err != nil { panic(err) } ``` ```java Java var session = client.beta().sessions().create(SessionCreateParams.builder() .agent(agent.id()) .environmentId(environment.id()) .metadata(SessionCreateParams.Metadata.builder() .putAdditionalProperty("input_file", JsonValue.from("s3://my-bucket/data.csv")) .build()) .build()); ``` ```php PHP $session = $client->beta->sessions->create( agent: $agent->id, environmentID: $environment->id, metadata: ['input_file' => 's3://my-bucket/data.csv'], ); ``` ```ruby Ruby session = client.beta.sessions.create( agent: agent.id, environment_id: environment.id, metadata: {input_file: "s3://my-bucket/data.csv"} ) ``` ## Próximos passos Leia a profundidade da fila, encerre sessões e workers de forma limpa e corrija falhas comuns. Modelo de responsabilidade compartilhada para ambientes de sandbox auto-hospedados.