Claude Platform Docs
Managed Agents자체 호스팅 샌드박스

자체 호스팅 워커 모니터링 및 문제 해결

큐 깊이를 확인하고, 작업 손실 없이 세션과 워커를 중지하며, 일반적인 자체 호스팅 샌드박스 오류를 해결합니다.

이 페이지의 큐 통계 및 중지 호출은 조직 API 키로 인증된 모니터링 또는 운영 도구에서 실행됩니다. 워커 헬퍼가 작업 가져오기(claim) 및 keep-alive 루프를 처리하므로 해당 엔드포인트를 직접 호출할 필요가 없습니다.

큐 깊이 확인

client.beta.environments.work.stats()는 환경의 큐 상태를 반환합니다:

필드의미용도
depth워커가 가져가기를 기다리는 항목입니다.워커 플릿을 확장하거나 백로그에 대해 알림을 설정합니다.
pending워커가 가져갔지만 아직 확인(acknowledge)하지 않은 항목입니다. 워커 헬퍼는 각 항목을 처리하기 전에 확인하므로, 정상 작동 시 이 값은 0에 가깝게 유지됩니다.작업 항목을 가져온 뒤 확인하기 전에 멈춘 워커를 감지합니다. 0이 아닌 값이 지속되면 알림을 설정하세요.
oldest_queued_at워커가 가져가기를 기다리고 있거나 가져갔지만 아직 확인되지 않은 상태로 큐에 남아 있는 가장 오래된 항목의 타임스탬프입니다. 해당 항목이 없으면 None입니다.가장 오래된 항목이 얼마나 오래 대기했는지 확인합니다.
workers_polling최근 30초 이내에 폴링한 워커입니다.활성 상태(liveness)에 대해 알림을 설정합니다.
import os

import anthropic

client = anthropic.Anthropic()

stats = client.beta.environments.work.stats(os.environ["ANTHROPIC_ENVIRONMENT_ID"])
print(f"depth={stats.depth} pending={stats.pending}")
{
  "type": "work_queue_stats",
  "depth": 0,
  "pending": 0,
  "oldest_queued_at": null,
  "workers_polling": 0
}

세션을 정상적으로 중지하기

client.beta.environments.work.stop()를 사용하여 특정 세션을 처리하는 워커에게 해당 세션을 종료하도록 요청합니다.

기본적으로 작업 항목은 stopping 상태로 전환됩니다. 워커는 다음 리스 하트비트에서 이를 감지하고, 세션의 진행 중인 도구 호출을 취소한 후 종료를 확인합니다. 그러면 작업 항목이 stopped 상태가 됩니다. Python SDK 워커는 대신 진행 중인 도구 호출이 먼저 완료되도록 하며, 이는 최대 2.5분이 걸릴 수 있습니다.

워커의 확인을 기다리지 않고 작업 항목을 즉시 stopped로 표시하려면 force=True를 전달하세요. 강제 중지를 하더라도 진행 중인 도구 호출이 더 빨리 종료되지는 않습니다. 워커는 여전히 다음 하트비트에서 중지를 감지하기 때문입니다.

이러한 호출은 워커 호스트가 아닌 운영 도구에서 실행되므로 ANTHROPIC_WORK_ID가 자동으로 설정되지 않습니다. 다음 예제를 실행하기 전에 대상 작업 항목의 ID로 설정하세요. 작업 항목의 ID를 찾으려면 Authorization: Bearer $ANTHROPIC_ENVIRONMENT_KEY로 전송되는 환경 키를 사용하여 작업 항목 나열API 참조 링크가 포함된 미리보기 사용 가능 — 카드에 포커스가 들어올 때까지 Tab을 누르고, 돌아가려면 Escape를 누르세요.을 호출하세요. 해당 엔드포인트는 조직 API 키를 거부합니다.

import os

import anthropic

client = anthropic.Anthropic()

work = client.beta.environments.work.stop(
    os.environ["ANTHROPIC_WORK_ID"],
    environment_id=os.environ["ANTHROPIC_ENVIRONMENT_ID"],
)
print(work.state)

워커를 정상적으로 중지하기

세션이 실행되는 동안 취소된 워커는 세션을 중지할 때와 마찬가지로 종료하기 전에 해당 세션을 종료합니다. 세션에 메모리 스토어가 연결되어 있으면 워커는 새 파일과 변경된 파일을 여전히 업로드하고 스토어 디렉터리를 제거합니다. 삭제 내용은 전송하지 않으므로, 에이전트가 삭제한 메모리는 이전 동기화에서 이미 스토어에서 삭제되지 않은 한, 스토어에 그대로 남습니다.

갑자기 종료된 프로세스는 정리(teardown) 작업을 실행하지 않습니다. 워커를 깔끔하게 중지하려면:

  1. SIGTERM과 SIGINT가 워커를 취소하도록 하세요. 방법은 워커에 따라 다릅니다:

    워커해야 할 일
    ant CLI아무것도 할 필요가 없습니다. CLI가 두 신호를 직접 처리합니다: 진행 중인 도구 호출을 취소하고, 오류 결과를 게시하며, 작업 항목을 stopped로 표시합니다.
    자체 프로세스로 실행되는 SDK 워커EnvironmentWorker는 신호 핸들러를 설치하지 않습니다. 독립 실행형 워커 예제처럼 신호 핸들러에서 워커를 취소하세요.
    웹훅 서버 내부의 SDK 워커웹훅 예제처럼 서버 자체의 종료 훅에서 워커를 취소하세요. 워커가 서버의 신호를 가로채서는 안 됩니다.
  2. SIGTERM으로 워커를 중지하고, 강제 종료 전에 워커가 작업을 마칠 시간을 주세요. 워커는 진행 중인 도구 호출을 종료하고 변경된 파일을 메모리 스토어에 업로드할 시간이 필요합니다. Docker는 기본적으로 중지 신호 후 10초가 지나면 SIGKILL을 보냅니다. docker run에서 --stop-timeout 210으로 이 제한을 늘리거나, 오케스트레이터의 종료 유예 기간을 같은 초 수로 설정하세요.

