Manage Claude Managed Agents end to end through a Python helper CLI, with ant CLI equivalents documented as a secondary path. Use this whenever the user want...
---
name: claude-managed-agents
description: Manage Claude Managed Agents end to end through a Python helper CLI, with ant CLI equivalents documented as a secondary path. Use this whenever the user wants to create, update, list, archive, or inspect Claude Managed Agents agents, environments, sessions, or event streams; configure built-in tools, MCP servers, skills, packages, or networking; send session messages, interrupts, confirmations, or custom tool results; or work with Anthropic's managed-agents beta lifecycle from this machine.
compatibility:
tools: Read, Edit, Bash
dependencies: Python 3, ANTHROPIC_API_KEY, optional anthropic SDK, optional ant CLI
---
# Claude Managed Agents
Use this skill to operate Anthropic Claude Managed Agents safely and cleanly from this machine.
This skill is **SDK-first** through the bundled Python helper, with **ant CLI** documented as a secondary operator lane. Raw REST is only for debugging or when the SDK is unavailable.
## What this skill handles
- agents
- create
- update
- retrieve
- list
- list versions
- archive
- delete
- environments
- create
- update
- retrieve
- list
- archive
- delete
- sessions
- create
- retrieve
- list
- archive
- delete
- session events
- send user messages
- interrupt and redirect
- list history
- stream live SSE events
- send tool confirmations
- send custom tool results
- files
- upload local files to the Files API
- list, download, and delete files
- return file IDs for mounting into sessions
- session resources
- add resources to running sessions
- list mounted resources
- delete mounted resources by resource ID
- configuration domains
- built-in toolset controls
- MCP servers
- skills
- packages
- networking
- vault IDs
- mounted resources
- diagnostics
- local preflight via `doctor`
- optional live read-only connectivity checks via `doctor --live`
## Required environment
Set:
- `ANTHROPIC_API_KEY`
Optional:
- `ANTHROPIC_API_BASE_URL`
- `ANTHROPIC_MANAGED_AGENTS_BETA`
- `ANTHROPIC_TIMEOUT_SECONDS`
The managed-agents beta header is required. The helper uses `managed-agents-2026-04-01` by default.
## Script
Use:
- `scripts/managed_agents.py`
Run it with Python 3:
```bash
python3 ~/.openclaw/skills/claude-managed-agents/scripts/managed_agents.py --help
```
Run a preflight before live work when the lane feels sketchy:
```bash
python3 ~/.openclaw/skills/claude-managed-agents/scripts/managed_agents.py \
doctor \
--allowed-host api.example.com
```
## Operating model
Prefer this order:
1. Python helper CLI
2. documented `ant` equivalent when the user wants a direct CLI path
3. raw REST only when troubleshooting edge cases
The helper supports:
- `--backend auto` (default)
- `--backend sdk`
- `--backend http`
Use `sdk` when the Anthropic Python SDK is installed. Use `http` if the SDK is missing or behaving oddly.
## Safe workflow
### For new setups
1. confirm `ANTHROPIC_API_KEY` exists
2. create or inspect the target agent
3. create or inspect the target environment
4. create the session
5. send a user message event
6. stream or list events to monitor progress
### For mid-run steering
1. list or stream session events
2. if the agent is going the wrong direction, send:
- `user.interrupt`
- followed by a new `user.message`
3. if the session is waiting on approval, send `user.tool_confirmation`
4. if the session is waiting on a custom tool result, send `user.custom_tool_result`
## High-value guardrails
- Do not guess event IDs, tool use IDs, or custom tool use IDs.
- For approval flows, read recent events first and use the exact pending tool ID.
- For custom tools, return only the result the tool actually produced. Do not fabricate success.
- Prefer limited networking with explicit hosts for production-oriented environments. Use bare hostnames like `api.example.com`, not full URLs.
- Do not delete environments, sessions, or agents casually. Archive first unless the user clearly wants hard deletion.
- Archiving is usually the safer lifecycle move than deletion, but disposable smoke fixtures may need delete for full cleanup.
## Recommended command patterns
### Create an agent with the full built-in toolset
```bash
python3 ~/.openclaw/skills/claude-managed-agents/scripts/managed_agents.py \
agent create \
--name "Coding Assistant" \
--model claude-sonnet-4-6 \
--system "You are a helpful coding agent." \
--agent-toolset
```
### Run doctor before a live session
```bash
python3 ~/.openclaw/skills/claude-managed-agents/scripts/managed_agents.py \
doctor \
--live \
--allowed-host api.example.com
```
### Create an environment with limited networking and pip packages
```bash
python3 ~/.openclaw/skills/claude-managed-agents/scripts/managed_agents.py \
environment create \
--name "python-dev" \
--network limited \
--allowed-host api.example.com \
--allow-package-managers \
--pip pandas==2.2.0 \
--pip numpy==2.1.0
```
### Upload a file and get a file ID
```bash
python3 ~/.openclaw/skills/claude-managed-agents/scripts/managed_agents.py \
file upload \
--file-path ./data.csv \
--only-id
```
### Create a session with an uploaded file mounted in the container
```bash
FILE_ID=$(python3 ~/.openclaw/skills/claude-managed-agents/scripts/managed_agents.py \
file upload \
--file-path ./data.csv \
--only-id)
python3 ~/.openclaw/skills/claude-managed-agents/scripts/managed_agents.py \
session create \
--agent-id agent_123 \
--environment-id env_123 \
--title "Repo analysis" \
--resource-json "{\"type\":\"file\",\"file_id\":\"${FILE_ID}\",\"mount_path\":\"/workspace/data.csv\"}"
```
### Add another file to a running session
```bash
python3 ~/.openclaw/skills/claude-managed-agents/scripts/managed_agents.py \
session resource add \
--session-id sess_123 \
--file-id file_abc123 \
--mount-path /workspace/config.json
```
### Download a session-scoped file artifact
```bash
python3 ~/.openclaw/skills/claude-managed-agents/scripts/managed_agents.py \
file download \
--file-id file_abc123 \
--output ./artifact.txt
```
Use this mainly for generated artifacts. Uploaded source files often come back with `downloadable: false`.
### Send a user message to the session
```bash
python3 ~/.openclaw/skills/claude-managed-agents/scripts/managed_agents.py \
session send \
--session-id sess_123 \
--message "Summarize the repository and propose the next refactor."
```
### Interrupt and redirect the session
```bash
python3 ~/.openclaw/skills/claude-managed-agents/scripts/managed_agents.py \
session send \
--session-id sess_123 \
--interrupt \
--message "Stop the broad audit and focus on the auth bug in line 42."
```
### Stream events until idle
```bash
python3 ~/.openclaw/skills/claude-managed-agents/scripts/managed_agents.py \
session stream \
--session-id sess_123 \
--until-idle
```
### Approve a pending tool call
```bash
python3 ~/.openclaw/skills/claude-managed-agents/scripts/managed_agents.py \
session send \
--session-id sess_123 \
--confirm-tool-use-id tool_evt_123 \
--confirm-result allow
```
### Delete an agent when the user explicitly wants permanent cleanup
```bash
python3 ~/.openclaw/skills/claude-managed-agents/scripts/managed_agents.py \
agent delete \
--agent-id agent_123
```
### Return a custom tool result
```bash
python3 ~/.openclaw/skills/claude-managed-agents/scripts/managed_agents.py \
session send \
--session-id sess_123 \
--custom-tool-use-id custom_evt_123 \
--custom-tool-text '{"temperature_f":72,"condition":"sunny"}'
```
## When to use ant CLI instead
Use `ant` when the user explicitly wants Anthropic's native CLI experience, copy-pasteable operator commands, or quick manual inspection.
Examples:
```bash
ant beta:agents create --name "Coding Assistant" --model '{id: claude-sonnet-4-6}' --tool '{type: agent_toolset_20260401}'
ant beta:environments list
ant beta:sessions retrieve --session-id "$SESSION_ID"
ant beta:sessions:events send --session-id "$SESSION_ID"
ant beta:sessions stream --session-id "$SESSION_ID"
```
## References in this skill
Read these when needed:
- `references/quickstart.md` for the end-to-end happy path
- `references/lifecycle-recipes.md` for lifecycle operations and payload patterns
- `references/files-api.md` for upload, list, download, delete, and session resource workflows
- `references/event-model.md` for streaming, interruptions, approvals, and custom tools
- `references/ant-cli-recipes.md` for direct ant commands mirroring the helper
- `references/known-gaps.md` for dependency assumptions and operational caveats
## Output contract
Default answer shape:
- short lead sentence with the answer or current state
- 2-6 bullets with the important IDs, statuses, or lifecycle facts
- exact next command when a follow-up step is likely
If the user asks for raw JSON, return the raw JSON instead.
don't have the plugin yet? install it then click "run inline in claude" again.