managed-agents-2026-04-01 beta header. The Anthropic SDK used in this guide adds it automatically. See Anthropic beta access.
Prerequisites
Before you begin, you need the following:- Une clé API W&B. Ces exemples utilisent l’authentification W&B.
- Un accès à Claude Managed Agents dans votre workspace Anthropic, ainsi qu’une clé API Console pour le client qui crée les sessions.
- Un agent existant configuré avec
agent_toolset_20260401. Pour en créer un, suivez le guide de démarrage rapide de Managed Agents d’Anthropic, puis notez son ID. - Pour les exemples de SDK, Python 3.11 ou version ultérieure avec
uv, ou bien Node.js 22 ou version ultérieure.
cws-agent sélectionne l’authentification W&B :
Create an environment
In the Claude Console, create a Self-hosted environment. Open it and generate an environment key. Record the environment ID and store the key securely. See Anthropic’s environment setup. The environment key authenticates workers to this environment. The Console API key creates sessions from your client. Keep the two credentials separate. For the verification task, use an environment with only the worker created in this guide. That prevents another worker from claiming the test session. With the environment ready, choose eithercws-agent or the Sandbox SDK to start its worker, then run the verification task.
Quick start with cws-agent
Suivez les instructions d’installation decws-agent. L’outil configure un volume de snapshots qui permet d’enregistrer et de restaurer votre workspace à l’aide de snapshots du système de fichiers.
Replace [ENVIRONMENT-KEY], [ENVIRONMENT-ID], and [SANDBOX-NAME] with your environment key, environment ID, and a cws-agent session name for the sandbox. For the session name, use 1 to 40 lowercase letters, digits, or hyphens, starting with a letter or digit:
/workspace/claude/0 and returns to your shell. The tool passes the environment key into the sandbox.
To view the worker’s terminal, run:
cws-agent run command doesn’t drive Managed Agents conversations.
Set up with the Sandbox SDK
This alternative starts Anthropic’sant worker as the sandbox’s main process. It doesn’t require cws-agent or configure snapshots.
Run Python snippets in the virtual environment created in this guide. Save TypeScript snippets as .mts files in the project where you install the client, then run them with npx tsx [FILENAME].mts.
Configure credentials and install the client
Export the environment key and ID from the Console in the terminal where you run the script:- Python
- TypeScript
Utilisez Python 3.11 ou une version ultérieure, ainsi que
uv :Start the worker
Save the script for your language using the filename shown. The script installs theant CLI in a Linux image with Bash, starts one worker, and prints the sandbox ID. The client reads ANTHROPIC_ENVIRONMENT_KEY from your local environment and passes its value in the sandbox request to set the worker’s environment variable.
- Python
- TypeScript
start_claude_worker.py
- Python
- TypeScript
wait() can also return if the main process has already completed. A printed sandbox ID doesn’t confirm that the worker is authenticated or polling. Before starting a task, inspect its status and recent logs. Replace [SANDBOX-ID] with the printed ID:
- Python
- TypeScript
Facultatif : utiliser un gestionnaire de secrets
Au lieu de la valeur de la clé d’environnement, vous pouvez transmettre une référence de secret W&B. Les exemples du SDK utilisent déjà l’authentification W&B. Stockez la clé d’environnement dans le Secret Manager de votre équipe W&B, puis sélectionnez cette équipe avecWANDB_ENTITY s’il ne s’agit pas de votre entity par défaut.
Remplacez [SECRET-NAME] par le nom du secret de l’équipe :
- Python
- TypeScript
Importez
Secret depuis cwsandbox, supprimez ANTHROPIC_ENVIRONMENT_KEY de environment_variables, puis ajoutez secrets=[Secret(store="wandb", name="[SECRET-NAME]", env_var="ANTHROPIC_ENVIRONMENT_KEY")] à Sandbox.run().Run and verify a task
Run the session client on your own machine for either setup path. Install the Anthropic SDK for your language:- Python
- TypeScript
[ANTHROPIC-API-KEY] with your Console API key, [AGENT-ID] with your existing agent ID, and [ENVIRONMENT-ID] with the environment connected to your worker:
- Python
- TypeScript
verify_claude_worker.py
- Python
- TypeScript
requires_action, inspect the referenced tool events. Calls with evaluated_permission: "ask" need Anthropic’s tool-confirmation workflow. The worker handles allowed calls. If they stall, inspect its logs. Keep the session ID to continue that session rather than creating another one.
After the task completes, read the file from the sandbox with the command for your setup. Replace [SANDBOX-NAME] or [SANDBOX-ID] with the workspace name or printed sandbox ID:
- cws-agent
- Sandbox SDK
cwsandbox if needed. For TypeScript, save the SDK snippet as an .mts file and run it with npx tsx.
The file must match the value printed by the client. This ties the agent’s tool execution to the specific CoreWeave sandbox.
Keep results and stop
Wait for active tasks to finish and copy any results you need out of the sandbox. Then stop it using the command for your setup:- cws-agent
- Sandbox SDK
down crée un snapshot du workspace avant l’arrêt. Si la capture échoue, vérifiez cws-agent status [SANDBOX-NAME] et résolvez le problème avant de réessayer. Si vous pouvez vous permettre de perdre les modifications non enregistrées, utilisez down --no-snapshot.Troubleshoot
Use these checks to resolve common issues:- If the session waits for a worker, check the environment ID, the worker logs, and whether another task already occupies the worker.
- If the worker can’t authenticate, check its environment key. The Console API key used by the session client is a different credential.
- If a tool is missing, build an image with the required dependencies. The example uses a Python image and doesn’t install a project-specific toolchain.