자체 호스팅 워커 배포
자체 호스팅 샌드박스 워커가 작업을 가져오는 방식과 세션이 실행되는 위치를 선택한 다음, 상시 실행 워커를 실행하거나 웹훅에서 워커를 트리거하세요.
자체 호스팅 샌드박스 빠른 시작은 지속적으로 폴링하며 모든 세션을 하나의 프로세스에서 실행하는 ant CLI 워커 하나를 실행합니다. 이 페이지는 배포 패턴을 선택하는 데 도움을 준 다음, 상시 실행 워커와 웹훅 트리거 워커를 다룹니다.
배포 패턴 선택
워커를 배포할 때는 두 가지를 선택해야 합니다. 워커가 작업을 가져오는 방식과 각 세션이 실행되는 위치입니다.
워커가 작업을 가져오는 방식:
- 상시 실행(Always-on): 장기 실행 프로세스가 큐를 지속적으로 폴링합니다. 이 프로세스는 아웃바운드 HTTPS 요청만 보내므로 Anthropic에 엔드포인트를 노출하지 않아도 됩니다.
- 웹훅 트리거(Webhook-triggered): 핸들러가
session.status_run_started에서 깨어나 폴링을 시작합니다. 유휴 폴러를 피할 수 있지만, Anthropic이 접근할 수 있는 웹훅 엔드포인트가 필요합니다.
각 세션이 실행되는 위치:
- 프로세스 내(In process): 세션을 가져온 워커가 하나의 공유 작업 디렉터리에서 해당 세션의 도구 호출도 실행합니다.
- 세션당 샌드박스(Sandbox per session): 폴러가 가져온 각 세션마다 새 샌드박스를 시작합니다. 새로운 파일 시스템, 리소스 제한 또는 세션별 네트워크 제어 등 더 강력한 격리가 필요할 때 이 방식을 선택하세요. 세션당 하나의 샌드박스 실행을 참조하세요. 이 페이지에서는 Kubernetes용 Helm 차트도 다룹니다.
CLI 워커와 SDK 워커는 서로 다른 조합을 지원합니다:
| 기능 | ant CLI | SDK (Python, TypeScript, Go) |
|---|---|---|
| 상시 폴링 | 예 | 예 |
| 웹훅 트리거 | 아니요 | 예 |
| 세션당 샌드박스 | 예 | 예 |
| 메모리 스토어 | 예, 기본 동기화 설정 사용 | 예, 동기화 구성 가능 |
| 사용자 정의 도구 | 아니요 | 예 |
모든 CLI 플래그와 SDK 옵션은 자체 호스팅 워커 참조를 참조하세요.
더 세밀하게 제어하려면 환경 작업 엔드포인트를 직접 호출하여 자체 워커를 구현하세요. 그러면 사용자의 워커가 SDK 워커가 하는 일을 수행합니다. 예를 들어 각 작업 항목을 확인(acknowledge)하고, 하트비트를 보내고, 에이전트의 스킬을 다운로드합니다. 세션의 권한 정책(permission policy)이 허용하는 도구 호출만 실행합니다. 각 결과를 user.tool_result 또는 user.custom_tool_result 이벤트로 반환합니다. 마지막으로 항목을 중지합니다. Python SDK, TypeScript SDK 또는 Go SDK에 있는 워커 소스를 참고 자료로 사용하세요.
상시 실행 워커 실행
이 샘플은 /workspace를 워커의 작업 디렉터리로 사용합니다. 이 디렉터리는 워커가 시작되기 전에 존재해야 합니다. 새 호스트에서는 첫 번째 세션 실행하기의 "워커 시작하기" 단계에서처럼 디렉터리를 만들고 워커의 사용자에게 쓰기 권한을 부여하세요.
macOS에서는 루트 볼륨이 읽기 전용이므로 mkdir로 /workspace를 만들 수 없습니다. 해당 단계에 나와 있는 것처럼 대신 ~/workspace를 만드세요. SDK는 ~를 확장하지 않으므로 /workspace 대신 echo ~/workspace가 출력하는 전체 경로를 사용하세요.
큐를 지속적으로 폴링하는 워커를 시작합니다. 워커는 빠른 시작에서 받은 환경 키로 인증합니다:
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())
# 프로세스를 강제 종료하는 대신 태스크를 취소하면 워커가 종료 전에
# 진행 중인 작업 항목을 중지하고 변경된 메모리 파일을 업로드할 수 있습니다.
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())웹훅으로 워커 트리거
세션 웹훅 구독
Claude Console에서
session.status_run_started이벤트를 수신하는 webhook 엔드포인트를 정의하세요. 자세한 내용은 웹훅 구독하기를 참조하세요.웹훅 서명 키 내보내기
첫 번째 세션 실행하기의 환경 ID 및 키와 함께, 핸들러 호스트에서 webhook 서명 키를 내보내세요. 핸들러는 이 키를 사용하여 수신되는 페이로드를 검증합니다.
export ANTHROPIC_WEBHOOK_SIGNING_KEY="whsec_..."웹훅 핸들러 구현
session.status_run_started가 발생하면 워커를 시작하세요. 핸들러는 큐를 비우면서 가져온 각 작업 항목을 (Python, TypeScript 및 Go SDK의)handle_item()에 전달합니다. 이 메서드는 스킬을 다운로드하고, 도구 호출을 실행하고, 결과를 다시 게시한 후 반환합니다.샘플은
/workspace를 작업 디렉터리로 사용합니다. 핸들러를 시작하기 전에 핸들러 호스트에 해당 디렉터리를 만드세요. 첫 번째 세션 실행하기의 "워커 시작하기" 단계에서처럼 핸들러의 사용자가 이 디렉터리에 쓸 수 있는지 확인하세요.Python웹훅 서명을 검증하려면 webhooks extra를 설치하세요:
pip install "anthropic[webhooks]".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, ) # shutdown()에 의해 취소되므로, 진행 중인 작업 항목이 변경된 메모리 파일을 업로드하고 # 프로세스 종료 전에 스토어 디렉터리를 제거할 수 있습니다. inflight: set[asyncio.Task[None]] = set() # 호스트의 종료 훅에서 이를 await하세요. 예: ASGI lifespan 종료(FastAPI lifespan의 # `yield` 이후 코드)는 uvicorn이 SIGTERM 시 실행합니다. uvicorn은 열린 요청이 # 끝난 뒤 해당 훅을 실행하므로 --timeout-graceful-shutdown으로 대기 시간을 제한하세요. 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: # 보호됨: 전달이 끊기거나 시간 초과되어도 항목을 취소하면 안 되며, 취소는 shutdown()이 합니다. 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, # 세션별 시크릿을 통해 워커가 세션의 메모리 스토어를 마운트할 수 있습니다. work_secret=work.secret, )Python, TypeScript 및 Go SDK에서
handle_item()은 메모리 스토어를 마운트하기 위해 작업 항목의 시크릿이 필요합니다.run()으로 폴링하는 워커는 이미 시크릿을 가지고 있습니다. 이 핸들러는 각 항목을 직접 가져오므로work_secret인수로 시크릿을 전달합니다. 작업 항목의 시크릿 전달을 참조하세요.
이 핸들러는 가져온 모든 항목을 하나의 프로세스에서 실행하며, 서로 다른 웹훅 전달에서 온 항목을 동시에 실행합니다. 이러한 세션들은 /workspace 및 /mnt/memory를 포함한 하나의 파일 시스템을 공유합니다. 세션들이 동일한 메모리 스토어를 연결하는 경우 스토어를 공유하는 세션 격리하기를 참조하세요.
다음 단계
Kubernetes의 Helm 차트, 스폰 스크립트 또는 SDK 폴러로 샌드박스를 시작하세요.
큐 깊이를 확인하고, 세션과 워커를 깔끔하게 중지하고, 일반적인 오류를 해결하세요.
자체 호스팅 샌드박스 환경을 위한 공동 책임 모델입니다.
제공 여부
Claude API
- 상태
- 베타
- API
- Managed Agents
- 베타 헤더
- 필요
- 모델
- 모든 모델
Claude Platform on AWS
- 상태
- 베타
- API
- Managed Agents
- 베타 헤더
- 필요
- 모델
- 모든 모델
데이터 처리
데이터 처리 개요적용 엔드포인트
/v1/agents/v1/sessions/v1/environments
자체 호스팅 Managed Agents를 제외하고 ZDR 적격 대상이 아닙니다. 세션은 상태를 유지하는 리소스이며, 트랜스크립트는 삭제할 때까지 유지됩니다. 자세히 알아보기
HIPAA 적격 대상이 아닙니다. 모든 Managed Agents 하위 기능에 적용됩니다.
이 페이지가 도움이 되었나요?