---
title: 자체 호스팅 워커 참조
url: https://platform.claude.com/docs/ko/managed-agents/self-hosted-sandboxes-reference
description: "자체 호스팅 샌드박스 워커에 대한 참조: ant CLI 플래그, 환경 변수, 호스트 요구 사항, 파일 시스템 경로 및 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: 자체 호스팅 Managed Agents를 제외하고 ZDR 적격 대상이 아닙니다. 세션은 상태를 유지하는 리소스이며, 트랜스크립트는 삭제할 때까지 유지됩니다.
  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
---

이 페이지는 `self_hosted` 환경을 처리하는 사전 빌드된 워커를 설명합니다. 작업 중심 가이드는 [자체 호스팅 샌드박스](https://platform.claude.com/docs/ko/managed-agents/self-hosted-sandboxes)와 [자체 호스팅 워커 배포](https://platform.claude.com/docs/ko/managed-agents/self-hosted-sandboxes-workers)부터 시작하세요.

## CLI 명령 및 플래그

| 명령 | 설명 |
| ----- | ----- |
| `ant beta:worker poll` | 환경의 큐에서 작업 항목을 가져와(claim) 각 세션을 프로세스 내에서 실행합니다. `--on-work`를 사용하면 대신 각 작업 항목에 대해 사용자의 스크립트를 호출합니다. |
| `ant beta:worker run` | 가져온 세션 하나를 처리한 후 종료합니다. 세션별 샌드박스의 진입점으로 사용하세요. |

| 플래그 | 설명 |
| ----- | ----- |
| `--environment-id` | 작업을 폴링할 환경입니다. `ANTHROPIC_ENVIRONMENT_ID`에서도 읽습니다. |
| `--environment-key` | 이 환경에 대해 워커를 인증합니다. `ANTHROPIC_ENVIRONMENT_KEY`에서도 읽습니다. |
| `--workdir` | 워커가 스킬을 다운로드하고 도구가 파일을 읽고 쓰는 디렉터리입니다. 기본값은 `.`(현재 디렉터리)입니다. 워커가 시작되기 전에 디렉터리가 존재해야 합니다. |
| `--on-work` | 도구를 프로세스 내에서 실행하는 대신 가져온 각 작업 항목에 대해 호출할 스크립트입니다. 세션 세부 정보를 환경 변수로, 작업 항목을 표준 입력의 JSON으로 받습니다. |
| `--max-idle` | 세션이 유휴 상태인 동안 `ant beta:worker run`이 종료되거나 `ant beta:worker poll`이 다음 작업 항목으로 넘어가기 전까지 워커가 대기하는 시간입니다. [`requires_action` 중지 이유](https://platform.claude.com/docs/ko/managed-agents/events-and-streaming#respond-when-the-session-goes-idle)로 인한 유휴 시간은 포함되지 않습니다. 기본값은 `60s`입니다. 시간 제한을 끄려면 `0`으로 설정하세요. `--on-work` 스크립트를 사용하는 경우 `ant beta:worker poll`은 이 플래그를 무시합니다. 대신 스크립트가 시작하는 `ant beta:worker run` 명령에 이 플래그를 전달하세요. |
| `--log-format` | 로그 출력 형식입니다. 구조화된 로그 수집에는 `json`을 사용하세요. 기본값은 `text`입니다. |

## 환경 변수

| 변수 | 설명 | 설정 주체 |
| ----- | ----- | ----- |
| `ANTHROPIC_ENVIRONMENT_ID` | 워커가 처리하는 큐가 속한 환경입니다. | 사용자가 워커 호스트에서 설정합니다. 폴러가 이를 `--on-work` 스크립트에 전달합니다. |
| `ANTHROPIC_ENVIRONMENT_KEY` | 워커를 해당 큐에 인증합니다. | 사용자가 워커 호스트에서 설정합니다. 폴러가 이를 `--on-work` 스크립트에 전달합니다. |
| `ANTHROPIC_SESSION_ID` | 가져온 작업 항목이 나타내는 세션입니다. | 폴러가 `--on-work` 스크립트를 위해 설정합니다. |
| `ANTHROPIC_WORK_ID` | 가져온 작업 항목입니다. | 폴러가 `--on-work` 스크립트를 위해 설정합니다. |
| `ANTHROPIC_WORK_SECRET` | 작업 항목의 세션별 시크릿입니다. | 사용자가 설정합니다. 폴러는 이를 설정하지 않습니다. [작업 항목의 시크릿 전달](https://platform.claude.com/docs/ko/managed-agents/self-hosted-sandboxes-per-session#forward-the-work-items-secret)을 참조하세요. |
| `ANTHROPIC_BASE_URL` | 기본 API 엔드포인트를 재정의합니다. 선택 사항입니다. | 사용자가 워커 호스트에서 설정합니다. |
| `ANTHROPIC_WEBHOOK_SIGNING_KEY` | 수신되는 웹훅 페이로드를 검증합니다. | 사용자가 웹훅 핸들러 호스트에서 설정합니다. |

## 호스트 요구 사항

| 워커 | 요구 사항 |
| ----- | ----- |
| 모든 워커 | 정확히 해당 경로에 `/bin/bash`가 있는 Linux 또는 macOS 호스트. 워커의 `bash` 도구는 `PATH`를 참조하지 않고 이를 직접 실행합니다. macOS에서는 시스템 Bash 3.2가 해당됩니다. |
| TypeScript SDK | `PATH`에 있는 `unzip` 및 `tar`, 그리고 Node.js 22 이상. |
| Python 및 Go SDK | 추가 바이너리가 필요하지 않습니다. 이 SDK들은 아카이브 추출에 표준 라이브러리를 사용합니다. |

[메모리 스토어](https://platform.claude.com/docs/ko/managed-agents/self-hosted-sandboxes-memory#requirements)에는 자체 요구 사항이 추가됩니다.

macOS에서는 루트 볼륨이 읽기 전용이므로 `mkdir`로 `/workspace`를 생성할 수 없습니다. 워커의 작업 디렉터리를 홈 디렉터리의 `workspace` 디렉터리처럼 쓰기 가능한 디렉터리로 설정하세요. macOS에서 메모리 스토어를 사용하려면 먼저 [macOS 호스트를 준비](https://platform.claude.com/docs/ko/managed-agents/self-hosted-sandboxes-memory#prepare-a-macos-host)하세요.

## 샌드박스 파일 시스템

| 경로 | 내용 |
| ----- | ----- |
| `/workspace` | 자체 호스팅 샌드박스 페이지의 샘플에서 사용하는 작업 디렉터리입니다. 워커의 기본값은 아닙니다. `--workdir` 또는 `workdir` (go: `Workdir`)를 설정하지 않으면 워커는 현재 디렉터리를 사용합니다. Anthropic의 클라우드 샌드박스는 스킬과 리포지토리를 `/workspace`에 보관합니다. 다른 작업 디렉터리를 사용하는 경우 Claude가 스킬 파일을 찾을 수 있도록 에이전트의 시스템 프롬프트를 업데이트하세요. |
| `<workdir>/skills/<name>/` | 에이전트의 다운로드된 스킬입니다. |
| `/mnt/memory/<store>/` | 연결된 각 메모리 스토어의 로컬 사본으로, 스토어마다 하나의 디렉터리입니다. API는 세션의 메모리 스토어 리소스의 `mount_path` (java, php: `mountPath`; csharp, go: `MountPath`) 필드에 각 디렉터리의 전체 경로를 반환합니다(예: `/mnt/memory/user-preferences/`). |

워커는 세션을 가져올 때 메모리 스토어 디렉터리를 생성합니다. 해당 세션 처리를 마치거나 사용자가 [워커를 정상적으로 중지](https://platform.claude.com/docs/ko/managed-agents/self-hosted-sandboxes-operations#stop-workers-gracefully)할 때 이를 제거합니다. 이 작업은 로컬 사본만 제거하며, 메모리는 스토어에 남아 있습니다.

스킬에는 에이전트가 직접 실행할 수 있는 실행 파일이 포함될 수 있습니다. CLI 및 SDK 워커는 스킬 번들을 추출할 때 번들에 기록된 실행 권한을 유지합니다. 스킬을 직접 다운로드하는 경우 실행 권한도 직접 설정하세요.

### 워커가 세션 처리를 마치는 시점

워커는 다음 중 하나에 해당하는 경우 세션 처리를 마칩니다:

* 세션이 종료되는 경우.
* 사용자가 [세션의 작업 항목을 중지](https://platform.claude.com/docs/ko/managed-agents/self-hosted-sandboxes-operations#stop-a-session-gracefully)하는 경우.
* 세션이 워커의 “idle limit”(유휴 제한 시간) 동안 유휴 상태로 유지되는 경우. 세션 자체는 열린 상태로 유지됩니다. 이후 사용자가 사용자 메시지와 같은 새 이벤트를 보내면 같은 워커나 다른 워커가 세션을 가져옵니다. 해당 워커는 스토어를 다시 다운로드합니다.

유휴 제한 시간은 기본적으로 60초입니다. 변경하려면 `ant` CLI 워커의 경우 [`--max-idle`](https://platform.claude.com/docs/ko/managed-agents/self-hosted-sandboxes-reference#cli-commands-and-flags)을, `EnvironmentWorker`의 경우 [`max_idle` (typescript: `maxIdleMs`; go: `MaxIdle`)](https://platform.claude.com/docs/ko/managed-agents/self-hosted-sandboxes-reference#environment-worker)을 사용하세요. [`cma-sandboxes` Helm 차트](https://platform.claude.com/docs/ko/managed-agents/self-hosted-sandboxes-per-session#run-sandboxes-on-kubernetes)는 대신 30분의 제한 시간으로 워커를 시작합니다. 해당 제한 시간을 변경하려면 차트의 `sandbox.idleTimeout` 설정을 변경하세요.

### 최종 결과물

자체 호스팅 샌드박스에는 `/mnt/session/outputs` 디렉터리가 없습니다. Anthropic의 클라우드 샌드박스에서는 세션의 시스템 프롬프트가 에이전트에게 최종 결과물을 그곳에 복사하도록 지시합니다. 자체 호스팅 환경에서는 시스템 프롬프트에 해당 지침이 포함되지 않습니다. 최종 결과물은 에이전트가 기록한 위치에 그대로 남으며 일반적으로 작업 디렉터리 아래에 있고, 워커는 이를 업로드하지 않습니다.

최종 결과물을 한곳에 모으려면 에이전트의 시스템 프롬프트에 디렉터리의 전체 경로를 지정하세요. 워커의 파일 도구가 기록할 수 있는 디렉터리를 선택하세요:

* **작업 디렉터리 내부:** 예를 들어 작업 디렉터리가 `/workspace`인 경우 `/workspace/outputs`.
* **그 외 모든 위치(SDK 워커에서만 가능):** 디렉터리를 `allowed_roots` (typescript: `allowedRoots`; go: `AllowedRoots`)에 추가하세요. [AgentToolContext 및 에이전트 도구 세트](https://platform.claude.com/docs/ko/managed-agents/self-hosted-sandboxes-reference#agent-tool-context-and-the-agent-toolset)를 참조하세요.

## SDK 헬퍼

Python, TypeScript 및 Go SDK는 서로 다른 제어 수준의 세 가지 헬퍼를 제공합니다:

| 헬퍼 | 기능 | 사용 시점 |
| ----- | ----- | ----- |
| [`EnvironmentWorker`](https://platform.claude.com/docs/ko/managed-agents/self-hosted-sandboxes-reference#environment-worker) | 폴링, 설정 및 도구 실행을 처음부터 끝까지 처리합니다. | 대부분의 경우. |
| [`work.poller()` (typescript: `new WorkPoller()`; go: `environments.NewWorkPoller()`)](https://platform.claude.com/docs/ko/managed-agents/self-hosted-sandboxes-reference#work-poller) | 작업 큐를 폴링하고 가져온 각 세션을 제공합니다. | 각 세션을 처리하는 방법을 직접 결정하는 경우. 예를 들어 도구를 프로세스 내에서 실행하는 대신 샌드박스를 시작하는 경우. |
| [`client.beta.sessions.events.tool_runner()` (typescript: `client.beta.sessions.events.toolRunner()`; go: `client.Beta.Sessions.Events.NewToolRunner()`)](https://platform.claude.com/docs/ko/managed-agents/self-hosted-sandboxes-reference#session-tool-runner) | 세션 ID와 도구 목록이 주어지면 단일 세션에 대한 도구 호출을 실행합니다. | 이미 작업을 가져왔고 도구 실행만 필요한 경우. |

### EnvironmentWorker

| 메서드 | 설명 |
| ----- | ----- |
| `run()` (go: `Run()`) | 무기한 실행되며 세션이 도착하는 대로 가져옵니다. |
| `handle_item()` (typescript: `handleItem()`; go: `HandleItem()`) | 폴러가 이미 가져온 작업 항목 하나를 처리합니다. 폴러는 `ant beta:worker poll --on-work` 또는 사용자의 자체 코드일 수 있습니다. 이 메서드는 워커가 해당 항목의 세션 처리를 마치면 반환합니다. `work_id` (typescript: `workId`; go: `WorkID`), `session_id` (typescript: `sessionId`; go: `SessionID`), `environment_id` (typescript: `environmentId`; go: `EnvironmentID`) 및 `work_secret` (typescript: `workSecret`; go: `WorkSecret`)을 전달할 수 있습니다. 생략한 각 항목에 대해 메서드는 해당하는 [`ANTHROPIC_*` 변수](https://platform.claude.com/docs/ko/managed-agents/self-hosted-sandboxes-reference#environment-variables)를 읽습니다. |

| 옵션 | 설명 |
| ----- | ----- |
| `tools` (go: `ToolsFunc`) | 세션의 `AgentToolContext`를 받아 도구 목록을 반환하는 팩토리입니다. 기본값은 표준 에이전트 도구 세트입니다. |
| `max_idle` (typescript: `maxIdleMs`; go: `MaxIdle`) | 세션이 유휴 상태인 동안 워커가 세션 처리를 마치기 전까지 대기하는 시간입니다. [`requires_action` 중지 이유](https://platform.claude.com/docs/ko/managed-agents/events-and-streaming#respond-when-the-session-goes-idle)로 인한 유휴 시간은 포함되지 않습니다. 기본값은 60초입니다. 5분 동안 대기하려면 `300` (typescript: `300_000`; go: `anthropic.Ptr(5 * time.Minute)`)으로 설정하세요. 제한을 끄려면 `None` (typescript: `0`; go: `new(time.Duration)`)으로 설정하세요. |
| `memory_sync_interval` (typescript: `memorySyncIntervalMs`; go: `MemorySyncInterval`) | 세션이 실행되는 동안 연결된 메모리 스토어를 두 번 동기화하는 사이의 최소 시간입니다. 워커는 타이머가 아니라 샌드박스에서 실행되는 도구를 호출할 때마다 그 후에 간격을 확인합니다. 기본값은 15초입니다. [동기화 간격](https://platform.claude.com/docs/ko/managed-agents/self-hosted-sandboxes-memory#sync-interval)을 참조하세요. |
| `memory_sync_deletions` (typescript: `memorySyncDeletions`; go: `MemorySyncDeletions`) | 에이전트가 로컬에서 삭제한 파일을 스토어에서도 삭제할지 여부입니다. [삭제](https://platform.claude.com/docs/ko/managed-agents/self-hosted-sandboxes-memory#deletions)를 참조하세요. |

`EnvironmentWorker`는 `AgentToolContext`와 도구 세트를 자동으로 관리합니다. 도구 목록을 사용자 지정하려면 `tools` (go: `ToolsFunc`) 팩토리를 전달하세요:

<CodeGroup exclude="shell, csharp, java, php, ruby">
  <CodeGroupItem language="cURL">
    워커는 단일 HTTP 요청이 아니라 “long-running process”(장기 실행 프로세스)입니다. 도구 목록을 사용자 지정하려면 Python, TypeScript 또는 Go SDK의 `EnvironmentWorker`를 사용하세요.
  </CodeGroupItem>

  <CodeGroupItem language="CLI">
    `ant` CLI 워커는 항상 표준 에이전트 도구 세트를 사용합니다. 도구 목록을 사용자 지정하려면 Python, TypeScript 또는 Go SDK의 `EnvironmentWorker`를 사용하세요.
  </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,
              # 에이전트가 호출할 수 있는 모든 도구를 나열하세요. 워커는 그 외의 도구에는 응답하지 않습니다.
              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,
    // 에이전트가 호출할 수 있는 모든 도구를 나열하세요. 워커는 그 외의 도구에는 응답하지 않습니다.
    tools: (ctx) => [betaBashTool(ctx), getOrderStatus]
  }).run();
  ```

  <CodeGroupItem language="C#">
    C# SDK에는 `EnvironmentWorker`가 없습니다. 자체 코드에서 사용자 정의 도구 호출에 응답하려면 [커스텀 도구 결과 반환하기](https://platform.claude.com/docs/ko/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,
  		// 에이전트가 호출할 수 있는 모든 도구를 나열하세요. 워커는 그 외의 도구에는 응답하지 않습니다.
  		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">
    Java SDK에는 `EnvironmentWorker`가 없습니다. 자체 코드에서 사용자 정의 도구 호출에 응답하려면 [커스텀 도구 결과 반환하기](https://platform.claude.com/docs/ko/managed-agents/events-and-streaming#return-a-custom-tool-result)에서와 같이 각 결과를 세션의 이벤트 스트림으로 전송하세요.
  </CodeGroupItem>

  <CodeGroupItem language="PHP">
    PHP SDK에는 `EnvironmentWorker`가 없습니다. 자체 코드에서 사용자 정의 도구 호출에 응답하려면 [커스텀 도구 결과 반환하기](https://platform.claude.com/docs/ko/managed-agents/events-and-streaming#return-a-custom-tool-result)에서와 같이 각 결과를 세션의 이벤트 스트림으로 전송하세요.
  </CodeGroupItem>

  <CodeGroupItem language="Ruby">
    Ruby SDK에는 `EnvironmentWorker`가 없습니다. 자체 코드에서 사용자 정의 도구 호출에 응답하려면 [커스텀 도구 결과 반환하기](https://platform.claude.com/docs/ko/managed-agents/events-and-streaming#return-a-custom-tool-result)에서와 같이 각 결과를 세션의 이벤트 스트림으로 전송하세요.
  </CodeGroupItem>
</CodeGroup>

### 작업 폴러

| 옵션 | 설명 |
| ----- | ----- |
| `drain` (go: `Drain`) | 새 작업을 기다리지 않고 큐가 비면 폴링을 중지할지 여부입니다. |
| `block_ms` (typescript: `blockMs`; go: `BlockMs`) | 각 폴링이 반환하기 전에 작업이 도착하기를 기다리는 시간(밀리초)입니다. 1에서 999 사이여야 합니다. 헬퍼가 자동으로 다시 폴링합니다. 비차단 확인을 하려면 `null` (python: `None`; go: `param.Null[int64]()`)을 전달하세요. 기본값은 999ms 롱 폴링입니다. |
| `reclaim_older_than_ms` (typescript: `reclaimOlderThanMs`; go: `ReclaimOlderThanMs`) | 가져왔지만 이 밀리초 내에 확인(acknowledge)되지 않은 작업 항목을 다시 가져옵니다. |
| `auto_stop` (typescript: `autoStop`; go: `AutoStop`) | 루프 본문이 각 작업 항목 처리를 마치면 폴러가 해당 작업 항목에 대한 중지 신호를 게시할지 여부입니다. 기본값은 `true` (python: `True`)입니다. 이 표 다음에 나오는 두 가지 경우에 `false` (python: `False`; go: `param.NewOpt(false)`)로 설정하세요. |

다음 두 가지 경우에 `auto_stop` (typescript: `autoStop`; go: `AutoStop`)을 `false` (python: `False`; go: `param.NewOpt(false)`)로 설정하세요:

1. 루프가 `handle_item()` (typescript: `handleItem()`; go: `HandleItem()`)을 호출하는 경우. 이 메서드는 직접 중지를 게시합니다.
2. 루프가 항목에 대한 샌드박스를 시작하고 다음으로 넘어가는 경우. 해당 샌드박스의 워커는 `ant beta:worker run` 및 `handle_item()` (typescript: `handleItem()`; go: `HandleItem()`)처럼 세션의 작업이 끝나면 중지를 게시해야 합니다.

전체 예제는 [SDK 폴러에서 샌드박스 시작](https://platform.claude.com/docs/ko/managed-agents/self-hosted-sandboxes-per-session#launch-sandboxes-from-the-sdk-poller)을 참조하세요.

### 세션 도구 러너

`client.beta.sessions.events.tool_runner()` (typescript: `client.beta.sessions.events.toolRunner()`; go: `client.Beta.Sessions.Events.NewToolRunner()`)는 도구 목록을 `tools` (go: `Tools`)로 받습니다. 해당 목록을 만들려면 `AgentToolContext`를 직접 설정하고 `beta_agent_toolset_20260401(env)` (typescript: `betaAgentToolset20260401(ctx)`; go: `agenttoolset.BetaAgentToolset20260401(env)`)를 호출하세요:

<CodeGroup exclude="shell, csharp, java, php, ruby">
  <CodeGroupItem language="cURL">
    `AgentToolContext`는 Python, TypeScript 및 Go SDK의 헬퍼입니다. cURL에는 이에 해당하는 기능이 없습니다. 해당 SDK 중 하나를 사용하세요.
  </CodeGroupItem>

  <CodeGroupItem language="CLI">
    `AgentToolContext`는 Python, TypeScript 및 Go SDK의 헬퍼입니다. `ant` CLI에는 이에 해당하는 기능이 없습니다. 해당 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:
      # 스킬은 /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#">
    C# SDK에는 `AgentToolContext`가 없습니다.
  </CodeGroupItem>

  ```go Go
  env := &agenttoolset.AgentToolContext{Workdir: "/workspace"}
  if err := env.SetupSkills(ctx, client, work.Data.ID); err != nil {
  	panic(err)
  }
  // 스킬은 /workspace/skills/<name>/에 다운로드됨
  tools := agenttoolset.BetaAgentToolset20260401(env)
  ```

  <CodeGroupItem language="Java">
    Java SDK에는 `AgentToolContext`가 없습니다.
  </CodeGroupItem>

  <CodeGroupItem language="PHP">
    PHP SDK에는 `AgentToolContext`가 없습니다.
  </CodeGroupItem>

  <CodeGroupItem language="Ruby">
    Ruby SDK에는 `AgentToolContext`가 없습니다.
  </CodeGroupItem>
</CodeGroup>

### AgentToolContext 및 에이전트 도구 세트

`AgentToolContext`는 도구 호출을 위한 실행 컨텍스트입니다. 작업 디렉터리와 경로 정책을 정의하며, 세션의 스킬을 다운로드할 수 있습니다.

| 옵션 | 설명 |
| ----- | ----- |
| `allowed_roots` (typescript: `allowedRoots`; go: `AllowedRoots`) | 작업 디렉터리 외에 파일 도구(`read`, `write`, `edit`, `glob`, `grep`)가 접근할 수 있는 디렉터리입니다. |
| `read_only_roots` (typescript: `readOnlyRoots`; go: `ReadOnlyRoots`) | `write` 및 `edit`가 경로를 거부하는 디렉터리입니다. |

`EnvironmentWorker`는 세션의 메모리 스토어 디렉터리를 `allowed_roots` (typescript: `allowedRoots`; go: `AllowedRoots`)에 직접 추가하고, `access: "read_only"`로 연결된 스토어의 디렉터리를 `read_only_roots` (typescript: `readOnlyRoots`; go: `ReadOnlyRoots`)에 추가합니다.

이 제한은 파일 도구에만 적용되는 보호 장치이며 샌드박스가 아닙니다. `bash`는 제한하지 않습니다.

`beta_agent_toolset_20260401(env)` (typescript: `betaAgentToolset20260401(ctx)`; go: `agenttoolset.BetaAgentToolset20260401(env)`)는 `AgentToolContext`를 받아 표준 도구 구현(`bash`, `read`, `write`, `edit`, `glob`, `grep`)을 반환합니다.