정리 작업이 실행되기 전에 워커가 중지되면 동기화되지 않은 메모리 편집 내용은 손실됩니다. 장기 실행 호스트에서는 해당 스토어를 연결하는 다음 세션 전에 /mnt/memory/ 아래에 남아 있는 스토어 디렉터리도 삭제하세요. 하나의 세션만 처리한 후 폐기되는 샌드박스는 정리가 필요하지 않습니다.

문제 해결

워커가 연결되지 않음

workers_polling이 0으로 유지되면 워커가 큐에 도달하지 못하고 있는 것입니다. 워커 호스트에 ANTHROPIC_ENVIRONMENT_KEY와 ANTHROPIC_ENVIRONMENT_ID가 설정되어 있는지 확인하세요.

세션이 대기 상태로 유지됨

작업을 가져가는 워커가 없습니다. 대기 중인 세션은 실패하지 않고 계속 대기합니다. 큐 깊이 확인에서 workers_polling과 depth를 확인하세요.

메모리 스토어 마운트 또는 동기화 실패

메모리 스토어 실패가 나타나는 위치는 실패 유형에 따라 다릅니다:

  • 마운트 실패: 워커가 세션을 가져올 때 메모리 스토어를 마운트할 수 없으면 실패를 로그에 기록하고 작업 항목을 실패 처리합니다. 세션은 오류 이벤트를 발생시키지 않고 유휴 상태로 유지됩니다.
  • 동기화 실패: 워커는 실패를 로그에 기록하며 세션에 보고하지 않습니다.
  • 읽기 전용 스토어에 대한 쓰기 거부: 에이전트가 도구 오류를 받습니다. 읽기 전용 스토어와 충돌을 참조하세요.
증상원인해결 방법
워커 로그에 the work item carried no sessions token(Go에서는 ErrSessionMemoryNoToken 오류)이 포함되고 작업 항목이 실패합니다.작업 항목의 세션별 secret이 워커에 도달하지 않았습니다. 코드에서 이를 전달하지 않았거나, 조직에서 자체 호스팅 샌드박스의 메모리 스토어가 활성화되지 않았습니다.작업 항목의 시크릿을 전달하세요. 워커가 하나의 프로세스에서 폴링과 세션 실행을 모두 수행하는데도 이 로그가 기록되면 지원팀에 문의하세요.
워커 로그에 something already exists at the memory store's path가 포함됩니다.동일한 파일 시스템의 다른 세션이 해당 경로를 사용하고 있습니다. 또는 이전 세션의 워커가 정리 작업이 실행되기 전에 강제 종료되어 디렉터리가 남아 있습니다.워커가 여전히 해당 경로를 사용하는 세션을 실행하고 있는지 확인하세요. 실행 중이라면 디렉터리를 제거하지 마세요: 워커가 세션 처리를 마치면 디렉터리를 제거합니다. 실행 중인 워커가 없다면 로그 줄에 명시된 디렉터리를 제거하세요. 그 안에서 동기화되지 않은 편집 내용은 손실됩니다. 이러한 세션 두 개를 동시에 실행하려면 스토어를 공유하는 세션 격리하기를 참조하세요.
워커 로그에 cannot create the memory store's folder와 the worker host must make this mount path writable이 포함됩니다.워커를 실행하는 사용자가 /mnt/memory 아래에 디렉터리를 생성할 수 없습니다./mnt/memory를 생성하고 해당 사용자에게 chown하세요. 호스트 준비를 참조하세요. macOS에서는 대신 macOS 호스트 준비를 따르세요.
워커가 세션을 가져온 직후 세션이 requires_action 중지 사유와 함께 오류 이벤트 없이 idle 상태로 유지됩니다.앞서 설명한 이유 중 하나로 메모리 스토어를 마운트할 수 없어 워커가 작업 항목을 실패 처리했습니다.호스트에서 원인을 해결한 다음 user.interrupt 이벤트를 보내세요. 세션의 작업이 다시 큐에 추가되고, 이를 가져가는 다음 워커가 마운트를 재시도합니다.

사용자 정의 도구 호출이 반환되지 않음

세션이 requires_action 중지 사유와 함께 일시 중지된 상태로 머물러 있다면 해당 도구를 제공하는 워커나 클라이언트가 없는 것입니다. 사용자 정의 도구 제공하기를 참조하세요.

래핑된 MCP 도구 호출이 멈춤

MCP 클라이언트에 타임아웃이 없으면 래핑된 MCP 서버에 대한 멈춘 호출은 백스톱이 작동할 때에만 오류 도구 결과가 됩니다:

SDK백스톱작동 시점
Python워커 자체의 도구 호출 제한약 2.5분 후
TypeScriptMCP SDK의 기본 요청 타임아웃약 1분 후
Go워커가 기본 제한을 초과한 도구 호출을 취소함120초 후

이 페이지가 도움이 되었나요?