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

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

큐 깊이 확인

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

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 상태로 전환됩니다. 워커는 다음 "lease heartbeat"(리스 하트비트)에서 이를 감지하고, 세션의 진행 중인 도구 호출을 취소한 후 종료를 확인합니다. 그러면 작업 항목은 stopped 상태가 됩니다.

워커의 확인을 기다리지 않고 작업 항목을 즉시 stopped로 표시하려면 force=True를 전달하세요.

이러한 호출은 워커 호스트가 아닌 운영 도구에서 실행되므로 ANTHROPIC_WORK_ID가 자동으로 설정되지 않습니다. 다음 예제를 실행하기 전에 대상 작업 항목의 ID로 설정하세요. 작업 항목의 ID를 찾으려면 Environments Work 엔드포인트를 통해 환경의 작업 항목을 나열하세요.

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가 두 신호를 직접 처리합니다: 진행 중인 도구 호출을 취소하고, 오류 결과를 게시하며, 작업 항목을 해제합니다.
   자체 프로세스로 실행되는 SDK 워커	EnvironmentWorker는 신호 핸들러를 설치하지 않습니다. 독립 실행형 워커 예제처럼 신호 핸들러에서 워커를 취소하세요.
   웹훅 서버 내부의 SDK 워커	웹훅 예제처럼 서버 자체의 종료 훅에서 워커를 취소하세요. 워커가 서버의 신호를 가로채서는 안 됩니다.

2. SIGTERM으로 워커를 중지하고, 강제 종료 전에 최소 30초를 허용하세요. 최종 업로드에 그만큼 시간이 걸릴 수 있습니다. Docker는 기본적으로 중지 신호 후 10초가 지나면 SIGKILL을 보냅니다. docker run의 --stop-timeout 또는 오케스트레이터의 종료 유예 기간으로 이 제한을 늘리세요.

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

문제 해결

워커가 연결되지 않음

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

세션이 대기 상태로 유지됨

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

메모리 스토어 마운트 실패

워커는 마운트 및 백그라운드 동기화 실패를 세션에 보고하지 않고 로그에 기록합니다. 읽기 전용 거부만 도구 오류로 에이전트에 전달됩니다(읽기 전용 스토어와 충돌 참조).

워커가 세션을 가져올 때 메모리 스토어를 마운트할 수 없으면 작업 항목을 실패 처리합니다. 세션은 오류 이벤트를 발생시키지 않고 유휴 상태로 유지됩니다.

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

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

래핑된 MCP 도구 호출이 멈춤

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