---
title: Riferimento per i worker self-hosted
url: https://platform.claude.com/docs/it/managed-agents/self-hosted-sandboxes-reference
description: "Riferimento per i worker di sandbox self-hosted: flag della CLI ant, variabili d'ambiente, requisiti dell'host, percorsi del filesystem e opzioni degli helper dell'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: Non idoneo per ZDR, ad eccezione di Managed Agents self-hosted. Le sessioni sono risorse con stato; le trascrizioni restano finché non le elimini.
  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
---

Questa pagina documenta i worker predefiniti che servono un ambiente `self_hosted`. Per guide orientate alle attività, inizia con [Sandbox self-hosted](https://platform.claude.com/docs/it/managed-agents/self-hosted-sandboxes) e [Distribuire worker self-hosted](https://platform.claude.com/docs/it/managed-agents/self-hosted-sandboxes-workers).

## Comandi e flag della CLI

| Comando | Descrizione |
| ----- | ----- |
| `ant beta:worker poll` | Acquisisce gli elementi di lavoro dalla coda dell’ambiente ed esegue ogni sessione nel processo. Con `--on-work`, chiama invece il tuo script per ogni elemento di lavoro. |
| `ant beta:worker run` | Gestisce una singola sessione acquisita e termina. Usalo come entrypoint di una sandbox per sessione. |

| Flag | Descrizione |
| ----- | ----- |
| `--environment-id` | L’ambiente da interrogare per il lavoro. Viene letto anche da `ANTHROPIC_ENVIRONMENT_ID`. |
| `--environment-key` | Autentica il worker con questo ambiente. Viene letto anche da `ANTHROPIC_ENVIRONMENT_KEY`. |
| `--workdir` | Directory in cui il worker scarica le skill e in cui gli strumenti leggono e scrivono file. Il valore predefinito è `.` (la directory corrente). La directory deve esistere prima dell’avvio del worker. |
| `--on-work` | Script da chiamare per ogni elemento di lavoro acquisito invece di eseguire gli strumenti nel processo. Riceve i dettagli della sessione come variabili d’ambiente e l’elemento di lavoro come JSON sullo standard input. |
| `--max-idle` | Quanto tempo il worker attende mentre una sessione è inattiva prima che `ant beta:worker run` termini o che `ant beta:worker poll` passi all’elemento di lavoro successivo. Il tempo di inattività con uno [stop reason `requires_action`](https://platform.claude.com/docs/it/managed-agents/events-and-streaming#respond-when-the-session-goes-idle) (motivo di arresto) non viene conteggiato. Il valore predefinito è `60s`. Impostalo su `0` per disattivare il timeout. Con uno script `--on-work`, `ant beta:worker poll` ignora questo flag. Passalo invece al comando `ant beta:worker run` avviato dal tuo script. |
| `--log-format` | Formato dell’output dei log. Usa `json` per l’acquisizione di log strutturati. Il valore predefinito è `text`. |

## Variabili d’ambiente

| Variabile | Descrizione | Impostata da |
| ----- | ----- | ----- |
| `ANTHROPIC_ENVIRONMENT_ID` | L’ambiente la cui coda viene servita dal worker. | Te, sull’host del worker. Il poller la passa allo script `--on-work`. |
| `ANTHROPIC_ENVIRONMENT_KEY` | Autentica il worker presso la sua coda. | Te, sull’host del worker. Il poller la passa allo script `--on-work`. |
| `ANTHROPIC_SESSION_ID` | La sessione rappresentata da un elemento di lavoro acquisito. | Il poller, per lo script `--on-work`. |
| `ANTHROPIC_WORK_ID` | L’elemento di lavoro acquisito. | Il poller, per lo script `--on-work`. |
| `ANTHROPIC_WORK_SECRET` | Il segreto dell’elemento di lavoro per la sua sessione. | Te. Il poller non la imposta. Consulta [Inoltra il segreto dell’elemento di lavoro](https://platform.claude.com/docs/it/managed-agents/self-hosted-sandboxes-per-session#forward-the-work-items-secret). |
| `ANTHROPIC_BASE_URL` | Sovrascrive l’endpoint API predefinito. Facoltativa. | Te, sull’host del worker. |
| `ANTHROPIC_WEBHOOK_SIGNING_KEY` | Verifica i payload dei webhook in arrivo. | Te, su un host che gestisce i webhook. |

## Requisiti dell’host

| Worker | Requisito |
| ----- | ----- |
| Tutti i worker | Un host Linux o macOS con `/bin/bash` esattamente in quel percorso. Lo strumento `bash` del worker lo esegue direttamente, senza consultare `PATH`. Su macOS, si tratta del Bash 3.2 di sistema. |
| SDK TypeScript | `unzip` e `tar` nel `PATH`, e Node.js 22 o successivo. |
| SDK Python e Go | Nessun binario aggiuntivo. Questi SDK usano le proprie librerie standard per l’estrazione degli archivi. |

I [memory store](https://platform.claude.com/docs/it/managed-agents/self-hosted-sandboxes-memory#requirements) aggiungono i propri requisiti.

Su macOS, il volume radice è di sola lettura, quindi `mkdir` non può creare `/workspace`. Imposta la directory di lavoro del worker su una in cui puoi scrivere, come una directory `workspace` nella tua home directory. Per usare gli archivi di memoria su macOS, prima [prepara l’host macOS](https://platform.claude.com/docs/it/managed-agents/self-hosted-sandboxes-memory#prepare-a-macos-host).

## Filesystem della sandbox

| Percorso | Contenuto |
| ----- | ----- |
| `/workspace` | La directory di lavoro usata negli esempi delle pagine sulle sandbox self-hosted. Non è quella predefinita del worker: il worker usa la directory corrente a meno che tu non imposti `--workdir` o `workdir` (go: `Workdir`). Le sandbox cloud di Anthropic conservano skill e repository in `/workspace`. Se usi una directory di lavoro diversa, aggiorna il prompt di sistema del tuo agente in modo che Claude possa individuare i file delle skill. |
| `<workdir>/skills/<name>/` | Le skill scaricate dell’agente. |
| `/mnt/memory/<store>/` | Una copia locale di ogni memory store collegato, una directory per store. L’API restituisce il percorso completo di ogni directory nel campo `mount_path` (java, php: `mountPath`; csharp, go: `MountPath`) della risorsa memory store della sessione (ad esempio, `/mnt/memory/user-preferences/`). |

Il worker crea le directory dei memory store quando acquisisce una sessione. Le rimuove quando ha finito con quella sessione o quando [arresti il worker in modo controllato](https://platform.claude.com/docs/it/managed-agents/self-hosted-sandboxes-operations#stop-workers-gracefully). Questo rimuove solo le copie locali, e le memorie restano nello store.

Le skill possono includere eseguibili che l’agente può eseguire direttamente. I worker della CLI e dell’SDK preservano i permessi di esecuzione registrati nel bundle della skill quando lo estraggono. Se scarichi le skill autonomamente, imposta tu stesso i loro permessi di esecuzione.

### Quando il worker ha finito con una sessione

Il worker ha finito con una sessione in uno qualsiasi di questi casi:

* La sessione termina.
* [Arresti l’elemento di lavoro della sessione](https://platform.claude.com/docs/it/managed-agents/self-hosted-sandboxes-operations#stop-a-session-gracefully).
* La sessione resta inattiva per tutto il limite di inattività del worker. La sessione stessa resta aperta. Quando poi le invii un nuovo evento, come un messaggio dell’utente, lo stesso worker o un altro la acquisisce. Quel worker scarica di nuovo gli store.

Il limite di inattività è di 60 secondi per impostazione predefinita. Per modificarlo, usa [`--max-idle`](https://platform.claude.com/docs/it/managed-agents/self-hosted-sandboxes-reference#cli-commands-and-flags) per il worker della CLI `ant` o [`max_idle` (typescript: `maxIdleMs`; go: `MaxIdle`)](https://platform.claude.com/docs/it/managed-agents/self-hosted-sandboxes-reference#environment-worker) per `EnvironmentWorker`. Il [chart Helm `cma-sandboxes`](https://platform.claude.com/docs/it/managed-agents/self-hosted-sandboxes-per-session#run-sandboxes-on-kubernetes) avvia invece i suoi worker con un limite di 30 minuti. Per modificare quel limite, modifica l’impostazione `sandbox.idleTimeout` del chart.

### Risultati finali

Le sandbox self-hosted non hanno una directory `/mnt/session/outputs`. Nelle sandbox cloud di Anthropic, il prompt di sistema della sessione indica all’agente di copiarvi i risultati finali. Negli ambienti self-hosted, il prompt di sistema omette quell’istruzione. I risultati finali restano ovunque l’agente li scriva, in genere sotto la directory di lavoro, e il worker non li carica.

Per raccogliere i risultati finali in un unico posto, indica il percorso completo di una directory nel prompt di sistema del tuo agente. Scegli una directory in cui gli strumenti per i file del worker possano scrivere:

* **All’interno della directory di lavoro:** ad esempio, `/workspace/outputs` se la directory di lavoro è `/workspace`.
* **In qualsiasi altro posto, solo con un worker dell’SDK:** aggiungi la directory a `allowed_roots` (typescript: `allowedRoots`; go: `AllowedRoots`). Consulta [AgentToolContext e il toolset dell’agente](https://platform.claude.com/docs/it/managed-agents/self-hosted-sandboxes-reference#agent-tool-context-and-the-agent-toolset).

## Helper dell’SDK

Gli SDK Python, TypeScript e Go forniscono tre helper con diversi livelli di controllo:

| Helper | Cosa fa | Quando usarlo |
| ----- | ----- | ----- |
| [`EnvironmentWorker`](https://platform.claude.com/docs/it/managed-agents/self-hosted-sandboxes-reference#environment-worker) | Gestisce polling, configurazione ed esecuzione degli strumenti dall’inizio alla fine. | Nella maggior parte dei casi. |
| [`work.poller()` (typescript: `new WorkPoller()`; go: `environments.NewWorkPoller()`)](https://platform.claude.com/docs/it/managed-agents/self-hosted-sandboxes-reference#work-poller) | Interroga la coda di lavoro e ti fornisce ogni sessione acquisita. | Decidi tu come gestire ogni sessione, ad esempio avviando una sandbox invece di eseguire gli strumenti nel processo. |
| [`client.beta.sessions.events.tool_runner()` (typescript: `client.beta.sessions.events.toolRunner()`; go: `client.Beta.Sessions.Events.NewToolRunner()`)](https://platform.claude.com/docs/it/managed-agents/self-hosted-sandboxes-reference#session-tool-runner) | Esegue le chiamate agli strumenti per una singola sessione, dati l’ID della sessione e un elenco di strumenti. | Hai già acquisito il lavoro e ti serve solo eseguire gli strumenti. |

### EnvironmentWorker

| Metodo | Descrizione |
| ----- | ----- |
| `run()` (go: `Run()`) | Viene eseguito indefinitamente, prendendo in carico le sessioni man mano che arrivano. |
| `handle_item()` (typescript: `handleItem()`; go: `HandleItem()`) | Gestisce un elemento di lavoro già acquisito da un poller. Il poller può essere `ant beta:worker poll --on-work` o il tuo codice. Il metodo ritorna quando il worker ha finito con la sessione dell’elemento. Puoi passare `work_id` (typescript: `workId`; go: `WorkID`), `session_id` (typescript: `sessionId`; go: `SessionID`), `environment_id` (typescript: `environmentId`; go: `EnvironmentID`) e `work_secret` (typescript: `workSecret`; go: `WorkSecret`). Per ciascuno che ometti, il metodo legge la [variabile `ANTHROPIC_*`](https://platform.claude.com/docs/it/managed-agents/self-hosted-sandboxes-reference#environment-variables) corrispondente. |

| Opzione | Descrizione |
| ----- | ----- |
| `tools` (go: `ToolsFunc`) | Una factory che riceve l’`AgentToolContext` della sessione e restituisce l’elenco degli strumenti. Il valore predefinito è il toolset standard dell’agente. |
| `max_idle` (typescript: `maxIdleMs`; go: `MaxIdle`) | Quanto tempo il worker attende mentre una sessione è inattiva prima di avere finito con la sessione. Il tempo di inattività con uno [stop reason `requires_action`](https://platform.claude.com/docs/it/managed-agents/events-and-streaming#respond-when-the-session-goes-idle) (motivo di arresto) non viene conteggiato. Il valore predefinito è 60 secondi. Per attendere 5 minuti, impostalo su `300` (typescript: `300_000`; go: `anthropic.Ptr(5 * time.Minute)`). Per disattivare il limite, impostalo su `None` (typescript: `0`; go: `new(time.Duration)`). |
| `memory_sync_interval` (typescript: `memorySyncIntervalMs`; go: `MemorySyncInterval`) | Il tempo minimo tra due sincronizzazioni dei memory store collegati mentre la sessione è in esecuzione. Il worker controlla l’intervallo dopo ogni chiamata a uno strumento eseguito nella tua sandbox, non in base a un timer. Il valore predefinito è 15 secondi. Consulta [Intervallo di sincronizzazione](https://platform.claude.com/docs/it/managed-agents/self-hosted-sandboxes-memory#sync-interval). |
| `memory_sync_deletions` (typescript: `memorySyncDeletions`; go: `MemorySyncDeletions`) | Se i file che l’agente elimina localmente vengono eliminati anche dallo store. Consulta [Eliminazioni](https://platform.claude.com/docs/it/managed-agents/self-hosted-sandboxes-memory#deletions). |

`EnvironmentWorker` gestisce automaticamente l’`AgentToolContext` e il set di strumenti. Passa una factory `tools` (go: `ToolsFunc`) per personalizzare l’elenco degli strumenti:

<CodeGroup exclude="shell, csharp, java, php, ruby">
  <CodeGroupItem language="cURL">
    Un worker è un processo di lunga durata, non una singola richiesta HTTP. Per personalizzare l’elenco degli strumenti, usa `EnvironmentWorker` nell’SDK Python, TypeScript o Go.
  </CodeGroupItem>

  <CodeGroupItem language="CLI">
    Il worker della CLI `ant` usa sempre il toolset standard dell’agente. Per personalizzare l’elenco degli strumenti, usa `EnvironmentWorker` nell’SDK Python, TypeScript o Go.
  </CodeGroupItem>

  ```python Python
  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,
              # Elenca ogni strumento che l'agente può chiamare. Il worker non risponde ad altri strumenti.
              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())
  ```

  ```typescript TypeScript
  import Anthropic from "@anthropic-ai/sdk";
  import { EnvironmentWorker } from "@anthropic-ai/sdk/helpers/beta/environments";
  import { betaTool } from "@anthropic-ai/sdk/helpers/beta/json-schema";
  import { betaBashTool } from "@anthropic-ai/sdk/tools/agent-toolset/node";

  const getOrderStatus = betaTool({
    name: "get_order_status",
    description: "Look up an order in the internal fulfillment system by order ID.",
    inputSchema: {
      type: "object",
      properties: { order_id: { type: "string", description: "The order ID" } },
      required: ["order_id"]
    },
    run: async ({ order_id }) => `Order ${order_id}: shipped`
  });

  const environmentKey = process.env.ANTHROPIC_ENVIRONMENT_KEY!;
  const environmentId = process.env.ANTHROPIC_ENVIRONMENT_ID!;
  const client = new Anthropic({ authToken: environmentKey });
  const controller = new AbortController();
  process.once("SIGINT", () => controller.abort());
  process.once("SIGTERM", () => controller.abort());

  await new EnvironmentWorker({
    client,
    environmentId,
    environmentKey,
    signal: controller.signal,
    // Elenca ogni strumento che l'agente può chiamare. Il worker non risponde ad altri strumenti.
    tools: (ctx) => [betaBashTool(ctx), getOrderStatus]
  }).run();
  ```

  <CodeGroupItem language="C#">
    L’SDK C# non dispone di `EnvironmentWorker`. Per rispondere alle chiamate agli strumenti personalizzati dal tuo codice, invia ogni risultato sul flusso di eventi della sessione, come in [Restituire il risultato di uno strumento personalizzato](https://platform.claude.com/docs/it/managed-agents/events-and-streaming#return-a-custom-tool-result).
  </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"
  	"github.com/anthropics/anthropic-sdk-go/v2/toolrunner"
  	"github.com/anthropics/anthropic-sdk-go/v2/tools/agenttoolset"
  )

  type orderStatusInput struct {
  	OrderID string `json:"order_id"`
  }

  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()

  	getOrderStatus := toolrunner.NewBetaTool(
  		"get_order_status",
  		"Look up an order in the internal fulfillment system by order ID.",
  		anthropic.BetaToolInputSchemaParam{
  			Properties: map[string]any{
  				"order_id": map[string]any{"type": "string", "description": "The order ID"},
  			},
  			Required: []string{"order_id"},
  		},
  		func(ctx context.Context, input orderStatusInput) (anthropic.BetaToolResultBlockParamContentUnion, error) {
  			return anthropic.BetaToolResultBlockParamContentUnion{
  				OfText: &anthropic.BetaTextBlockParam{Text: "Order " + input.OrderID + ": shipped"},
  			}, nil
  		},
  	)

  	client := anthropic.NewClient(option.WithAuthToken(environmentKey))

  	worker := environments.NewEnvironmentWorker(client, environments.EnvironmentWorkerOptions{
  		EnvironmentID:  environmentID,
  		EnvironmentKey: environmentKey,
  		// Elenca ogni strumento che l'agente può chiamare. Il worker non risponde a nessun altro strumento.
  		ToolsFunc: func(env *agenttoolset.AgentToolContext) []anthropic.BetaTool {
  			return []anthropic.BetaTool{agenttoolset.BetaBashTool(env), getOrderStatus}
  		},
  	})
  	if err := worker.Run(ctx); err != nil {
  		log.Fatalf("worker: %v", err)
  	}
  }
  ```

  <CodeGroupItem language="Java">
    L’SDK Java non dispone di `EnvironmentWorker`. Per rispondere alle chiamate agli strumenti personalizzati dal tuo codice, invia ogni risultato sul flusso di eventi della sessione, come in [Restituire il risultato di uno strumento personalizzato](https://platform.claude.com/docs/it/managed-agents/events-and-streaming#return-a-custom-tool-result).
  </CodeGroupItem>

  <CodeGroupItem language="PHP">
    L’SDK PHP non dispone di `EnvironmentWorker`. Per rispondere alle chiamate agli strumenti personalizzati dal tuo codice, invia ogni risultato sul flusso di eventi della sessione, come in [Restituire il risultato di uno strumento personalizzato](https://platform.claude.com/docs/it/managed-agents/events-and-streaming#return-a-custom-tool-result).
  </CodeGroupItem>

  <CodeGroupItem language="Ruby">
    L’SDK Ruby non dispone di `EnvironmentWorker`. Per rispondere alle chiamate agli strumenti personalizzati dal tuo codice, invia ogni risultato sul flusso di eventi della sessione, come in [Restituire il risultato di uno strumento personalizzato](https://platform.claude.com/docs/it/managed-agents/events-and-streaming#return-a-custom-tool-result).
  </CodeGroupItem>
</CodeGroup>

### Work poller

| Opzione | Descrizione |
| ----- | ----- |
| `drain` (go: `Drain`) | Se interrompere il polling quando la coda è vuota invece di attendere nuovo lavoro. |
| `block_ms` (typescript: `blockMs`; go: `BlockMs`) | Quanto attende ogni richiesta di polling l’arrivo di lavoro prima di ritornare, in millisecondi. Deve essere compreso tra 1 e 999. L’helper ripete automaticamente il polling. Passa `null` (python: `None`; go: `param.Null[int64]()`) per un controllo non bloccante. Il valore predefinito è un long polling di 999ms. |
| `reclaim_older_than_ms` (typescript: `reclaimOlderThanMs`; go: `ReclaimOlderThanMs`) | Acquisisce nuovamente gli elementi di lavoro che sono stati acquisiti ma mai confermati entro questo numero di millisecondi. |
| `auto_stop` (typescript: `autoStop`; go: `AutoStop`) | Se il poller invia un segnale di arresto per ogni elemento di lavoro una volta che il corpo del tuo ciclo ha finito di elaborarlo. Il valore predefinito è `true` (python: `True`). Impostalo su `false` (python: `False`; go: `param.NewOpt(false)`) nei due casi che seguono questa tabella. |

Imposta `auto_stop` (typescript: `autoStop`; go: `AutoStop`) su `false` (python: `False`; go: `param.NewOpt(false)`) in due casi:

1. Il tuo ciclo chiama `handle_item()` (typescript: `handleItem()`; go: `HandleItem()`), che invia l’arresto autonomamente.
2. Il tuo ciclo avvia una sandbox per l’elemento e passa oltre. Il worker in quella sandbox deve inviare l’arresto quando il lavoro della sessione termina, come fanno `ant beta:worker run` e `handle_item()` (typescript: `handleItem()`; go: `HandleItem()`).

Per un esempio completo, consulta [Avvia le sandbox dal poller dell’SDK](https://platform.claude.com/docs/it/managed-agents/self-hosted-sandboxes-per-session#launch-sandboxes-from-the-sdk-poller).

### Tool runner di sessione

`client.beta.sessions.events.tool_runner()` (typescript: `client.beta.sessions.events.toolRunner()`; go: `client.Beta.Sessions.Events.NewToolRunner()`) accetta un elenco di strumenti come `tools` (go: `Tools`). Per costruire tale elenco, configura tu stesso `AgentToolContext` e chiama `beta_agent_toolset_20260401(env)` (typescript: `betaAgentToolset20260401(ctx)`; go: `agenttoolset.BetaAgentToolset20260401(env)`):

<CodeGroup exclude="shell, csharp, java, php, ruby">
  <CodeGroupItem language="cURL">
    `AgentToolContext` è un helper degli SDK Python, TypeScript e Go. cURL non ha un equivalente. Usa uno di questi SDK.
  </CodeGroupItem>

  <CodeGroupItem language="CLI">
    `AgentToolContext` è un helper degli SDK Python, TypeScript e Go. La CLI `ant` non ha un equivalente. Usa uno di questi SDK.
  </CodeGroupItem>

  ```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:
      # skill scaricate in /workspace/skills/<name>/
      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);
  ```

  <CodeGroupItem language="C#">
    L’SDK C# non dispone di `AgentToolContext`.
  </CodeGroupItem>

  ```go Go
  env := &agenttoolset.AgentToolContext{Workdir: "/workspace"}
  if err := env.SetupSkills(ctx, client, work.Data.ID); err != nil {
  	panic(err)
  }
  // skill scaricate in /workspace/skills/<name>/
  tools := agenttoolset.BetaAgentToolset20260401(env)
  ```

  <CodeGroupItem language="Java">
    L’SDK Java non dispone di `AgentToolContext`.
  </CodeGroupItem>

  <CodeGroupItem language="PHP">
    L’SDK PHP non dispone di `AgentToolContext`.
  </CodeGroupItem>

  <CodeGroupItem language="Ruby">
    L’SDK Ruby non dispone di `AgentToolContext`.
  </CodeGroupItem>
</CodeGroup>

### AgentToolContext e il toolset dell’agente

`AgentToolContext` è il contesto di esecuzione per le chiamate agli strumenti. Definisce la directory di lavoro e la policy dei percorsi, e può scaricare le skill della sessione.

| Opzione | Descrizione |
| ----- | ----- |
| `allowed_roots` (typescript: `allowedRoots`; go: `AllowedRoots`) | Directory, oltre alla directory di lavoro, raggiungibili dagli strumenti per i file (`read`, `write`, `edit`, `glob`, `grep`). |
| `read_only_roots` (typescript: `readOnlyRoots`; go: `ReadOnlyRoots`) | Directory sotto le quali `write` e `edit` rifiutano i percorsi. |

`EnvironmentWorker` aggiunge autonomamente le directory degli archivi di memoria della sessione a `allowed_roots` (typescript: `allowedRoots`; go: `AllowedRoots`), e le directory degli archivi di memoria collegati con `access: "read_only"` a `read_only_roots` (typescript: `readOnlyRoots`; go: `ReadOnlyRoots`).

Il confinamento è una protezione solo per gli strumenti per i file, non una sandbox. Non vincola `bash`.

`beta_agent_toolset_20260401(env)` (typescript: `betaAgentToolset20260401(ctx)`; go: `agenttoolset.BetaAgentToolset20260401(env)`) accetta un `AgentToolContext` e restituisce le implementazioni standard degli strumenti (`bash`, `read`, `write`, `edit`, `glob`, `grep`).
