managed-agents-2026-04-01 베타 헤더가 필요합니다. 이 가이드에서 사용하는 Anthropic SDK는 이 헤더를 자동으로 추가합니다. Anthropic 베타 액세스를 참조하세요.
사전 요구 사항
시작하기 전에 다음이 필요합니다.SANDBOX_USER액션이 있는 CoreWeave API 액세스 토큰.- Anthropic 워크스페이스의 Claude Managed Agents 액세스 권한과 세션을 생성하는 클라이언트용 Console API 키.
agent_toolset_20260401로 설정된 기존 에이전트. Anthropic의 Managed Agents 퀵스타트에 따라 에이전트를 생성하고 해당 ID를 기록하세요.- SDK 예시의 경우
uv가 포함된 Python 3.11 이상 또는 Node.js 22 이상.
환경 만들기
Claude Console에서 Self-hosted 환경을 만드세요. 환경을 열고 환경 키를 생성하세요. 환경 ID를 기록하고 키를 안전하게 보관하세요. Anthropic의 환경 설정을 참고하세요. 환경 키는 이 환경에 대한 워커 인증에 사용됩니다. Console API 키는 클라이언트에서 세션을 생성하는 데 사용됩니다. 두 사용자 인증 정보를 별도로 관리하세요. 확인 작업에는 이 가이드에서 만든 워커만 있는 환경을 사용하세요. 이렇게 하면 다른 워커가 테스트 세션을 가져가는 것을 방지할 수 있습니다. 환경이 준비되면cws-agent 또는 Sandboxes SDK를 선택하여 워커를 시작한 다음 확인 작업을 실행하세요.
cws-agent로 빠르게 시작하기
cws-agent 설치 지침을 따르세요. 이 도구는 파일 시스템 스냅샷으로 작업 공간을 저장하고 복원할 수 있도록 스냅샷 볼륨을 설정합니다.
[ENVIRONMENT-KEY], [ENVIRONMENT-ID], [SANDBOX-NAME]을 각각 환경 키, 환경 ID, 샌드박스에 사용할 cws-agent 세션 이름으로 바꾸세요. 세션 이름은 소문자, 숫자, 하이픈을 사용해 1~40자로 지정하며, 소문자 또는 숫자로 시작해야 합니다.
/workspace/claude/0에서 워커 하나를 시작한 후 셸로 돌아옵니다. 이 도구는 환경 키를 샌드박스에 전달합니다.
워커의 터미널을 보려면 다음을 실행하세요:
cws-agent run 명령은 Managed Agents 대화를 처리하지 않습니다.
Sandboxes SDK로 설정하기
이 대안은 Anthropic의ant 워커를 샌드박스의 메인 프로세스로 시작합니다. cws-agent가 필요하지 않으며 스냅샷을 설정하지 않습니다.
Python 코드 스니펫은 이 가이드에서 생성한 가상 환경에서 실행하세요. TypeScript 코드 스니펫은 클라이언트를 설치한 프로젝트에 .mts 파일로 저장한 다음 npx tsx [FILENAME].mts로 실행하세요.
사용자 인증 정보 설정 및 클라이언트 설치
스크립트를 실행할 터미널에서 Console의 환경 키와 ID를 내보내세요.- Python
- TypeScript
Python 3.11 이상과
uv를 사용하세요:워커 시작하기
사용하는 언어에 맞는 스크립트를 표시된 파일 이름으로 저장하세요. 이 스크립트는 Bash가 포함된 Linux 이미지에ant CLI를 설치하고, 워커 하나를 시작한 다음 샌드박스 ID를 출력합니다. 클라이언트는 로컬 환경에서 ANTHROPIC_ENVIRONMENT_KEY를 읽고, 그 값을 샌드박스 요청에 전달하여 워커의 환경 변수를 설정합니다.
- Python
- TypeScript
start_claude_worker.py
- Python
- TypeScript
wait()가 반환될 수 있습니다. 샌드박스 ID가 출력되었다고 해서 워커가 인증되었거나 폴링 중이라는 의미는 아닙니다. 작업을 시작하기 전에 워커의 상태와 최근 로그를 확인하세요. [SANDBOX-ID]를 출력된 ID로 바꾸세요:
- Python
- TypeScript
선택: 시크릿 저장소 사용
환경 키 값 대신 Forge 시크릿 참조를 전달할 수 있습니다. 이 옵션을 사용하려면 Forge 인증과 서버리스 배치가 필요합니다. 환경 키를 담당 Forge 팀의 Secret Manager에 저장한 다음, 해당 팀의 사용자 인증 정보를 내보내세요.FORGE_API_KEY와 FORGE_TEAM은 예시로 든 환경 변수이므로 SDK가 자동으로 감지하지 않습니다.
- Python
- TypeScript
샌드박스를 생성하기 전에
AuthHeaders를 임포트하고 auth를 정의하세요.Sandbox.run()에 auth=auth를 전달하세요. 이후의 Python 예시에서도 이 설정을 포함하고, 모든 Sandbox.from_id() 호출에도 auth=auth를 전달하세요.[SECRET-NAME]을 팀 시크릿의 이름으로 바꾸세요.
- Python
- TypeScript
cwsandbox에서 Secret을 임포트하고, environment_variables에서 ANTHROPIC_ENVIRONMENT_KEY를 제거한 다음, Sandbox.run()에 secrets=[Secret(store="wandb", name="[SECRET-NAME]", env_var="ANTHROPIC_ENVIRONMENT_KEY")]를 추가하세요.작업 실행 및 확인
두 설정 방식 모두 사용자의 컴퓨터에서 세션 클라이언트를 실행하세요. 사용하는 언어에 맞는 Anthropic SDK를 설치하세요:- Python
- TypeScript
[ANTHROPIC-API-KEY]를 Console API 키로, [AGENT-ID]를 기존 에이전트 ID로, [ENVIRONMENT-ID]를 워커에 연결된 환경으로 바꾸세요:
- Python
- TypeScript
verify_claude_worker.py
- Python
- TypeScript
requires_action 상태로 중지되면 참조된 도구 이벤트를 확인하세요. evaluated_permission: "ask"가 설정된 Call은 Anthropic의 도구 확인 워크플로가 필요합니다. 허용된 Call은 워커가 처리합니다. Call이 멈춘 경우 워커의 로그를 확인하세요. 새 세션을 만들지 말고 세션 ID를 보관해 두었다가 해당 세션을 이어서 사용하세요.
작업이 완료되면 사용 중인 설정에 맞는 명령어로 샌드박스에서 파일을 읽으세요. [SANDBOX-NAME] 또는 [SANDBOX-ID]를 작업 공간 이름 또는 출력된 샌드박스 ID로 바꾸세요:
- cws-agent
- Sandboxes SDK
cwsandbox를 설치한 가상 환경을 다시 활성화하세요. TypeScript의 경우 SDK 코드 스니펫을 .mts 파일로 저장한 후 npx tsx로 실행하세요.
파일 내용은 클라이언트가 출력한 값과 일치해야 합니다. 이를 통해 에이전트의 도구 실행이 특정 CoreWeave 샌드박스와 연결되었음을 확인할 수 있습니다.
결과 보존 및 중지
진행 중인 작업이 완료될 때까지 기다린 후 필요한 결과를 샌드박스 밖으로 복사하세요. 그런 다음 설정에 맞는 명령으로 샌드박스를 중지하세요:- cws-agent
- 샌드박스 SDK
down은 중지하기 전에 작업 공간의 스냅샷을 생성합니다. 캡처에 실패하면 cws-agent status [SANDBOX-NAME]을 확인하고 실패 원인을 해결한 후 다시 시도하세요. 저장하지 않은 변경 사항을 삭제해도 된다면 down --no-snapshot을 사용하세요.문제 해결
다음 항목을 확인하여 일반적인 문제를 해결하세요:- 세션이 워커를 기다리는 경우 환경 ID, 워커 로그, 다른 작업이 이미 워커를 점유하고 있는지 확인하세요.
- 워커가 인증할 수 없는 경우 환경 키를 확인하세요. 세션 클라이언트에서 사용하는 Console API 키는 별도의 자격 증명입니다.
- 도구가 없는 경우 의존성을 포함한 이미지를 구축하세요. 예시에서는 Python 이미지를 사용하며 프로젝트별 도구 모음은 설치하지 않습니다.