1# Managed Agents — cURL / Raw HTTP
2 
3Use these examples when the user needs raw HTTP requests or is working without an SDK.
4 
5## Setup
6 
7```bash
8export ANTHROPIC_API_KEY="your-api-key"
9 
10# Common headers
11HEADERS=(
12  -H "Content-Type: application/json"
13  -H "x-api-key: $ANTHROPIC_API_KEY"
14  -H "anthropic-version: 2023-06-01"
15  -H "anthropic-beta: managed-agents-2026-04-01"
16)
17```
18 
19---
20 
21## Create an Environment
22 
23```bash
24curl -X POST https://api.anthropic.com/v1/environments \
25  "${HEADERS[@]}" \
26  -d '{
27    "name": "my-dev-env",
28    "config": {
29      "type": "cloud",
30      "networking": { "type": "unrestricted" }
31    }
32  }'
33```
34 
35### With restricted networking
36 
37```bash
38curl -X POST https://api.anthropic.com/v1/environments \
39  "${HEADERS[@]}" \
40  -d '{
41    "name": "restricted-env",
42    "config": {
43      "type": "cloud",
44      "networking": {
45        "type": "limited",
46        "allow_package_managers": true,
47        "allow_mcp_servers": true,
48        "allowed_hosts": ["api.example.com"]
49      }
50    }
51  }'
52```
53 
54---
55 
56## Create an Agent (required first step)
57 
58> ⚠️ **There is no inline agent config.** Under `managed-agents-2026-04-01`, `model`/`system`/`tools` are top-level fields on `POST /v1/agents`, not on the session. Always create the agent first — the session only takes `"agent": {"type": "agent", "id": "..."}`.
59 
60### Minimal
61 
62```bash
63# 1. Create the agent
64curl -X POST https://api.anthropic.com/v1/agents \
65  "${HEADERS[@]}" \
66  -d '{
67    "name": "Coding Assistant",
68    "model": "claude-opus-4-8",
69    "tools": [{ "type": "agent_toolset_20260401" }]
70  }'
71# → { "id": "agent_abc123", ... }
72 
73# 2. Start a session
74curl -X POST https://api.anthropic.com/v1/sessions \
75  "${HEADERS[@]}" \
76  -d '{
77    "agent": { "type": "agent", "id": "agent_abc123", "version": "1772585501101368014" },
78    "environment_id": "env_abc123"
79  }'
80```
81 
82### With system prompt, custom tools, and GitHub repo
83 
84```bash
85# 1. Create the agent
86curl -X POST https://api.anthropic.com/v1/agents \
87  "${HEADERS[@]}" \
88  -d '{
89    "name": "Code Reviewer",
90    "model": "claude-opus-4-8",
91    "system": "You are a senior code reviewer. Be thorough and constructive.",
92    "tools": [
93      { "type": "agent_toolset_20260401" },
94      {
95        "type": "custom",
96        "name": "run_linter",
97        "description": "Run the project linter on a file",
98        "input_schema": {
99          "type": "object",
100          "properties": {
101            "file_path": { "type": "string", "description": "Path to lint" }
102          },
103          "required": ["file_path"]
104        }
105      }
106    ]
107  }'
108 
109# 2. Start a session with the repo mounted
110curl -X POST https://api.anthropic.com/v1/sessions \
111  "${HEADERS[@]}" \
112  -d '{
113    "agent": { "type": "agent", "id": "agent_abc123", "version": "1772585501101368014" },
114    "environment_id": "env_abc123",
115    "title": "Code review session",
116    "resources": [
117      {
118        "type": "github_repository",
119        "url": "https://github.com/owner/repo",
120        "mount_path": "/workspace/repo",
121        "authorization_token": "ghp_...",
122        "branch": "feature-branch"
123      }
124    ]
125  }'
126```
127 
128---
129 
130## Send a User Message
131 
132```bash
133curl -X POST https://api.anthropic.com/v1/sessions/$SESSION_ID/events \
134  "${HEADERS[@]}" \
135  -d '{
136    "events": [
137      {
138        "type": "user.message",
139        "content": [{ "type": "text", "text": "Review the auth module for security issues" }]
140      }
141    ]
142  }'
143```
144 
145---
146 
147## Stream Events (SSE)
148 
149```bash
150curl -N https://api.anthropic.com/v1/sessions/$SESSION_ID/events/stream \
151  "${HEADERS[@]}"
152```
153 
154Response format:
155 
156```
157event: session.status_running
158data: {"type":"session.status_running","id":"sevt_...","processed_at":"..."}
159 
160event: agent.message
161data: {"type":"agent.message","id":"sevt_...","content":[{"type":"text","text":"I'll review..."}],"processed_at":"..."}
162 
163event: session.status_idle
164data: {"type":"session.status_idle","id":"sevt_...","processed_at":"..."}
165```
166 
167---
168 
169## Poll Events
170 
171```bash
172# Get all events
173curl https://api.anthropic.com/v1/sessions/$SESSION_ID/events \
174  "${HEADERS[@]}"
175 
176# Paginated — get next page of events
177curl "https://api.anthropic.com/v1/sessions/$SESSION_ID/events?page=page_abc123" \
178  "${HEADERS[@]}"
179```
180 
181---
182 
183## Provide Custom Tool Result
184 
185When the agent calls a custom tool, send the result back:
186 
187```bash
188curl -X POST https://api.anthropic.com/v1/sessions/$SESSION_ID/events \
189  "${HEADERS[@]}" \
190  -d '{
191    "events": [
192      {
193        "type": "user.custom_tool_result",
194        "custom_tool_use_id": "sevt_abc123",
195        "content": [{ "type": "text", "text": "No linting errors found." }]
196      }
197    ]
198  }'
199```
200 
201---
202 
203## Interrupt a Running Session
204 
205```bash
206curl -X POST https://api.anthropic.com/v1/sessions/$SESSION_ID/events \
207  "${HEADERS[@]}" \
208  -d '{
209    "events": [
210      {
211        "type": "interrupt"
212      }
213    ]
214  }'
215```
216 
217---
218 
219## Get Session Details
220 
221```bash
222curl https://api.anthropic.com/v1/sessions/$SESSION_ID \
223  "${HEADERS[@]}"
224```
225 
226---
227 
228## List Sessions
229 
230```bash
231curl https://api.anthropic.com/v1/sessions \
232  "${HEADERS[@]}"
233```
234 
235---
236 
237## Delete a Session
238 
239```bash
240curl -X DELETE https://api.anthropic.com/v1/sessions/$SESSION_ID \
241  "${HEADERS[@]}"
242```
243 
244---
245 
246## Upload a File
247 
248```bash
249curl -X POST https://api.anthropic.com/v1/files \
250  -H "x-api-key: $ANTHROPIC_API_KEY" \
251  -H "anthropic-version: 2023-06-01" \
252  -H "anthropic-beta: files-api-2025-04-14" \
253  -F "file=@path/to/file.txt"
254```
255 
256---
257 
258## List and Download Session Files
259 
260List files the agent wrote to `/mnt/session/outputs/` during a session, then download them.
261 
262```bash
263# List files associated with a session
264curl "https://api.anthropic.com/v1/files?scope_id=$SESSION_ID" \
265  -H "x-api-key: $ANTHROPIC_API_KEY" \
266  -H "anthropic-version: 2023-06-01" \
267  -H "anthropic-beta: files-api-2025-04-14,managed-agents-2026-04-01"
268 
269# Download a specific file
270curl "https://api.anthropic.com/v1/files/$FILE_ID/content" \
271  -H "x-api-key: $ANTHROPIC_API_KEY" \
272  -H "anthropic-version: 2023-06-01" \
273  -H "anthropic-beta: files-api-2025-04-14,managed-agents-2026-04-01" \
274  -o downloaded_file.txt
275```
276 
277---
278 
279## List Agents
280 
281```bash
282curl https://api.anthropic.com/v1/agents \
283  "${HEADERS[@]}"
284```
285 
286---
287 
288## MCP Server Integration
289 
290```bash
291# 1. Agent declares MCP server (no auth here — auth goes in a vault)
292curl -X POST https://api.anthropic.com/v1/agents \
293  "${HEADERS[@]}" \
294  -d '{
295    "name": "MCP Agent",
296    "model": "claude-opus-4-8",
297    "mcp_servers": [
298      { "type": "url", "name": "my-tools", "url": "https://my-mcp-server.example.com/sse" }
299    ],
300    "tools": [
301      { "type": "agent_toolset_20260401" },
302      { "type": "mcp_toolset", "mcp_server_name": "my-tools" }
303    ]
304  }'
305 
306# 2. Session attaches vault containing credentials for that MCP server URL
307curl -X POST https://api.anthropic.com/v1/sessions \
308  "${HEADERS[@]}" \
309  -d '{
310    "agent": "agent_abc123",
311    "environment_id": "env_abc123",
312    "vault_ids": ["vlt_abc123"]
313  }'
314```
315 
316See `shared/managed-agents-tools.md` §Vaults for creating vaults and adding credentials.
317 
318---
319 
320## Tool Configuration
321 
322```bash
323curl -X POST https://api.anthropic.com/v1/agents \
324  "${HEADERS[@]}" \
325  -d '{
326    "name": "Restricted Agent",
327    "model": "claude-opus-4-8",
328    "tools": [
329      {
330        "type": "agent_toolset_20260401",
331        "default_config": { "enabled": true },
332        "configs": [
333          { "name": "bash", "enabled": false }
334        ]
335      }
336    ]
337  }'
338```
339