---
title: Executar um sandbox por sessão
url: https://platform.claude.com/docs/pt-BR/managed-agents/self-hosted-sandboxes-per-session
description: Dê a cada sessão seu próprio sandbox auto-hospedado com o Helm chart no Kubernetes, um script de spawn ou o poller 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
  zdr:
    eligibility: not-eligible
    note: Não é elegível para ZDR, exceto o Managed Agents auto-hospedado. Sessões são recursos com estado; as transcrições persistem até que você as exclua.
  supportedModels:
    - claude-fable-5-2
    - claude-mythos-5-2
    - claude-fable-5-1
    - claude-mythos-5-1
    - claude-fable-5
    - claude-mythos-5
    - claude-mythos-preview
    - claude-opus-5-5
    - claude-opus-5
    - claude-sonnet-5-5
    - claude-sonnet-5
    - claude-haiku-5-5
    - claude-haiku-4-5-20251001
    - claude-opus-4-8
    - claude-opus-4-7
    - claude-opus-4-6
    - claude-sonnet-4-6
    - claude-opus-4-5-20251101
    - claude-sonnet-4-5-20250929
  supportedPlatforms:
    Claude API: beta
    Claude Platform on AWS: beta
---

No padrão de sandbox por sessão, cada sessão é executada em um sandbox novo, que pode ter seu próprio sistema de arquivos, limites de recursos e controles de rede. Para compará-lo com os outros padrões, consulte [Escolher um padrão de implantação](https://platform.claude.com/docs/pt-BR/managed-agents/self-hosted-sandboxes-workers#choose-a-deployment-pattern).

Você pode configurá-lo de três maneiras:

* **[Helm chart no Kubernetes](https://platform.claude.com/docs/pt-BR/managed-agents/self-hosted-sandboxes-per-session#run-sandboxes-on-kubernetes):** O dispatcher da Anthropic reivindica o trabalho e inicia um pod para cada sessão no seu cluster.
* **[Script de spawn](https://platform.claude.com/docs/pt-BR/managed-agents/self-hosted-sandboxes-per-session#launch-sandboxes-with-a-spawn-script):** A CLI `ant` reivindica o trabalho e chama seu script, que inicia um sandbox em qualquer plataforma.
* **[Poller do SDK](https://platform.claude.com/docs/pt-BR/managed-agents/self-hosted-sandboxes-per-session#launch-sandboxes-from-the-sdk-poller):** Seu próprio código reivindica o trabalho e inicia o sandbox.

As seções após [Executar sandboxes no Kubernetes](https://platform.claude.com/docs/pt-BR/managed-agents/self-hosted-sandboxes-per-session#run-sandboxes-on-kubernetes) se aplicam ao script de spawn e ao poller do SDK.

## Executar sandboxes no Kubernetes

A Anthropic publica um Helm chart, `cma-sandboxes`, e suas imagens. O chart executa um sandbox por sessão no seu próprio cluster Kubernetes. Seu dispatcher consulta a fila de trabalho do ambiente e dá a cada sessão um pod próprio:

* **Isolamento:** Cada pod é executado sob o [gVisor](https://gvisor.dev/), protegido pelas políticas de rede do chart. Ele tem seu próprio sistema de arquivos e limites de recursos. Apenas o dispatcher detém a chave do ambiente.
* **Afinidade de sessão:** Cada mensagem de uma sessão vai para o sandbox dessa sessão. Depois que a sessão fica ociosa por 30 minutos (o padrão da configuração `sandbox.idleTimeout` do chart), seu pod é parado. Seu volume `/workspace` permanece até o fim da sessão. A próxima mensagem inicia um pod no mesmo volume.
* **Pool pré-aquecido:** Exceto no Google Kubernetes Engine (GKE), o chart mantém dois pods prontos para novas sessões (o padrão da configuração `sandbox.warmPoolSize` do chart).

Os pods de sandbox executam o worker da CLI `ant`. Eles oferecem suporte a [memory stores](https://platform.claude.com/docs/pt-BR/managed-agents/self-hosted-sandboxes-memory) com as configurações de sincronização padrão e não oferecem suporte a [ferramentas personalizadas](https://platform.claude.com/docs/pt-BR/managed-agents/self-hosted-sandboxes-custom-tools).

### Instalar o chart

O chart é executado no GKE, no Amazon EKS e em outros clusters. Configure o seguinte antes de instalá-lo:

* **No cluster:** O controlador [Agent Sandbox](https://github.com/kubernetes-sigs/agent-sandbox) (no GKE, o complemento Agent Sandbox), nós que executam o gVisor e um plugin de rede que aplique NetworkPolicy.
* **No seu próprio namespace:** Rótulos do Pod Security Standard restrito, um Secret com o ID do ambiente e a [chave do ambiente](https://platform.claude.com/docs/pt-BR/managed-agents/self-hosted-sandboxes#run-your-first-session) e o certificado TLS do dispatcher.

O [guia de instalação no GitHub](https://github.com/anthropics/anthropic-cli/blob/main/sandboxes/kubernetes/README.md) tem as etapas de configuração para cada tipo de cluster. Ele também aborda atualizações e rotação de chaves.

Salve suas configurações como `cma-values.yaml`. A instalação falha sem as três configurações deste arquivo:

<File filename="cma-values.yaml">
  ```yaml
  platform: gke             # or eks, or generic for any other cluster
  egress:
    # The chart already blocks the private ranges. List your other addresses
    # that sandboxes must not reach.
    clusterCIDRs:
      - 203.0.113.10/32     # your cluster's Kubernetes API endpoint
    cmaServer:
      public: true          # the Claude API has a public address
  ```
</File>

O guia de instalação lista as configurações que dependem do seu cluster, como `gke.dns` no GKE Autopilot. Ele também informa quando `egress.clusterIsPrivate: true` substitui `egress.clusterCIDRs`.

Em seguida, instale o chart:

```bash
helm install cma \
  oci://us-docker.pkg.dev/anthropic-public-registry/sandboxes/charts/cma-sandboxes \
  --version 0.1.0 \
  --namespace cma \
  -f cma-values.yaml \
  --wait
```

Após a instalação, execute a verificação prévia descrita no guia de instalação.

<Warning>
  Não remova o chart apenas com `helm uninstall`. Esse comando exclui as políticas de rede e deixa os sandboxes das sessões em execução sem elas. Pare o dispatcher e exclua os sandboxes primeiro, na ordem indicada pela [seção Removal do guia de instalação](https://github.com/anthropics/anthropic-cli/blob/main/sandboxes/kubernetes/README.md#removal).
</Warning>

### Adicionar ferramentas à imagem do sandbox

A imagem de sandbox publicada é Alpine Linux com `bash`, `curl`, `jq` e a CLI `ant`. O chart a executa com um sistema de arquivos raiz somente leitura e como um usuário não root, então um agente não pode instalar pacotes durante uma sessão.

Para dar mais ferramentas aos seus agentes, como Python ou Git, crie as duas imagens a partir do repositório na tag da versão. A [seção Install do guia de instalação](https://github.com/anthropics/anthropic-cli/blob/main/sandboxes/kubernetes/README.md#install) tem os comandos. Envie as imagens para o seu registro como `cma-dispatcher` e `cma-sandbox`, com a versão do chart como tag. Em seguida, defina `image.registry` como esse registro. Se você fixar digests de imagem, use os digests das suas próprias imagens.

### Restringir o egress de rede

Por padrão, as políticas de rede do chart permitem que um sandbox alcance a internet IPv4 pública. Elas bloqueiam intervalos de endereços privados, o servidor de metadados da nuvem e os endereços em `egress.clusterCIDRs`. Um agente que sofreu prompt injection pode enviar o que lê para qualquer endereço que seu sandbox consiga alcançar. [Network egress](https://github.com/anthropics/anthropic-cli/blob/main/sandboxes/kubernetes/README.md#network-egress) no guia de instalação tem os detalhes.

* **GKE com Dataplane V2:** Defina `egress.mode: fqdnGke` para limitar as conexões à porta 443 nos hosts em `egress.fqdnGke.hosts`. Mantenha `api.anthropic.com` nessa lista e adicione todos os hosts de que os comandos dos seus agentes precisam. Ao contrário do padrão, esse modo não tem uma lista de intervalos bloqueados. Ele permite qualquer endereço para o qual o nome de um host listado seja resolvido, então liste apenas hosts cujo DNS seja confiável para você. Um sandbox ainda pode enviar dados para fora dentro de consultas DNS.
* **Outros clusters e GKE sem Dataplane V2:** O padrão é o único modo.
* **Todos os clusters:** As políticas de rede não cobrem as portas nas quais os próprios nós do cluster escutam. Consulte [Node isolation you own](https://github.com/anthropics/anthropic-cli/blob/main/sandboxes/kubernetes/README.md#node-isolation-you-own) no guia de instalação.

## Iniciar sandboxes com um script de spawn

Um poller no host reivindica o trabalho e chama seu script uma vez para cada item de trabalho. O script inicia um sandbox para essa única sessão.

<Steps>
  <Step title="Criar a imagem do sandbox">
    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, atende a essa sessão e encerra. A imagem base deve fornecer `/bin/bash`; a compilação usa `curl` apenas para baixar o `ant`.

    <File filename="Dockerfile">
      ```dockerfile
      FROM your-base-image
      ARG ANT_VERSION=2.11.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"]
      ```
    </File>
  </Step>

  <Step title="Escrever o script de spawn">
    O script encaminha os detalhes da sessão para um sandbox novo. Ele requer `jq` no host do poller.

    <File filename="spawn.sh">
      ```bash
      #!/bin/bash
      # spawn.sh: chamado uma vez para cada item de trabalho reivindicado
      # O item de trabalho reivindicado chega como JSON pelo 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
      ```
    </File>

    O poller define `ANTHROPIC_WORK_ID`, `ANTHROPIC_ENVIRONMENT_ID`, `ANTHROPIC_SESSION_ID` e `ANTHROPIC_ENVIRONMENT_KEY`. `ANTHROPIC_BASE_URL` só chega ao script se você a definir no host do poller. O script lê `ANTHROPIC_WORK_SECRET` do JSON do item de trabalho na entrada padrão. 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 inclui a árvore `skills/` baixada e quaisquer arquivos intermediários.
  </Step>

  <Step title="Iniciar o poller">
    ```bash
    ant beta:worker poll --on-work ./spawn.sh
    ```
  </Step>
</Steps>

## Encaminhar o segredo do item de trabalho

Cada item de trabalho reivindicado pode conter um `secret` (csharp, go: `Secret`) que a Anthropic emite para essa sessão. 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 repassa o segredo por conta própria. `EnvironmentWorker` com `run()` (go: `Run()`) é um desses workers, e `ant beta:worker poll` sem `--on-work` é outro. Quando seu próprio código fica entre a reivindicação e o worker, você encaminha o segredo:

| Você reivindica trabalho com                                                                                              | O segredo chega como                                                         | Repasse-o ao 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                                                                                                                                               |
| `work.poller()` (typescript: `new WorkPoller()`; go: `environments.NewWorkPoller()`) do SDK para Python, TypeScript ou Go | 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`) de `handle_item()` (typescript: `handleItem()`; go: `HandleItem()`) |

Repasse o segredo apenas para o sandbox que atende a essa sessão e nunca o registre em log. Consulte [Modelo de segurança](https://platform.claude.com/docs/pt-BR/managed-agents/self-hosted-sandboxes-security) para saber como ele se relaciona com a chave do 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 o poller do SDK para Python, TypeScript ou Go: `work.poller()` (typescript: `new WorkPoller()`; go: `environments.NewWorkPoller()`). Ele consulta a fila e entrega a você cada sessão reivindicada, e você inicia o sandbox:

<CodeGroup exclude="shell, csharp, java, php, ruby">
  <CodeGroupItem language="cURL">
    Reivindicar trabalho em um loop e iniciar um sandbox para cada sessão exige mais lógica do que um único comando de shell. No shell, execute `ant beta:worker poll --on-work` com um script de spawn, como em [Iniciar sandboxes com um script de spawn](https://platform.claude.com/docs/pt-BR/managed-agents/self-hosted-sandboxes-per-session#launch-sandboxes-with-a-spawn-script).
  </CodeGroupItem>

  <CodeGroupItem language="CLI">
    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. Consulte [Iniciar sandboxes com um script de spawn](https://platform.claude.com/docs/pt-BR/managed-agents/self-hosted-sandboxes-per-session#launch-sandboxes-with-a-spawn-script).
  </CodeGroupItem>

  ```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 memory stores 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<void> {
    console.log(`claimed session ${work.data.id}`);
    // Substitua `docker run` pelo seu próprio inicializador de sandbox. Encaminhe 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 memory stores 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);
  }
  ```

  <CodeGroupItem language="C#">
    O SDK para C# não tem um helper que consulta trabalho. Para reivindicar trabalho a partir do seu próprio código, chame os [endpoints de Environments Work](https://platform.claude.com/docs/pt-BR/api/beta/environments/work) para consultar um item e confirmá-lo.
  </CodeGroupItem>

  ```go Go
  package main

  import (
  	"context"
  	"fmt"
  	"log"
  	"os"
  	"os/exec"

  	"github.com/anthropics/anthropic-sdk-go/v2"
  	"github.com/anthropics/anthropic-sdk-go/v2/lib/environments"
  	"github.com/anthropics/anthropic-sdk-go/v2/option"
  	"github.com/anthropics/anthropic-sdk-go/v2/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. Encaminhe 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 memory stores 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)
  		}
  	}
  }
  ```

  <CodeGroupItem language="Java">
    O SDK para Java não tem um helper que consulta trabalho. Para reivindicar trabalho a partir do seu próprio código, chame os [endpoints de Environments Work](https://platform.claude.com/docs/pt-BR/api/beta/environments/work) para consultar um item e confirmá-lo.
  </CodeGroupItem>

  <CodeGroupItem language="PHP">
    O SDK para PHP não tem um helper que consulta trabalho. Para reivindicar trabalho a partir do seu próprio código, chame os [endpoints de Environments Work](https://platform.claude.com/docs/pt-BR/api/beta/environments/work) para consultar um item e confirmá-lo.
  </CodeGroupItem>

  <CodeGroupItem language="Ruby">
    O SDK para Ruby não tem um helper que consulta trabalho. Para reivindicar trabalho a partir do seu próprio código, chame os [endpoints de Environments Work](https://platform.claude.com/docs/pt-BR/api/beta/environments/work) para consultar um item e confirmá-lo.
  </CodeGroupItem>
</CodeGroup>

## 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.

<CodeGroup exclude="shell, csharp, java, php, ruby">
  <CodeGroupItem language="cURL">
    Um worker é um processo de longa duração, não uma única requisição HTTP. Para servir ferramentas personalizadas ou alterar as configurações de sincronização de memória, use `EnvironmentWorker` no SDK para Python, TypeScript ou Go.
  </CodeGroupItem>

  <CodeGroupItem language="CLI">
    O worker da CLI `ant` (`ant beta:worker run`) não pode servir ferramentas personalizadas nem alterar as configurações de sincronização de memória. Para fazer qualquer uma dessas coisas, use `EnvironmentWorker` no SDK para Python, TypeScript ou Go.
  </CodeGroupItem>

  ```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 do store antes de encerrar.
          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 do store antes de encerrar.
  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();
  ```

  <CodeGroupItem language="C#">
    O SDK para C# não tem `EnvironmentWorker`.
  </CodeGroupItem>

  ```go Go
  package main

  import (
  	"context"
  	"log"
  	"os"
  	"os/signal"
  	"syscall"

  	"github.com/anthropics/anthropic-sdk-go/v2"
  	"github.com/anthropics/anthropic-sdk-go/v2/lib/environments"
  	"github.com/anthropics/anthropic-sdk-go/v2/option"
  )

  func main() {
  	// Cancelar o contexto quando o contêiner é parado permite que o worker envie
  	// os arquivos de memória alterados e remova os diretórios do store antes de encerrar.
  	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)
  	}
  }
  ```

  <CodeGroupItem language="Java">
    O SDK para Java não tem `EnvironmentWorker`.
  </CodeGroupItem>

  <CodeGroupItem language="PHP">
    O SDK para PHP não tem `EnvironmentWorker`.
  </CodeGroupItem>

  <CodeGroupItem language="Ruby">
    O SDK para Ruby não tem `EnvironmentWorker`.
  </CodeGroupItem>
</CodeGroup>

## 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` (csharp, go: `Metadata`) da sessão.
2. No seu script de spawn ou handler de `--on-work`, recupere a sessão (`GET /v1/sessions/{session_id}`) e leia `metadata` (csharp, go: `Metadata`). O item de trabalho reivindicado contém o ID da sessão, mas não os metadados.
3. Prepare os arquivos no diretório de trabalho antes que qualquer ferramenta seja executada.

O exemplo em cURL lê um “access token” (token de acesso) de `ANTHROPIC_AUTH_TOKEN`. Para obter um, configure a Workload Identity Federation com o escopo padrão `workspace:developer`, conforme descrito em [Configurar a federação](https://platform.claude.com/docs/pt-BR/manage-claude/workload-identity-federation#set-up-federation). Em seguida, troque o token de identidade da sua carga de trabalho por um token de acesso, conforme mostrado em [Autenticar a partir da sua carga de trabalho](https://platform.claude.com/docs/pt-BR/manage-claude/workload-identity-federation#authenticate-from-your-workload). Defina `ANTHROPIC_AUTH_TOKEN` apenas no shell em que você executar o exemplo em cURL, porque ele tem precedência sobre suas configurações de federação. [Autenticação](https://platform.claude.com/docs/pt-BR/manage-claude/authentication) lista as outras credenciais que a API aceita, como a chave de API do início rápido.

<CodeGroup>
  ```bash cURL
  curl -sS --fail-with-body https://api.anthropic.com/v1/sessions \
    -H "authorization: Bearer $ANTHROPIC_AUTH_TOKEN" \
    -H "anthropic-version: 2026-10-21" \
    -H "anthropic-beta: managed-agents-2026-04-01" \
    -H "content-type: application/json" \
    -d '{
      "agent": "agent_011CYm1BLqPXpQRk5khsSXrs",
      "environment_id": "env_01595EKxaaTTGwwY3kyXdtbs",
      "metadata": {"input_file": "s3://my-bucket/data.csv"}
    }'
  ```

  ```bash CLI
  ant beta:sessions create \
    --agent agent_011CYm1BLqPXpQRk5khsSXrs \
    --environment-id env_01595EKxaaTTGwwY3kyXdtbs \
    --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<string, string> { ["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"}
  )
  ```
</CodeGroup>

## Próximos passos

<CardGroup cols={2}>
  <Card title="Monitorar e solucionar problemas de workers auto-hospedados" icon="lightning" href="https://platform.claude.com/docs/pt-BR/managed-agents/self-hosted-sandboxes-operations">
    Leia a profundidade da fila, pare sessões e workers de forma controlada e corrija falhas comuns.
  </Card>
</CardGroup>
