api-20261019T193710Z / page 3 of 4 / documentation capture

manage-claude/workspaces Changed · +6 / -6 lines

from line 857

857857

858858The header is absent when the credential doesn't resolve to a workspace (for example, on Admin API requests) or when the request fails before authentication completes, such as a 401 error.

859859

860The following examples send a Messages API request and print the workspace ID from the response headers:

860The following examples send a Messages API request and read the workspace ID from the response headers:

861861

862862<CodeGroup>

863863 ```bash cURL

864 # -D - prints the response headers; -o /dev/null discards the body

865 curl -sS -D - -o /dev/null https://api.anthropic.com/v1/messages \

864 # -i prints the response headers, including anthropic-workspace-id, before the body

865 curl -sS -i https://api.anthropic.com/v1/messages \

866866 -H "x-api-key: $ANTHROPIC_API_KEY" \

867867 -H "anthropic-version: 2023-06-01" \

868868 -H "content-type: application/json" \

from line 870

870870 "model": "claude-opus-5-5",

871871 "max_tokens": 1024,

872872 "messages": [{"role": "user", "content": "Hello, Claude"}]

873 }' | grep -i '^anthropic-workspace-id'

873 }'

874874 ```

875875

876876 ```bash CLI

877877 # --debug prints the HTTP response, including the Anthropic-Workspace-Id

878 # header, to stderr; > /dev/null hides the JSON body on stdout

878 # header, to stderr

879879 ant --debug messages create \

880880 --model claude-opus-5-5 \

881881 --max-tokens 1024 \

882 --message '{role: user, content: "Hello, Claude"}' > /dev/null

882 --message '{role: user, content: "Hello, Claude"}'

883883 ```

884884

885885 ```python Python

managed-agents/agent-setup Changed · +13 / -28 lines

from line 38

3838

3939<CodeGroup defaultLanguage="CLI">

4040 ```bash cURL

41 agent=$(curl -fsSL https://api.anthropic.com/v1/agents \

41 curl -fsSL https://api.anthropic.com/v1/agents \

4242 -H "x-api-key: $ANTHROPIC_API_KEY" \

4343 -H "anthropic-version: 2023-06-01" \

4444 -H "anthropic-beta: managed-agents-2026-04-01" \

from line 48

4848 "model": "claude-opus-5-5",

4949 "system": "You are a helpful coding agent.",

5050 "tools": [{"type": "agent_toolset_20260401"}]

51 }')

52

53 AGENT_ID=$(jq -r '.id' <<< "$agent")

54 AGENT_VERSION=$(jq -r '.version' <<< "$agent")

51 }'

5552 ```

5653

5754 <CodeGroupItem>

from line 211

214211

215212Like `speed` (csharp, go: `Speed`) and `effort` (csharp, go: `Effort`), `inference_geo` (java, php: `inferenceGeo`; csharp, go: `InferenceGeo`) is set through the object form of `model` (csharp, go: `Model`): pass `model` (csharp, go: `Model`) as an object and set `inference_geo` (java, php: `inferenceGeo`; csharp, go: `InferenceGeo`) alongside `id` (csharp, go: `ID`). The field accepts `"us"` or `"global"`. When it's unset, each model request follows the workspace's default inference geo at the time it's served. See [Data residency](https://platform.claude.com/docs/en/manage-claude/data-residency) for the workspace-level geo controls and pricing.

216213

217The following example pins an agent to US inference and prints the `inference_geo` (java, php: `inferenceGeo`; csharp, go: `InferenceGeo`) value from the agent's `model` (csharp, go: `Model`) object:

214The following example pins an agent to US inference. The response carries the `inference_geo` (java, php: `inferenceGeo`; csharp, go: `InferenceGeo`) value in the agent's `model` (csharp, go: `Model`) object:

218215

219216<CodeGroup defaultLanguage="CLI">

220217 ```bash cURL

221 agent=$(curl -fsSL https://api.anthropic.com/v1/agents \

218 curl -fsSL https://api.anthropic.com/v1/agents \

222219 -H "x-api-key: $ANTHROPIC_API_KEY" \

223220 -H "anthropic-version: 2023-06-01" \

224221 -H "anthropic-beta: managed-agents-2026-04-01" \

from line 224

227224 "name": "Geo-pinned assistant",

228225 "model": {"id": "claude-opus-5-5", "inference_geo": "us"},

229226 "system": "You are a helpful assistant."

230 }')

231

232 echo "Inference geo: $(jq -r '.model.inference_geo' <<< "$agent")"

227 }'

233228 ```

234229

235230 <CodeGroupItem>

from line 353

358353

359354<CodeGroup defaultLanguage="CLI">

360355 ```bash cURL

361 updated_agent=$(curl -fsSL "https://api.anthropic.com/v1/agents/$AGENT_ID" \

356 curl -fsSL "https://api.anthropic.com/v1/agents/$AGENT_ID" \

362357 -H "x-api-key: $ANTHROPIC_API_KEY" \

363358 -H "anthropic-version: 2023-06-01" \

364359 -H "anthropic-beta: managed-agents-2026-04-01" \

from line 362

367362 "version": '"$AGENT_VERSION"',

368363 "system": "You are a helpful coding agent. Always write tests."

369364 }'

370 )

371

372 echo "New version: $(jq -r '.version' <<< "$updated_agent")"

373365 ```

374366

375367 <CodeGroupItem>

from line 461

469461

470462<CodeGroup>

471463 ```bash cURL

472 updated_agent=$(curl -fsSL "https://api.anthropic.com/v1/agents/$AGENT_ID" \

464 curl -fsSL "https://api.anthropic.com/v1/agents/$AGENT_ID" \

473465 -H "x-api-key: $ANTHROPIC_API_KEY" \

474466 -H "anthropic-version: 2023-06-01" \

475467 -H "anthropic-beta: managed-agents-2026-04-01" \

from line 468

476468 -H "content-type: application/json" \

477469 -d '{

478470 "description": "Writes and reviews code."

479 }')

480

481 echo "New version: $(jq -r '.version' <<< "$updated_agent")"

471 }'

482472 ```

483473

484474 ```bash CLI

from line 566

576566

577567<CodeGroup defaultLanguage="CLI">

578568 ```bash cURL

579 cleared_agent=$(curl -fsSL "https://api.anthropic.com/v1/agents/$AGENT_ID" \

569 curl -fsSL "https://api.anthropic.com/v1/agents/$AGENT_ID" \

580570 -H "x-api-key: $ANTHROPIC_API_KEY" \

581571 -H "anthropic-version: 2023-06-01" \

582572 -H "anthropic-beta: managed-agents-2026-04-01" \

from line 575

585575 "description": null,

586576 "metadata": {"team": null},

587577 "multiagent": {"type": "multiagent_20261001", "workflows": null}

588 }')

589

590 echo "Description: $(jq -r '.description' <<< "$cleared_agent")"

578 }'

591579 ```

592580

593581 <CodeGroupItem>

from line 719

731719 curl -fsSL "https://api.anthropic.com/v1/agents/$AGENT_ID/versions" \

732720 -H "x-api-key: $ANTHROPIC_API_KEY" \

733721 -H "anthropic-version: 2023-06-01" \

734 -H "anthropic-beta: managed-agents-2026-04-01" \

735 | jq -r '.data[] | "Version \(.version): \(.updated_at)"'

722 -H "anthropic-beta: managed-agents-2026-04-01"

736723 ```

737724

738725 ```bash CLI

from line 781

794781

795782<CodeGroup>

796783 ```bash cURL

797 archived=$(curl -fsSL -X POST "https://api.anthropic.com/v1/agents/$AGENT_ID/archive" \

784 curl -fsSL -X POST "https://api.anthropic.com/v1/agents/$AGENT_ID/archive" \

798785 -H "x-api-key: $ANTHROPIC_API_KEY" \

799786 -H "anthropic-version: 2023-06-01" \

800 -H "anthropic-beta: managed-agents-2026-04-01")

801

802 echo "Archived at: $(jq -r '.archived_at' <<< "$archived")"

787 -H "anthropic-beta: managed-agents-2026-04-01"

803788 ```

804789

805790 ```bash CLI

managed-agents/define-outcomes Changed · +16 / -28 lines

from line 290

290290<CodeGroup>

291291 ```bash cURL

292292 # Create a session

293 session=$(curl -fsSL https://api.anthropic.com/v1/sessions \

293 curl -fsSL https://api.anthropic.com/v1/sessions \

294294 -H "x-api-key: $ANTHROPIC_API_KEY" \

295295 -H "anthropic-version: 2023-06-01" \

296296 -H "anthropic-beta: managed-agents-2026-04-01" \

from line 299

299299 "environment_id": "'"$ENVIRONMENT_ID"'",

300300 "title": "Financial analysis on Costco"

301301 }'

302 )

303 SESSION_ID=$(jq -r '.id' <<<"$session")

304302

305 # Define the outcome — agent starts working on receipt

303 # Define the outcome: SESSION_ID is the id from the create response

304 # The agent starts working when it receives the event

306305 curl -fsSL "https://api.anthropic.com/v1/sessions/$SESSION_ID/events" \

307306 -H "x-api-key: $ANTHROPIC_API_KEY" \

308307 -H "anthropic-version: 2023-06-01" \

from line 315

316315 "max_iterations": 5

317316 }

318317 ]

319 }' >/dev/null

318 }'

320319 # or: "rubric": {"type": "file", "file_id": "'"$RUBRIC_ID"'"}

321320 # "max_iterations" is optional; default 3, max 20

322321 ```

from line 322

323322

324323 ```bash CLI

325324 # Create a session

326 SESSION_ID=$(ant beta:sessions create \

325 ant beta:sessions create \

327326 --agent "$AGENT_ID" \

328327 --environment-id "$ENVIRONMENT_ID" \

329 --title "Financial analysis on Costco" \

330 --transform id --raw-output)

328 --title "Financial analysis on Costco"

331329

332 # Define the outcome — agent starts working on receipt

330 # Define the outcome: SESSION_ID is the id from the create response

331 # The agent starts working when it receives the event

333332 ant beta:sessions:events send --session-id "$SESSION_ID" <<YAML

334333 events:

335334 - type: user.define_outcome

from line 711

712711 -H "anthropic-version: 2023-06-01" \

713712 -H "anthropic-beta: managed-agents-2026-04-01"

714713

715 # Download a file

716 FILE_ID=$(curl -fsSL "https://api.anthropic.com/v1/files?scope_id=$SESSION_ID" \

714 # Download a file by the ID from the list

715 curl -fsSL "https://api.anthropic.com/v1/files/$FILE_ID/content" \

717716 -H "x-api-key: $ANTHROPIC_API_KEY" \

718717 -H "anthropic-version: 2023-06-01" \

719 -H "anthropic-beta: managed-agents-2026-04-01" | jq -r '.data[0].id // empty')

720 if [[ -n $FILE_ID ]]; then

721 curl -fsSL "https://api.anthropic.com/v1/files/$FILE_ID/content" \

722 -H "x-api-key: $ANTHROPIC_API_KEY" \

723 -H "anthropic-version: 2023-06-01" \

724 -H "anthropic-beta: managed-agents-2026-04-01" \

725 -o /tmp/output.txt

726 fi

718 -H "anthropic-beta: managed-agents-2026-04-01" \

719 -o /tmp/output.txt

727720 ```

728721

729722 ```bash CLI

from line 724

731724 # scope_id filtering requires the managed-agents beta on the files request

732725 ant beta:files list --scope-id "$SESSION_ID" --beta managed-agents-2026-04-01

733726

734 # Download a file

735 FILE_ID=$(ant beta:files list --scope-id "$SESSION_ID" \

736 --beta managed-agents-2026-04-01 \

737 --transform 'data[0].id' --raw-output)

738 if [[ -n $FILE_ID ]]; then

739 ant files download --file-id "$FILE_ID" --output /tmp/output.txt

740 fi

727 # Download a file by the ID from the list

728 ant files download --file-id "$FILE_ID" --output /tmp/output.txt

741729 ```

742730

743731 ```python Python

managed-agents/dreams Changed · +6 / -16 lines

from line 204

204204

205205<CodeGroup>

206206 ```bash cURL

207 while true; do

208 dream=$(curl -s "https://api.anthropic.com/v1/dreams/$dream_id" \

209 -H "x-api-key: $ANTHROPIC_API_KEY" \

210 -H "anthropic-version: 2023-06-01" \

211 -H "anthropic-beta: managed-agents-2026-04-01,dreaming-2026-04-21")

212 status=$(jq -r '.status' <<< "$dream")

213 echo "status=$status input_tokens=$(jq -r '.usage.input_tokens' <<< "$dream")"

214 [[ "$status" == "pending" || "$status" == "running" ]] || break

215 sleep 10

216 done

207 curl -s "https://api.anthropic.com/v1/dreams/$dream_id" \

208 -H "x-api-key: $ANTHROPIC_API_KEY" \

209 -H "anthropic-version: 2023-06-01" \

210 -H "anthropic-beta: managed-agents-2026-04-01,dreaming-2026-04-21"

217211 ```

218212

219213 ```bash CLI

from line 298

304298

305299<CodeGroup>

306300 ```bash cURL

307 # After the dream ends, the memory_store output holds the rebuilt store

308 output_store_id=$(jq -r 'first(.outputs[] | select(.type == "memory_store")).memory_store_id' <<< "$dream")

309

301 # $output_store_id is the memory_store_id of the completed dream's memory_store output

310302 curl -s https://api.anthropic.com/v1/sessions \

311303 -H "x-api-key: $ANTHROPIC_API_KEY" \

312304 -H "anthropic-version: 2023-06-01" \

from line 314

322314 ```

323315

324316 ```bash CLI

325 output_store_id=$(ant beta:dreams retrieve --dream-id "$dream_id" --format json |

326 jq -r 'first(.outputs[] | select(.type == "memory_store")).memory_store_id')

327

317 # $output_store_id is the memory_store_id of the completed dream's memory_store output

328318 ant beta:sessions create <<YAML

329319 agent: $agent_id

330320 environment_id: $environment_id

managed-agents/event-deltas Changed · +16 / -139 lines

from line 107

107107

108108The following examples opt in to `agent.message` previews and reconcile them with the buffered event:

109109

110<CodeGroup exclude="shell:CLI">

111 ```bash cURL

112 # Opt in to agent.message previews via event_deltas, then accumulate manually.

113 exec {stream}< <(

114 curl --fail-with-body -sS -N \

115 "https://api.anthropic.com/v1/sessions/$SESSION_ID/events/stream?beta=true&event_deltas%5B%5D=agent.message" \

116 -H "x-api-key: $ANTHROPIC_API_KEY" \

117 -H "anthropic-version: 2023-06-01" \

118 -H "anthropic-beta: managed-agents-2026-04-01" \

119 -H "accept: text/event-stream"

120 )

110<CodeGroup exclude="shell:cURL, shell:CLI">

111 <CodeGroupItem language="cURL">

112 This workflow needs more logic than a single shell command. Use the [Claude SDK](https://platform.claude.com/docs/en/cli-sdks-libraries/overview) to run it.

113 </CodeGroupItem>

121114

122 curl --fail-with-body -sS \

123 "https://api.anthropic.com/v1/sessions/$SESSION_ID/events?beta=true" \

124 -H "x-api-key: $ANTHROPIC_API_KEY" \

125 -H "anthropic-version: 2023-06-01" \

126 -H "anthropic-beta: managed-agents-2026-04-01" \

127 -H "content-type: application/json" \

128 -d '{

129 "events": [

130 {

131 "type": "user.message",

132 "content": [{"type": "text", "text": "In one short sentence, describe what an event delta is."}]

133 }

134 ]

135 }' >/dev/null

136

137 # Accumulate deltas keyed by (message id, content index); the final

138 # agent.message carries the full text, so it replaces every preview for that id.

139 declare -A preview

140 while IFS= read -r -u "$stream" event_line; do

141 [[ $event_line == data:* ]] || continue

142 event_json=${event_line#data: }

143 case $(jq -r '.type' <<<"$event_json") in

144 event_start)

145 preview_id=$(jq -r '.event.id' <<<"$event_json")

146 printf '[event_start id=%s]\n' "$preview_id"

147 ;;

148 event_delta)

149 preview_key=$(jq -r '.event_id + ":" + (.delta.index | tostring)' <<<"$event_json")

150 preview[$preview_key]+=$(jq -r '.delta.content.text' <<<"$event_json")

151 printf '[event_delta] %s\n' "${preview[$preview_key]}"

152 ;;

153 agent.message)

154 msg_id=$(jq -r '.id' <<<"$event_json")

155 for preview_key in "${!preview[@]}"; do

156 [[ $preview_key == "$msg_id":* ]] && unset "preview[$preview_key]"

157 done

158 printf '[agent.message id=%s] ' "$msg_id"

159 jq -j '.content[] | select(.type == "text") | .text' <<<"$event_json"

160 printf '\n'

161 ;;

162 span.model_request_end)

163 for preview_key in "${!preview[@]}"; do

164 printf '[closing unreconciled preview for %s]\n' "${preview_key%%:*}"

165 done

166 preview=()

167 ;;

168 session.status_idle)

169 break

170 ;;

171 esac

172 done

173 exec {stream}<&-

174 ```

175

176115 <CodeGroupItem language="CLI">

177116 This workflow needs more logic than a single shell command. Use the [Claude SDK](https://platform.claude.com/docs/en/cli-sdks-libraries/overview) to run it.

178117 </CodeGroupItem>

from line 568

629568

630569<CodeGroup>

631570 ```bash cURL

632 # List the session's threads and pick a child: child threads carry a non-null

633 # parent_thread_id, and the primary thread's parent_thread_id is null.

634 THREAD_ID=$(

635 curl --fail-with-body -sS \

636 "https://api.anthropic.com/v1/sessions/$SESSION_ID/threads?beta=true" \

637 -H "x-api-key: $ANTHROPIC_API_KEY" \

638 -H "anthropic-version: 2023-06-01" \

639 -H "anthropic-beta: managed-agents-2026-04-01" |

640 jq -er 'first(.data[] | select(.parent_thread_id != null)).id'

641 )

642

643 # The child thread's stream takes the same event_deltas[] parameter as the

644 # session stream. Percent-encode the brackets (%5B%5D) and quote the URL.

645 exec {stream}< <(

646 curl --fail-with-body -sS -N \

647 "https://api.anthropic.com/v1/sessions/$SESSION_ID/threads/$THREAD_ID/stream?beta=true&event_deltas%5B%5D=agent.message" \

648 -H "x-api-key: $ANTHROPIC_API_KEY" \

649 -H "anthropic-version: 2023-06-01" \

650 -H "anthropic-beta: managed-agents-2026-04-01" \

651 -H "accept: text/event-stream"

652 )

653

654 while IFS= read -r -u "$stream" event_line; do

655 [[ $event_line == data:* ]] || continue

656 event_json=${event_line#data: }

657 case $(jq -r '.type' <<<"$event_json") in

658 event_delta)

659 jq -j '.delta.content.text' <<<"$event_json"

660 ;;

661 agent.message)

662 # The buffered event is the authoritative record; render its content.

663 printf '\n'

664 jq -j '.content[] | select(.type == "text") | .text' <<<"$event_json"

665 printf '\n'

666 ;;

667 session.thread_status_idle)

668 break

669 ;;

670 esac

671 done

672 exec {stream}<&-

571 # The thread stream takes the same event_deltas[] parameter as the session stream.

572 # Percent-encode the brackets (%5B%5D) and quote the URL.

573 curl --fail-with-body -sS -N \

574 "https://api.anthropic.com/v1/sessions/$SESSION_ID/threads/$THREAD_ID/stream?beta=true&event_deltas%5B%5D=agent.message" \

575 -H "x-api-key: $ANTHROPIC_API_KEY" \

576 -H "anthropic-version: 2023-06-01" \

577 -H "anthropic-beta: managed-agents-2026-04-01" \

578 -H "accept: text/event-stream"

673579 ```

674580

675581 ```bash CLI

676 # List the session's threads and pick a child: child threads carry a non-null

677 # parent_thread_id, and the primary thread's parent_thread_id is null

678 # (--transform's #(parent_thread_id!=~null) query matches non-null values).

679 THREAD_ID=$(ant beta:sessions:threads list \

582 # The thread stream takes the same event_deltas parameter as the session stream,

583 # one --event-delta flag per event type to preview.

584 ant beta:sessions:threads:events stream \

680585 --session-id "$SESSION_ID" \

681 --format raw --transform 'data.#(parent_thread_id!=~null).id' --raw-output)

682

683 # The child thread's stream takes the same event_deltas parameter as the

684 # session stream, one --event-delta flag per event type to preview. @tostr

685 # re-encodes each text field as a JSON string, so every value stays on one

686 # YAML line and jq's fromjson recovers the original text.

687 transform='{type,frag:delta.content.text|@tostr,text:content.#(type=="text").text|@tostr}'

688 exec {stream}< <(ant beta:sessions:threads:events stream \

689 --session-id "$SESSION_ID" \

690586 --thread-id "$THREAD_ID" \

691 --event-delta agent.message \

692 --transform "$transform" \

693 --format yaml)

694

695 type=

696 while IFS= read -r -u "$stream" line; do

697 case "$line" in

698 type:\ session.thread_status_idle) break ;;

699 type:\ *) type=${line#type: } ;;

700 frag:*)

701 [[ $type == event_delta ]] || continue

702 jq -j fromjson <<<"${line#frag: }" ;;

703 text:*)

704 [[ $type == agent.message ]] || continue

705 # The buffered event is the authoritative record; render its content.

706 printf '\n'

707 jq -r fromjson <<<"${line#text: }" ;;

708 esac

709 done

710 exec {stream}<&-

587 --event-delta agent.message

711588 ```

712589

713590 ```python Python

managed-agents/events-and-streaming Changed · +23 / -161 lines

from line 27

2727

2828Stream events from the session to receive real-time updates as the agent works. A stream delivers only the events emitted after it opens, so open the stream before you send events to avoid a race condition.

2929

30<CodeGroup exclude="shell:CLI">

30<CodeGroup>

3131 ```bash cURL

32 # Open the stream first, then send the user message

33 exec {stream}< <(

34 curl --fail-with-body -sS -N \

35 "https://api.anthropic.com/v1/sessions/$SESSION_ID/events/stream?beta=true" \

36 -H "x-api-key: $ANTHROPIC_API_KEY" \

37 -H "anthropic-version: 2023-06-01" \

38 -H "anthropic-beta: managed-agents-2026-04-01" \

39 -H "content-type: application/json" \

40 -H "accept: text/event-stream"

41 )

42

43 curl --fail-with-body -sS \

44 "https://api.anthropic.com/v1/sessions/$SESSION_ID/events?beta=true" \

32 # Open the stream before you send the first event: only later events are delivered.

33 curl --fail-with-body -sS -N \

34 "https://api.anthropic.com/v1/sessions/$SESSION_ID/events/stream?beta=true" \

4535 -H "x-api-key: $ANTHROPIC_API_KEY" \

4636 -H "anthropic-version: 2023-06-01" \

4737 -H "anthropic-beta: managed-agents-2026-04-01" \

48 -H "content-type: application/json" \

49 -d '{

50 "events": [

51 {

52 "type": "user.message",

53 "content": [{"type": "text", "text": "Summarize the repo README"}]

54 }

55 ]

56 }' >/dev/null

38 -H "accept: text/event-stream"

39 ```

5740

58 while IFS= read -r -u "$stream" event_line; do

59 [[ $event_line == data:* ]] || continue

60 event_json=${event_line#data: }

61 case $(jq -r '.type' <<<"$event_json") in

62 agent.message)

63 jq -j '.content[] | select(.type == "text") | .text' <<<"$event_json"

64 ;;

65 session.status_idle)

66 break

67 ;;

68 session.error)

69 printf '\n[Error: %s]\n' "$(jq -r '.error.message // "unknown"' <<<"$event_json")"

70 break

71 ;;

72 esac

73 done

74 exec {stream}<&-

41 ```bash CLI

42 # Open the stream before you send the first event: only later events are delivered.

43 ant beta:sessions:events stream --session-id "$SESSION_ID"

7544 ```

7645

77 <CodeGroupItem language="CLI">

78 This workflow needs more logic than a single shell command. Use the [Claude SDK](https://platform.claude.com/docs/en/cli-sdks-libraries/overview) to run it.

79 </CodeGroupItem>

80

8146 ```python Python

8247 # Open the stream first, then send the user message

8348 with client.beta.sessions.events.stream(session.id) as stream:

from line 295

3302952. [List the full event history](https://platform.claude.com/docs/en/managed-agents/events-and-streaming#list-past-events) to seed a set of seen event IDs.

3312963. Tail the live stream, skipping any events already returned by the history list.

332297

333<CodeGroup exclude="shell:CLI">

334 ```bash cURL

335 exec {stream}< <(

336 curl --fail-with-body -sS -N \

337 "https://api.anthropic.com/v1/sessions/$SESSION_ID/events/stream?beta=true" \

338 -H "x-api-key: $ANTHROPIC_API_KEY" \

339 -H "anthropic-version: 2023-06-01" \

340 -H "anthropic-beta: managed-agents-2026-04-01" \

341 -H "content-type: application/json" \

342 -H "accept: text/event-stream"

343 )

298<CodeGroup exclude="shell:cURL, shell:CLI">

299 <CodeGroupItem language="cURL">

300 This workflow needs more logic than a single shell command. Use the [Claude SDK](https://platform.claude.com/docs/en/cli-sdks-libraries/overview) to run it.

301 </CodeGroupItem>

344302

345 # Stream is open and buffering. List history before tailing live.

346 declare -A seen_event_ids

347 while IFS= read -r event_id; do

348 seen_event_ids[$event_id]=1

349 done < <(

350 curl --fail-with-body -sS \

351 "https://api.anthropic.com/v1/sessions/$SESSION_ID/events?beta=true" \

352 -H "x-api-key: $ANTHROPIC_API_KEY" \

353 -H "anthropic-version: 2023-06-01" \

354 -H "anthropic-beta: managed-agents-2026-04-01" \

355 -H "content-type: application/json" | jq -r '.data[].id'

356 )

357

358 # Tail live events, skipping anything already seen

359 while IFS= read -r -u "$stream" event_line; do

360 [[ $event_line == data:* ]] || continue

361 event_json=${event_line#data: }

362 event_id=$(jq -r '.id' <<<"$event_json")

363 [[ -n ${seen_event_ids[$event_id]+seen} ]] && continue

364 seen_event_ids[$event_id]=1

365 case $(jq -r '.type' <<<"$event_json") in

366 agent.message)

367 jq -j '.content[] | select(.type == "text") | .text' <<<"$event_json"

368 ;;

369 session.status_idle)

370 break

371 ;;

372 esac

373 done

374 exec {stream}<&-

375 ```

376

377303 <CodeGroupItem language="CLI">

378304 This workflow needs more logic than a single shell command. Use the [Claude SDK](https://platform.claude.com/docs/en/cli-sdks-libraries/overview) to run it.

379305 </CodeGroupItem>

from line 694

768694

769695The following example answers each call as it arrives:

770696

771<CodeGroup exclude="shell:CLI">

772 ```bash cURL

773 exec {stream_fd}< <(curl --fail-with-body -sS -N \

774 "https://api.anthropic.com/v1/sessions/$SESSION_ID/events/stream?beta=true" \

775 -H "x-api-key: $ANTHROPIC_API_KEY" \

776 -H "anthropic-version: 2023-06-01" \

777 -H "anthropic-beta: managed-agents-2026-04-01" \

778 -H "content-type: application/json" \

779 -H "accept: text/event-stream")

697<CodeGroup exclude="shell:cURL, shell:CLI">

698 <CodeGroupItem language="cURL">

699 This workflow needs more logic than a single shell command. Use the [Claude SDK](https://platform.claude.com/docs/en/cli-sdks-libraries/overview) to run it.

700 </CodeGroupItem>

780701

781 while IFS= read -r -u "$stream_fd" line; do

782 [[ $line == data:* ]] || continue

783 event_json="${line#data: }"

784 case $(jq -r '.type' <<<"$event_json") in

785 agent.custom_tool_use)

786 # Execute the tool and send the result back

787 result=$(call_tool "$(jq -r '.name' <<<"$event_json")" "$(jq -c '.input' <<<"$event_json")")

788 jq --arg result "$result" \

789 '{events: [{type: "user.custom_tool_result", custom_tool_use_id: .id, content: [{type: "text", text: $result}]}]}' <<<"$event_json" |

790 curl --fail-with-body -sS \

791 "https://api.anthropic.com/v1/sessions/$SESSION_ID/events?beta=true" \

792 -H "x-api-key: $ANTHROPIC_API_KEY" \

793 -H "anthropic-version: 2023-06-01" \

794 -H "anthropic-beta: managed-agents-2026-04-01" \

795 -H "content-type: application/json" \

796 -d @-

797 ;;

798 session.status_idle)

799 if [[ $(jq -r '.stop_reason.type' <<<"$event_json") == end_turn ]]; then

800 break

801 fi

802 ;;

803 esac

804 done

805 exec {stream_fd}<&-

806 ```

807

808702 <CodeGroupItem language="CLI">

809703 This workflow needs more logic than a single shell command. Use the [Claude SDK](https://platform.claude.com/docs/en/cli-sdks-libraries/overview) to run it.

810704 </CodeGroupItem>

from line 925

1031925

1032926The following example approves every pending call:

1033927

1034<CodeGroup exclude="shell:CLI">

1035 ```bash cURL

1036 exec {stream_fd}< <(curl --fail-with-body -sS -N \

1037 "https://api.anthropic.com/v1/sessions/$SESSION_ID/events/stream?beta=true" \

1038 -H "x-api-key: $ANTHROPIC_API_KEY" \

1039 -H "anthropic-version: 2023-06-01" \

1040 -H "anthropic-beta: managed-agents-2026-04-01" \

1041 -H "content-type: application/json" \

1042 -H "accept: text/event-stream")

1043

1044 while IFS= read -r -u "$stream_fd" line; do

1045 [[ $line == data:* ]] || continue

1046 event_json="${line#data: }"

1047 stop_reason=$(jq -r 'select(.type == "session.status_idle") | .stop_reason.type // empty' <<<"$event_json")

1048 case "$stop_reason" in

1049 requires_action)

1050 while IFS= read -r event_id; do

1051 # Approve the pending tool call

1052 jq -n --arg id "$event_id" \

1053 '{events: [{type: "user.tool_confirmation", tool_use_id: $id, result: "allow"}]}' |

1054 curl --fail-with-body -sS \

1055 "https://api.anthropic.com/v1/sessions/$SESSION_ID/events?beta=true" \

1056 -H "x-api-key: $ANTHROPIC_API_KEY" \

1057 -H "anthropic-version: 2023-06-01" \

1058 -H "anthropic-beta: managed-agents-2026-04-01" \

1059 -H "content-type: application/json" \

1060 -d @-

1061 done < <(jq -r '.stop_reason.event_ids[]' <<<"$event_json")

1062 ;;

1063 end_turn)

1064 break

1065 ;;

1066 esac

1067 done

1068 exec {stream_fd}<&-

1069 ```

928<CodeGroup exclude="shell:cURL, shell:CLI">

929 <CodeGroupItem language="cURL">

930 This workflow needs more logic than a single shell command. Use the [Claude SDK](https://platform.claude.com/docs/en/cli-sdks-libraries/overview) to run it.

931 </CodeGroupItem>

1070932

1071933 <CodeGroupItem language="CLI">

1072934 This workflow needs more logic than a single shell command. Use the [Claude SDK](https://platform.claude.com/docs/en/cli-sdks-libraries/overview) to run it.

managed-agents/files Changed · +37 / -25 lines

from line 18

1818

1919<CodeGroup>

2020 ```bash cURL

21 file=$(curl --fail-with-body -sS "${auth[@]}" \

22 "${base_url}/files" \

23 -F [email protected])

24 FILE_ID=$(jq -er '.id' <<<"${file}")

21 curl --fail-with-body -sS https://api.anthropic.com/v1/files \

22 -H "x-api-key: $ANTHROPIC_API_KEY" \

23 -H "anthropic-version: 2023-06-01" \

24 -H "anthropic-beta: managed-agents-2026-04-01" \

25 -F [email protected]

2526 ```

2627

2728 ```bash CLI

28 FILE_ID=$(ant files upload --file data.csv --transform id --raw-output)

29 ant files upload --file data.csv

2930 ```

3031

3132 ```python Python

from line 93

9293

9394<CodeGroup>

9495 ```bash cURL

95 jq -n \

96 --arg agent_id "${AGENT_ID}" \

97 --arg environment_id "${ENVIRONMENT_ID}" \

98 --arg file_id "${FILE_ID}" \

99 '{

100 agent: $agent_id,

101 environment_id: $environment_id,

102 resources: [

96 curl --fail-with-body -sS https://api.anthropic.com/v1/sessions \

97 -H "x-api-key: $ANTHROPIC_API_KEY" \

98 -H "anthropic-version: 2023-06-01" \

99 -H "anthropic-beta: managed-agents-2026-04-01" \

100 -H "content-type: application/json" \

101 -d '{

102 "agent": "'"$AGENT_ID"'",

103 "environment_id": "'"$ENVIRONMENT_ID"'",

104 "resources": [

103105 {

104 type: "file",

105 file_id: $file_id,

106 mount_path: "/data.csv"

106 "type": "file",

107 "file_id": "'"$FILE_ID"'",

108 "mount_path": "/data.csv"

107109 }

108110 ]

109 }' | curl --fail-with-body -sS "${auth[@]}" "${base_url}/sessions" --json @-

111 }'

110112 ```

111113

112114 ```bash CLI

from line 360

358360

359361<CodeGroup>

360362 ```bash cURL

361 jq -n --arg file_id "${FILE_ID}" '{type: "file", file_id: $file_id}' \

362 | curl --fail-with-body -sS "${auth[@]}" \

363 "${base_url}/sessions/${SESSION_ID}/resources" --json @-

363 curl --fail-with-body -sS "https://api.anthropic.com/v1/sessions/$SESSION_ID/resources" \

364 -H "x-api-key: $ANTHROPIC_API_KEY" \

365 -H "anthropic-version: 2023-06-01" \

366 -H "anthropic-beta: managed-agents-2026-04-01" \

367 -H "content-type: application/json" \

368 -d '{

369 "type": "file",

370 "file_id": "'"$FILE_ID"'"

371 }'

364372 ```

365373

366374 ```bash CLI

from line 458

450458

451459<CodeGroup>

452460 ```bash cURL

453 curl --fail-with-body -sS "${auth[@]}" \

454 "${base_url}/sessions/${SESSION_ID}/resources"

461 curl --fail-with-body -sS "https://api.anthropic.com/v1/sessions/$SESSION_ID/resources" \

462 -H "x-api-key: $ANTHROPIC_API_KEY" \

463 -H "anthropic-version: 2023-06-01" \

464 -H "anthropic-beta: managed-agents-2026-04-01"

455465

456 curl --fail-with-body -sS "${auth[@]}" -X DELETE \

457 "${base_url}/sessions/${SESSION_ID}/resources/${RESOURCE_ID}" >/dev/null

466 curl --fail-with-body -sS -X DELETE "https://api.anthropic.com/v1/sessions/$SESSION_ID/resources/$RESOURCE_ID" \

467 -H "x-api-key: $ANTHROPIC_API_KEY" \

468 -H "anthropic-version: 2023-06-01" \

469 -H "anthropic-beta: managed-agents-2026-04-01"

458470 ```

459471

460472 ```bash CLI

managed-agents/github Changed · +42 / -36 lines

from line 20

2020

2121<CodeGroup defaultLanguage="CLI">

2222 ```bash cURL

23 agent_id=$(curl -fsS https://api.anthropic.com/v1/agents \

23 curl -fsS https://api.anthropic.com/v1/agents \

2424 -H "x-api-key: $ANTHROPIC_API_KEY" \

2525 -H "anthropic-version: 2023-06-01" \

2626 -H "anthropic-beta: managed-agents-2026-04-01" \

2727 -H "content-type: application/json" \

28 --data '{

28 -d '{

2929 "name": "Code Reviewer",

3030 "model": "claude-opus-5-5",

3131 "system": "You are a code review assistant with access to GitHub.",

from line 43

4343 "mcp_server_name": "github"

4444 }

4545 ]

46 }' | jq -r '.id'

47 )

46 }'

4847 ```

4948

5049 <CodeGroupItem>

from line 242

243242

244243<CodeGroup>

245244 ```bash cURL

246 session_id=$(curl -fsS https://api.anthropic.com/v1/sessions \

245 curl -fsS https://api.anthropic.com/v1/sessions \

247246 -H "x-api-key: $ANTHROPIC_API_KEY" \

248247 -H "anthropic-version: 2023-06-01" \

249248 -H "anthropic-beta: managed-agents-2026-04-01" \

250249 -H "content-type: application/json" \

251 --data @- <<JSON | jq -r '.id'

250 -d @- <<JSON

252251 {

253252 "agent": "$agent_id",

254253 "environment_id": "$environment_id",

from line 261

262261 ]

263262 }

264263 JSON

265 )

266264 ```

267265

268266 ```bash CLI

269 SESSION_ID=$(ant beta:sessions create \

267 ant beta:sessions create \

270268 --agent "$AGENT_ID" \

271 --environment-id "$ENVIRONMENT_ID" \

272 --transform id --raw-output <<'EOF'

269 --environment-id "$ENVIRONMENT_ID" <<'EOF'

273270 resources:

274271 - type: github_repository

275272 url: https://github.com/org/repo

from line 273

276273 mount_path: /workspace/repo

277274 authorization_token: ghp_your_github_token

278275 EOF

279 )

280276 ```

281277

282278 ```python Python

from line 420

424420

425421<CodeGroup>

426422 ```bash cURL

427 resources='[

428 {

429 "type": "github_repository",

430 "url": "https://github.com/org/frontend",

431 "mount_path": "/workspace/frontend",

432 "authorization_token": "ghp_your_github_token"

433 },

434 {

435 "type": "github_repository",

436 "url": "https://github.com/org/backend",

437 "mount_path": "/workspace/backend",

438 "authorization_token": "ghp_your_github_token"

439 }

440 ]'

423 curl -fsS https://api.anthropic.com/v1/sessions \

424 -H "x-api-key: $ANTHROPIC_API_KEY" \

425 -H "anthropic-version: 2023-06-01" \

426 -H "anthropic-beta: managed-agents-2026-04-01" \

427 -H "content-type: application/json" \

428 -d @- <<JSON

429 {

430 "agent": "$agent_id",

431 "environment_id": "$environment_id",

432 "resources": [

433 {

434 "type": "github_repository",

435 "url": "https://github.com/org/frontend",

436 "mount_path": "/workspace/frontend",

437 "authorization_token": "ghp_your_github_token"

438 },

439 {

440 "type": "github_repository",

441 "url": "https://github.com/org/backend",

442 "mount_path": "/workspace/backend",

443 "authorization_token": "ghp_your_github_token"

444 }

445 ]

446 }

447 JSON

441448 ```

442449

443450 ```bash CLI

444 RESOURCES_BODY=$(cat <<'EOF'

451 ant beta:sessions create \

452 --agent "$AGENT_ID" \

453 --environment-id "$ENVIRONMENT_ID" <<'EOF'

445454 resources:

446455 - type: github_repository

447456 url: https://github.com/org/frontend

from line 461

452461 mount_path: /workspace/backend

453462 authorization_token: ghp_your_github_token

454463 EOF

455 )

456464 ```

457465

458466 ```python Python

from line 596

588596<CodeGroup>

589597 ```bash cURL

590598 # List resources on the session

591 repo_resource_id=$(curl -fsS "https://api.anthropic.com/v1/sessions/$session_id/resources" \

599 curl -fsS "https://api.anthropic.com/v1/sessions/$session_id/resources" \

592600 -H "x-api-key: $ANTHROPIC_API_KEY" \

593601 -H "anthropic-version: 2023-06-01" \

594602 -H "anthropic-beta: managed-agents-2026-04-01" \

595 -H "content-type: application/json" | jq -r '.data[0].id')

596 echo "$repo_resource_id" # "sesrsc_01ABC..."

603 -H "content-type: application/json"

597604

598605 # Rotate the authorization token

599 curl -fsS "https://api.anthropic.com/v1/sessions/$session_id/resources/$repo_resource_id" \

606 curl -fsS \

607 "https://api.anthropic.com/v1/sessions/$session_id/resources/$repo_resource_id" \

600608 # ...

601 -o /dev/null \

602 --data @- <<JSON

609 -d @- <<'JSON'

603610 {

604611 "authorization_token": "ghp_your_new_github_token"

605612 }

from line 743

736743 -H "anthropic-version: 2023-06-01" \

737744 -H "anthropic-beta: managed-agents-2026-04-01" \

738745 -H "content-type: application/json" \

739 -o /dev/null \

740 --data '{

746 -d '{

741747 "events": [

742748 {

743749 "type": "user.message",

from line 759

753759 ```

754760

755761 ```bash CLI

756 ant beta:sessions:events send --session-id "$SESSION_ID" > /dev/null <<'EOF'

762 ant beta:sessions:events send --session-id "$SESSION_ID" <<'EOF'

757763 events:

758764 - type: user.message

759765 content:

managed-agents/mcp-connector Changed · +4 / -9 lines

from line 27

2727

2828<CodeGroup defaultLanguage="CLI">

2929 ```bash cURL

30 agent_response=$(curl -sS --fail-with-body https://api.anthropic.com/v1/agents \

30 curl -sS --fail-with-body https://api.anthropic.com/v1/agents \

3131 -H "x-api-key: $ANTHROPIC_API_KEY" \

3232 -H "anthropic-version: 2023-06-01" \

3333 -H "anthropic-beta: managed-agents-2026-04-01" \

from line 47

4747 {"type": "mcp_toolset", "mcp_server_name": "github"}

4848 ]

4949 }'

50 )

51 agent_id=$(jq -r '.id' <<<"$agent_response")

5250 ```

5351

5452 <CodeGroupItem>

from line 291

293291

294292<CodeGroup>

295293 ```bash cURL

296 session_response=$(curl -sS --fail-with-body https://api.anthropic.com/v1/sessions \

294 curl -sS --fail-with-body https://api.anthropic.com/v1/sessions \

297295 -H "x-api-key: $ANTHROPIC_API_KEY" \

298296 -H "anthropic-version: 2023-06-01" \

299297 -H "anthropic-beta: managed-agents-2026-04-01" \

from line 301

303301 "environment_id": "'"$environment_id"'",

304302 "vault_ids": ["'"$vault_id"'"]

305303 }'

306 )

307 session_id=$(jq -r '.id' <<<"$session_response")

308304 ```

309305

310306 ```bash CLI

311 SESSION_ID=$(ant beta:sessions create \

307 ant beta:sessions create \

312308 --agent "$AGENT_ID" \

313309 --environment-id "$ENVIRONMENT_ID" \

314 --vault-id "$VAULT_ID" \

315 --transform id --raw-output)

310 --vault-id "$VAULT_ID"

316311 ```

317312

318313 ```python Python

managed-agents/memory Changed · +10 / -14 lines

from line 135

135135 -H "anthropic-version: 2023-06-01" \

136136 -H "anthropic-beta: agent-memory-2026-07-22" \

137137 -H "content-type: application/json" \

138 -d '{"path": "/formatting_standards.md", "content": "All reports use GAAP formatting. Dates are ISO-8601..."}' > /dev/null

138 -d '{"path": "/formatting_standards.md", "content": "All reports use GAAP formatting. Dates are ISO-8601..."}'

139139 ```

140140

141141 ```bash CLI

from line 142

142142 ant beta:memory-stores:memories create \

143143 --memory-store-id "$store_id" \

144144 --path "/formatting_standards.md" \

145 --content "All reports use GAAP formatting. Dates are ISO-8601..." \

146 > /dev/null

145 --content "All reports use GAAP formatting. Dates are ISO-8601..."

147146 ```

148147

149148 ```python Python

from line 662

663662 -H "anthropic-version: 2023-06-01" \

664663 -H "anthropic-beta: agent-memory-2026-07-22" \

665664 -H "content-type: application/json" \

666 -d '{"path": "/archive/2026_q1_formatting.md"}' > /dev/null

665 -d '{"path": "/archive/2026_q1_formatting.md"}'

667666 ```

668667

669668 ```bash CLI

from line 669

670669 ant beta:memory-stores:memories update \

671670 --memory-store-id "$store_id" \

672671 --memory-id "$mem_id" \

673 --path "/archive/2026_q1_formatting.md" \

674 > /dev/null

672 --path "/archive/2026_q1_formatting.md"

675673 ```

676674

677675 ```python Python

from line 745

747745 -H "anthropic-version: 2023-06-01" \

748746 -H "anthropic-beta: agent-memory-2026-07-22" \

749747 -H "content-type: application/json" \

750 --data '{

748 -d '{

751749 "content": "CORRECTED: Always use 2-space indentation.",

752750 "precondition": {"type": "content_sha256", "content_sha256": "'"$mem_sha"'"}

753 }' > /dev/null

751 }'

754752 ```

755753

756754 ```bash CLI

from line 756

758756 --memory-store-id "$store_id" \

759757 --memory-id "$mem_id" \

760758 --content "CORRECTED: Always use 2-space indentation." \

761 --precondition "{type: content_sha256, content_sha256: $mem_sha}" \

762 > /dev/null

759 --precondition "{type: content_sha256, content_sha256: $mem_sha}"

763760 ```

764761

765762 ```python Python

from line 845

848845 curl -s -X DELETE "https://api.anthropic.com/v1/memory_stores/$store_id/memories/$mem_id" \

849846 -H "x-api-key: $ANTHROPIC_API_KEY" \

850847 -H "anthropic-version: 2023-06-01" \

851 -H "anthropic-beta: agent-memory-2026-07-22" > /dev/null

848 -H "anthropic-beta: agent-memory-2026-07-22"

852849 ```

853850

854851 ```bash CLI

855852 ant beta:memory-stores:memories delete \

856853 --memory-store-id "$store_id" \

857 --memory-id "$mem_id" \

858 > /dev/null

854 --memory-id "$mem_id"

859855 ```

860856

861857 ```python Python

from line 1269

12731269 curl -s -X POST "https://api.anthropic.com/v1/memory_stores/$store_id/archive" \

12741270 -H "x-api-key: $ANTHROPIC_API_KEY" \

12751271 -H "anthropic-version: 2023-06-01" \

1276 -H "anthropic-beta: agent-memory-2026-07-22" > /dev/null

1272 -H "anthropic-beta: agent-memory-2026-07-22"

12771273 ```

12781274

12791275 ```bash CLI

managed-agents/migration Changed · +12 / -88 lines

from line 249

249249

250250**After** (Claude Managed Agents):

251251

252<CodeGroup>

253 ```bash cURL

254 agent=$(

255 curl --fail-with-body -sS "https://api.anthropic.com/v1/agents?beta=true" \

256 -H "x-api-key: ${ANTHROPIC_API_KEY}" \

257 -H "anthropic-version: 2023-06-01" \

258 -H "anthropic-beta: managed-agents-2026-04-01" \

259 --json '{

260 "name": "Task Runner",

261 "model": "claude-opus-5-5",

262 "tools": [{"type": "agent_toolset_20260401"}]

263 }'

264 )

265 agent_id=$(jq -r '.id' <<< "${agent}")

252<CodeGroup exclude="shell:cURL, shell:CLI">

253 <CodeGroupItem language="cURL">

254 This workflow needs more logic than a single shell command. Use the [Claude SDK](https://platform.claude.com/docs/en/cli-sdks-libraries/overview) to run it.

255 </CodeGroupItem>

266256

267 session_id=$(

268 curl --fail-with-body -sS "https://api.anthropic.com/v1/sessions?beta=true" \

269 -H "x-api-key: ${ANTHROPIC_API_KEY}" \

270 -H "anthropic-version: 2023-06-01" \

271 -H "anthropic-beta: managed-agents-2026-04-01" \

272 --json "$(jq -n --argjson a "${agent}" --arg env "${environment_id}" \

273 '{agent: {type: "agent", id: $a.id, version: $a.version}, environment_id: $env}')" \

274 | jq -r '.id'

275 )

276

277 # Open the SSE stream in the background, then send the user message.

278 stream_log=$(mktemp)

279 curl --fail-with-body -sS -N \

280 "https://api.anthropic.com/v1/sessions/${session_id}/events/stream?beta=true" \

281 -H "x-api-key: ${ANTHROPIC_API_KEY}" \

282 -H "anthropic-version: 2023-06-01" \

283 -H "anthropic-beta: managed-agents-2026-04-01" \

284 > "${stream_log}" &

285 stream_pid=$!

286

287 curl --fail-with-body -sS \

288 "https://api.anthropic.com/v1/sessions/${session_id}/events?beta=true" \

289 -H "x-api-key: ${ANTHROPIC_API_KEY}" \

290 -H "anthropic-version: 2023-06-01" \

291 -H "anthropic-beta: managed-agents-2026-04-01" \

292 --json "$(jq -n --arg text "${task}" \

293 '{events: [{type: "user.message", content: [{type: "text", text: $text}]}]}')" \

294 > /dev/null

295

296 # Wait for the session to go idle. grep exits at the first match, and

297 # reading via process substitution means the shell doesn't wait for

298 # tail (a foreground `tail -f | grep -m1` pipeline would hang: tail

299 # only dies on its next write, which never comes once the stream is idle).

300 grep -m1 '"session.status_idle"' <(tail -f -n +1 "${stream_log}") > /dev/null

301

302 kill "${stream_pid}" 2>/dev/null || true

303 ```

304

305 <CodeGroupItem>

306 ```bash CLI

307 ant apply agent.md

308

309 session_id=$(ant beta:sessions create \

310 --agent "{type: agent, id: $agent_id, version: $agent_version}" \

311 --environment-id "$environment_id" \

312 --transform id --raw-output)

313

314 # Open the stream first, then send the user message

315 exec {stream}< <(ant beta:sessions:events stream \

316 --session-id "$session_id" \

317 --transform type --raw-output)

318

319 ant beta:sessions:events send \

320 --session-id "$session_id" \

321 --event "{type: user.message, content: [{type: text, text: \"$task\"}]}" \

322 > /dev/null

323

324 # Wait for the session to go idle (grep exits at the first match)

325 grep -m1 -x 'session.status_idle' <&"$stream" > /dev/null

326 exec {stream}<&-

327 ```

328

329 <File filename="agent.md">

330 ```markdown

331 ---

332 name: Task Runner

333 model: claude-opus-5-5

334 tools:

335 - type: agent_toolset_20260401

336 ---

337 ```

338 </File>

257 <CodeGroupItem language="CLI">

258 This workflow needs more logic than a single shell command. Use the [Claude SDK](https://platform.claude.com/docs/en/cli-sdks-libraries/overview) to run it.

339259 </CodeGroupItem>

340260

341261 ```python Python

from line 1291

13711291 -H "x-api-key: $ANTHROPIC_API_KEY" \

13721292 -H "anthropic-version: 2023-06-01" \

13731293 -H "anthropic-beta: managed-agents-2026-04-01" \

1374 --json "$(jq -n --argjson version "$AGENT_VERSION" '{version: $version, model: "claude-opus-5-5"}')"

1294 -H "content-type: application/json" \

1295 -d '{

1296 "version": '"$AGENT_VERSION"',

1297 "model": "claude-opus-5-5"

1298 }'

13751299 ```

13761300

13771301 <CodeGroupItem>

managed-agents/multiagent-orchestration Changed · +82 / -86 lines

from line 111

111111

112112<CodeGroup defaultLanguage="CLI">

113113 ```bash cURL

114 lead_agent=$(curl -fsS https://api.anthropic.com/v1/agents \

114 curl -fsS https://api.anthropic.com/v1/agents \

115115 -H "x-api-key: $ANTHROPIC_API_KEY" \

116116 -H "anthropic-version: 2023-06-01" \

117117 -H "anthropic-beta: managed-agents-2026-04-01" \

from line 136

136136 }

137137 }

138138 }'

139 )

140139 ```

141140

142141 <CodeGroupItem>

143142 ```bash CLI

144 # Create the subagents, then read their IDs from the lockfile.

145 ant apply reviewer.md test-writer.md

146 REVIEWER_AGENT_ID=$(jq -er '.resources["./reviewer.md"].id' claude-lock.json)

147 TEST_WRITER_AGENT_ID=$(jq -er '.resources["./test-writer.md"].id' claude-lock.json)

148

149 # Write the agent's definition, listing each subagent by ID.

150 cat > engineering-lead.md <<EOF

151 ---

152 name: Engineering Lead

153 model: claude-opus-5-5

154 tools:

155 - type: agent_toolset_20260401

156 multiagent:

157 type: multiagent_20261001

158 subagents:

159 type: enabled

160 predefined_agents:

161 - type: agent

162 id: $REVIEWER_AGENT_ID

163 - type: agent

164 id: $TEST_WRITER_AGENT_ID

165 ---

166

167 You coordinate engineering work. Delegate code review to the reviewer agent

168 and test writing to the test agent.

169 EOF

170

171 # Create the agent.

172143 ant apply engineering-lead.md reviewer.md test-writer.md

173144 ```

174145

146 <File filename="engineering-lead.md">

147 ```markdown

148 ---

149 name: Engineering Lead

150 model: claude-opus-5-5

151 tools:

152 - type: agent_toolset_20260401

153 multiagent:

154 type: multiagent_20261001

155 subagents:

156 type: enabled

157 predefined_agents: # ant apply replaces each path with {type: agent, id, version}

158 - ./reviewer.md

159 - ./test-writer.md

160 ---

161

162 You coordinate engineering work. Delegate code review to the reviewer agent

163 and test writing to the test agent.

164 ```

165 </File>

166

175167 <File filename="reviewer.md">

176168 ```markdown

177169 ---

from line 368

376368

377369<CodeGroup>

378370 ```bash cURL

379 session=$(curl -fsSL https://api.anthropic.com/v1/sessions \

371 curl -fsSL https://api.anthropic.com/v1/sessions \

380372 -H "x-api-key: $ANTHROPIC_API_KEY" \

381373 -H "anthropic-version: 2023-06-01" \

382374 -H "anthropic-beta: managed-agents-2026-04-01" \

from line 377

385377 "agent": "'"$LEAD_AGENT_ID"'",

386378 "environment_id": "'"$ENVIRONMENT_ID"'"

387379 }'

388 )

389 SESSION_ID=$(jq -r '.id' <<< "$session")

390380 ```

391381

392382 ```bash CLI

from line 456

466456

467457<CodeGroup defaultLanguage="CLI">

468458 ```bash cURL

469 research_agent_id=$(curl --fail-with-body -sS "$BASE/v1/agents" "${H[@]}" --data '{

470 "name": "researcher",

471 "model": "claude-haiku-5-5",

472 "mcp_servers": [{"type": "url", "name": "github", "url": "https://api.githubcopilot.com/mcp/"}],

473 "tools": [{"type": "mcp_toolset", "mcp_server_name": "github"}]

474 }' | jq -er '.id'

475 )

459 # Create the researcher

460 curl --fail-with-body -sS https://api.anthropic.com/v1/agents \

461 -H "x-api-key: $ANTHROPIC_API_KEY" \

462 -H "anthropic-version: 2023-06-01" \

463 -H "anthropic-beta: managed-agents-2026-04-01" \

464 -H "content-type: application/json" \

465 -d '{

466 "name": "researcher",

467 "model": "claude-haiku-5-5",

468 "mcp_servers": [{"type": "url", "name": "github", "url": "https://api.githubcopilot.com/mcp/"}],

469 "tools": [{"type": "mcp_toolset", "mcp_server_name": "github"}]

470 }'

476471

477 lead_agent_id=$(curl --fail-with-body -sS "$BASE/v1/agents" "${H[@]}" --data '{

478 "name": "lead",

479 "model": "claude-opus-5-5",

480 "tools": [{"type": "agent_toolset_20260401"}],

481 "multiagent": {

482 "type": "multiagent_20261001",

483 "subagents": {

484 "type": "enabled",

485 "predefined_agents": [{"type": "agent", "id": "'"$research_agent_id"'"}]

472 # Create the agent that delegates to it: research_agent_id is the id from the first response

473 curl --fail-with-body -sS https://api.anthropic.com/v1/agents \

474 -H "x-api-key: $ANTHROPIC_API_KEY" \

475 -H "anthropic-version: 2023-06-01" \

476 -H "anthropic-beta: managed-agents-2026-04-01" \

477 -H "content-type: application/json" \

478 -d '{

479 "name": "lead",

480 "model": "claude-opus-5-5",

481 "tools": [{"type": "agent_toolset_20260401"}],

482 "multiagent": {

483 "type": "multiagent_20261001",

484 "subagents": {

485 "type": "enabled",

486 "predefined_agents": [{"type": "agent", "id": "'"$research_agent_id"'"}]

487 }

486488 }

487 }

488 }' | jq -er '.id'

489 )

489 }'

490490 ```

491491

492492 <CodeGroupItem>

493493 ```bash CLI

494 # Create the researcher, then read its ID from the lockfile.

495 ant apply researcher.md

496 research_agent_id=$(jq -er '.resources["./researcher.md"].id' claude-lock.json)

497

498 # Write the agent's definition, listing the researcher by ID.

499 cat > lead.md <<EOF

500 ---

501 name: lead

502 model: claude-opus-5-5

503 tools:

504 - type: agent_toolset_20260401

505 multiagent:

506 type: multiagent_20261001

507 subagents:

508 type: enabled

509 predefined_agents:

510 - type: agent

511 id: $research_agent_id

512 ---

513 EOF

514

515 # Create the agent.

516494 ant apply lead.md researcher.md

517495 ```

518496

497 <File filename="lead.md">

498 ```markdown

499 ---

500 name: lead

501 model: claude-opus-5-5

502 tools:

503 - type: agent_toolset_20260401

504 multiagent:

505 type: multiagent_20261001

506 subagents:

507 type: enabled

508 predefined_agents: # ant apply replaces each path with {type: agent, id, version}

509 - ./researcher.md

510 ---

511 ```

512 </File>

513

519514 <File filename="researcher.md">

520515 ```markdown

521516 ---

from line 777

782777

783778<CodeGroup>

784779 ```bash cURL

785 session_id=$(curl --fail-with-body -sS "$BASE/v1/sessions" "${H[@]}" --data '{

786 "agent": "'"$lead_agent_id"'",

787 "environment_id": "'"$environment_id"'",

788 "vault_ids": ["'"$vault_id"'"]

789 }' | jq -er '.id'

790 )

791 echo "$session_id"

780 curl --fail-with-body -sS https://api.anthropic.com/v1/sessions \

781 -H "x-api-key: $ANTHROPIC_API_KEY" \

782 -H "anthropic-version: 2023-06-01" \

783 -H "anthropic-beta: managed-agents-2026-04-01" \

784 -H "content-type: application/json" \

785 -d '{

786 "agent": "'"$lead_agent_id"'",

787 "environment_id": "'"$environment_id"'",

788 "vault_ids": ["'"$vault_id"'"]

789 }'

792790 ```

793791

794792 ```bash CLI

795 session_id=$(ant beta:sessions create \

793 ant beta:sessions create \

796794 --agent "$lead_agent_id" \

797795 --environment-id "$environment_id" \

798 --vault-id "$vault_id" \

799 --transform id --raw-output)

800 echo "$session_id"

796 --vault-id "$vault_id"

801797 ```

802798

803799 ```python Python

managed-agents/permission-policies Changed · +26 / -17 lines

from line 34

3434

3535<CodeGroup defaultLanguage="CLI">

3636 ```bash cURL

37 agent=$(curl -fsSL https://api.anthropic.com/v1/agents \

37 curl -fsSL https://api.anthropic.com/v1/agents \

3838 -H "x-api-key: $ANTHROPIC_API_KEY" \

3939 -H "anthropic-version: 2023-06-01" \

4040 -H "anthropic-beta: managed-agents-2026-04-01" \

from line 50

5050 }

5151 }

5252 ]

53 }')

53 }'

5454 ```

5555

5656 <CodeGroupItem>

from line 221

221221

222222<CodeGroup defaultLanguage="CLI">

223223 ```bash cURL

224 agent=$(curl -fsSL https://api.anthropic.com/v1/agents \

224 curl -fsSL https://api.anthropic.com/v1/agents \

225225 -H "x-api-key: $ANTHROPIC_API_KEY" \

226226 -H "anthropic-version: 2023-06-01" \

227227 -H "anthropic-beta: managed-agents-2026-04-01" \

from line 242

242242 }

243243 }

244244 ]

245 }')

245 }'

246246 ```

247247

248248 <CodeGroupItem>

from line 479

479479

480480<CodeGroup defaultLanguage="CLI">

481481 ```bash cURL

482 tools='[

483 {

484 "type": "agent_toolset_20260401",

485 "default_config": {

486 "permission_policy": {"type": "always_allow"}

487 },

488 "configs": [

482 curl -fsSL https://api.anthropic.com/v1/agents \

483 -H "x-api-key: $ANTHROPIC_API_KEY" \

484 -H "anthropic-version: 2023-06-01" \

485 -H "anthropic-beta: managed-agents-2026-04-01" \

486 -H "content-type: application/json" \

487 -d '{

488 "name": "Coding Assistant",

489 "model": "claude-opus-5-5",

490 "tools": [

489491 {

490 "name": "bash",

491 "permission_policy": {"type": "always_ask"}

492 "type": "agent_toolset_20260401",

493 "default_config": {

494 "permission_policy": {"type": "always_allow"}

495 },

496 "configs": [

497 {

498 "name": "bash",

499 "permission_policy": {"type": "always_ask"}

500 }

501 ]

492502 }

493503 ]

494 }

495 ]'

504 }'

496505 ```

497506

498507 <CodeGroupItem>

from line 698

689698

690699<CodeGroup defaultLanguage="CLI">

691700 ```bash cURL

692 agent=$(curl -fsSL https://api.anthropic.com/v1/agents \

701 curl -fsSL https://api.anthropic.com/v1/agents \

693702 -H "x-api-key: $ANTHROPIC_API_KEY" \

694703 -H "anthropic-version: 2023-06-01" \

695704 -H "anthropic-beta: managed-agents-2026-04-01" \

from line 727

718727 }

719728 }

720729 ]

721 }')

730 }'

722731 ```

723732

724733 <CodeGroupItem>

managed-agents/quickstart Changed · +44 / -62 lines

from line 13

1313This guide walks you through creating an agent, setting up an environment, starting a session, and streaming agent responses.

1414

1515<Tip>

16 **Prefer an interactive walkthrough?** Run `/claude-api managed-agents-onboard` in the latest version of [Claude Code](https://claude.com/product/claude-code) for a guided setup and interactive question-answering.

16 **Prefer an interactive walkthrough?** The latest version of [Claude Code](https://claude.com/product/claude-code) can guide you through the setup and answer your questions:

17

18 Let Claude Code set up your agent for you

19

20 ```text

21 /claude-api managed-agents-onboard

22 ```

1723</Tip>

1824

1925## Core concepts

from line 144

138144 <CodeGroup defaultLanguage="CLI">

139145 <CodeGroupItem>

140146 ```bash cURL

141 set -euo pipefail

142

143 agent=$(

144 curl -sS --fail-with-body https://api.anthropic.com/v1/agents \

145 -H "x-api-key: $ANTHROPIC_API_KEY" \

146 -H "anthropic-version: 2023-06-01" \

147 -H "anthropic-beta: managed-agents-2026-04-01" \

148 -H "content-type: application/json" \

149 -d '{

150 "name": "Coding Assistant",

151 "model": "claude-opus-5-5",

152 "system": "You are a helpful coding assistant. Write clean, well-documented code.",

153 "tools": [

154 {"type": "agent_toolset_20260401"}

155 ]

156 }'

157 )

158

159 AGENT_ID=$(jq -er '.id' <<<"$agent")

160 AGENT_VERSION=$(jq -er '.version' <<<"$agent")

161

162 echo "Agent ID: $AGENT_ID, version: $AGENT_VERSION"

147 curl -sS --fail-with-body https://api.anthropic.com/v1/agents \

148 -H "x-api-key: $ANTHROPIC_API_KEY" \

149 -H "anthropic-version: 2023-06-01" \

150 -H "anthropic-beta: managed-agents-2026-04-01" \

151 -H "content-type: application/json" \

152 -d '{

153 "name": "Coding Assistant",

154 "model": "claude-opus-5-5",

155 "system": "You are a helpful coding assistant. Write clean, well-documented code.",

156 "tools": [

157 {"type": "agent_toolset_20260401"}

158 ]

159 }'

163160 ```

164161

165162 Save the returned `agent.id`. You'll reference it in every session you create.

from line 374

377374 <CodeGroup defaultLanguage="CLI">

378375 <CodeGroupItem>

379376 ```bash cURL

380 environment=$(

381 curl -sS --fail-with-body https://api.anthropic.com/v1/environments \

382 -H "x-api-key: $ANTHROPIC_API_KEY" \

383 -H "anthropic-version: 2023-06-01" \

384 -H "anthropic-beta: managed-agents-2026-04-01" \

385 -H "content-type: application/json" \

386 -d '{

387 "name": "quickstart-env",

388 "config": {

389 "type": "cloud",

390 "networking": {"type": "limited", "allow_package_managers": true}

391 }

392 }'

393 )

394

395 ENVIRONMENT_ID=$(jq -er '.id' <<<"$environment")

396

397 echo "Environment ID: $ENVIRONMENT_ID"

377 curl -sS --fail-with-body https://api.anthropic.com/v1/environments \

378 -H "x-api-key: $ANTHROPIC_API_KEY" \

379 -H "anthropic-version: 2023-06-01" \

380 -H "anthropic-beta: managed-agents-2026-04-01" \

381 -H "content-type: application/json" \

382 -d '{

383 "name": "quickstart-env",

384 "config": {

385 "type": "cloud",

386 "networking": {"type": "limited", "allow_package_managers": true}

387 }

388 }'

398389 ```

399390

400391 Save the returned `environment.id` too.

from line 549

558549

559550 <CodeGroup>

560551 ```bash cURL

561 session=$(

562 curl -sS --fail-with-body https://api.anthropic.com/v1/sessions \

563 -H "x-api-key: $ANTHROPIC_API_KEY" \

564 -H "anthropic-version: 2023-06-01" \

565 -H "anthropic-beta: managed-agents-2026-04-01" \

566 -H "content-type: application/json" \

567 -d '{

568 "agent": "'"$AGENT_ID"'",

569 "environment_id": "'"$ENVIRONMENT_ID"'",

570 "title": "Quickstart session"

571 }'

572 )

573

574 SESSION_ID=$(jq -er '.id' <<<"$session")

575

576 echo "Session ID: $SESSION_ID"

552 curl -sS --fail-with-body https://api.anthropic.com/v1/sessions \

553 -H "x-api-key: $ANTHROPIC_API_KEY" \

554 -H "anthropic-version: 2023-06-01" \

555 -H "anthropic-beta: managed-agents-2026-04-01" \

556 -H "content-type: application/json" \

557 -d '{

558 "agent": "'"$AGENT_ID"'",

559 "environment_id": "'"$ENVIRONMENT_ID"'",

560 "title": "Quickstart session"

561 }'

577562 ```

578563

579564 ```bash CLI

580 SESSION_ID=$(ant beta:sessions create \

565 ant beta:sessions create \

581566 --agent "$AGENT_ID" \

582567 --environment-id "$ENVIRONMENT_ID" \

583 --title "Quickstart session" \

584 --transform id --raw-output)

585

586 echo "Session ID: $SESSION_ID"

568 --title "Quickstart session"

587569 ```

588570

589571 ```python Python

managed-agents/secure-deployment Changed · +44 / -34 lines

from line 17

1717| [Choose where the agent runs](https://platform.claude.com/docs/en/managed-agents/secure-deployment#choose-where-the-agent-runs) | Cloud or self-hosted sandbox | Cloud, unless tools must run on infrastructure you control |

1818| [Limit the network](https://platform.claude.com/docs/en/managed-agents/secure-deployment#limit-the-network) | Environment `networking.type` | `limited`, with only the hosts the agent needs |

1919| [Keep credentials in vaults](https://platform.claude.com/docs/en/managed-agents/secure-deployment#keep-credentials-in-vaults) | `injection_location` and `networking` on each environment variable credential | Request headers only, and `limited` networking with only the hosts the key is for |

20| [Keep credentials in vaults](https://platform.claude.com/docs/en/managed-agents/secure-deployment#keep-credentials-in-vaults) | How your application authenticates to the Claude API | Where you can, a Workload Identity Federation rule enabled in one workspace only, otherwise an API key scoped to one workspace |

2021| [Restrict web search and web fetch](https://platform.claude.com/docs/en/managed-agents/secure-deployment#restrict-web-search-and-web-fetch) | `allowed_domains` on each web tool | An allowlist on each tool. On `web_fetch`, list only the sites the agent needs. On `web_search`, list the sites you want results from |

2122| [Approve risky actions](https://platform.claude.com/docs/en/managed-agents/secure-deployment#approve-risky-actions) | `permission_policy` on each tool | `auto` on `bash`, `write`, `edit`, `web_fetch`, and MCP tools that only read data. `always_ask` instead on a tool if you cannot undo its changes outside the sandbox, or if relayed end-user text alone should not make it run |

2223| [Give the agent the smallest tool set](https://platform.claude.com/docs/en/managed-agents/secure-deployment#give-the-agent-the-smallest-tool-set) | `default_config.enabled` on the agent toolset | `false`, then enable the tools the agent needs |

from line 231

230231

231232The support agent needs no vault credential, because your application holds the API key for your order API. If your agent does hold a vault credential, see [Add a credential](https://platform.claude.com/docs/en/managed-agents/vaults#add-a-credential) for the request in every language.

232233

233Keep keys out of system prompts, agent definitions, and messages. Do not give the agent a Claude API key. Even when a Claude API key is in a vault, code in the sandbox can use it to call the Claude API directly. It can do anything that key allows, such as starting or deleting sessions, or using web search and web fetch. The agent's tool settings, approvals, and budget do not apply to those calls. In a `limited` environment, code can make these calls only if `allowed_hosts` lets the sandbox reach `api.anthropic.com`.

234Keep keys out of system prompts, agent definitions, and messages. Do not give the agent a Claude API key or Claude API access token. Even when one is in a vault, code in the sandbox can use it to call the Claude API directly. It can do anything that credential allows, such as starting or deleting sessions, or using web search and web fetch. The agent's tool settings, approvals, and budget do not apply to those calls. In a `limited` environment, code can make these calls only if `allowed_hosts` lets the sandbox reach `api.anthropic.com`.

234235

235Fetch tokens yourself and store them in the vault, because a token that code in the sandbox fetches with a stored secret comes back unredacted.

236Fetch third-party tokens yourself and store them in the vault. A token that code in the sandbox fetches with a stored secret comes back unredacted.

236237

237Keep vaults for workloads with different trust levels in separate [workspaces](https://platform.claude.com/docs/en/manage-claude/workspaces), because any API key with access to a workspace can reference its vaults. Use API keys scoped to one workspace.

238Keep vaults for workloads with different trust levels in separate [workspaces](https://platform.claude.com/docs/en/manage-claude/workspaces), because whoever can start sessions in a workspace can reference its vaults. Limit each workload to one workspace: where you can, a [Workload Identity Federation](https://platform.claude.com/docs/en/manage-claude/workload-identity-federation) rule enabled only in it, otherwise an API key scoped to it. Workload Identity Federation gives your application short-lived Claude API access tokens, so there is no long-lived Claude API key to leak.

238239

239240See [Authenticate with vaults](https://platform.claude.com/docs/en/managed-agents/vaults) for MCP credentials and rotation.

240241

from line 327

326327

327328<CodeGroup defaultLanguage="CLI">

328329 ```bash cURL

329 tools='[

330 {

331 "type": "agent_toolset_20260401",

332 "default_config": {

333 "enabled": false,

334 "permission_policy": {"type": "always_ask"}

335 },

336 "configs": [

337 {"name": "read", "enabled": true, "permission_policy": {"type": "always_allow"}},

338 {"name": "write", "enabled": true, "permission_policy": {"type": "auto"}},

330 curl -fsSL https://api.anthropic.com/v1/agents \

331 -H "x-api-key: $ANTHROPIC_API_KEY" \

332 -H "anthropic-version: 2023-06-01" \

333 -H "anthropic-beta: managed-agents-2026-04-01" \

334 -H "content-type: application/json" \

335 -d '{

336 "name": "Support Agent",

337 "model": "claude-opus-5-5",

338 "tools": [

339339 {

340 "name": "web_fetch",

341 "enabled": true,

342 "allowed_domains": ["help.example.com"],

343 "permission_policy": {"type": "auto"}

340 "type": "agent_toolset_20260401",

341 "default_config": {

342 "enabled": false,

343 "permission_policy": {"type": "always_ask"}

344 },

345 "configs": [

346 {"name": "read", "enabled": true, "permission_policy": {"type": "always_allow"}},

347 {"name": "write", "enabled": true, "permission_policy": {"type": "auto"}},

348 {

349 "name": "web_fetch",

350 "enabled": true,

351 "allowed_domains": ["help.example.com"],

352 "permission_policy": {"type": "auto"}

353 }

354 ]

355 },

356 {

357 "type": "custom",

358 "name": "lookup_order",

359 "description": "Look up one order by its ID. Returns the status, the items, and the delivery date.",

360 "input_schema": {

361 "type": "object",

362 "properties": {

363 "order_id": {"type": "string", "description": "The order ID from the ticket"}

364 },

365 "required": ["order_id"]

366 }

344367 }

345368 ]

346 },

347 {

348 "type": "custom",

349 "name": "lookup_order",

350 "description": "Look up one order by its ID. Returns the status, the items, and the delivery date.",

351 "input_schema": {

352 "type": "object",

353 "properties": {

354 "order_id": {"type": "string", "description": "The order ID from the ticket"}

355 },

356 "required": ["order_id"]

357 }

358 }

359 ]'

369 }'

360370 ```

361371

362372 <CodeGroupItem>

from line 845

835845

836846You cannot add a budget to a session created without one. To change or remove a cap, see [Resume a session at its budget](https://platform.claude.com/docs/en/managed-agents/budgets#resume-a-session-at-its-budget). After you remove a session's cap, you cannot set a new one.

837847

838A budget caps spending, but it does not limit what the agent does before the cap. To keep workloads with different trust levels apart, use separate [workspaces](https://platform.claude.com/docs/en/manage-claude/workspaces). Give each workload an API key scoped to one workspace, because a key that can reach several workspaces can act in any of them.

848A budget caps spending, but it does not limit what the agent does before the cap. To keep workloads with different trust levels apart, use separate [workspaces](https://platform.claude.com/docs/en/manage-claude/workspaces). Limit each workload to one workspace: where you can, a [Workload Identity Federation](https://platform.claude.com/docs/en/manage-claude/workload-identity-federation) rule enabled only in it, otherwise an API key scoped to it. Access to several workspaces lets the workload act in any of them.

839849

840850See [Session budgets](https://platform.claude.com/docs/en/managed-agents/budgets), [Session operations](https://platform.claude.com/docs/en/managed-agents/session-operations#archiving-a-session), and [Scheduled deployments](https://platform.claude.com/docs/en/managed-agents/scheduled-deployments#managing-deployment-lifecycle).

841851

managed-agents/session-operations Changed · +6 / -31 lines

from line 278

278278

279279<CodeGroup>

280280 ```bash cURL

281 first_page=$(curl -sS --fail-with-body \

281 curl -sS --fail-with-body \

282282 "https://api.anthropic.com/v1/sessions?agent_id=$AGENT_ID&limit=1" \

283283 -H "x-api-key: $ANTHROPIC_API_KEY" \

284284 -H "anthropic-version: 2023-06-01" \

285 -H "anthropic-beta: managed-agents-2026-04-01")

286 jq '{prev_page, next_page}' <<< "$first_page" # prev_page is null on the first page

287

288 next_cursor=$(jq -r '.next_page' <<< "$first_page")

289 second_page=$(curl -sS --fail-with-body \

290 "https://api.anthropic.com/v1/sessions?agent_id=$AGENT_ID&limit=1&page=$next_cursor" \

291 -H "x-api-key: $ANTHROPIC_API_KEY" \

292 -H "anthropic-version: 2023-06-01" \

293 -H "anthropic-beta: managed-agents-2026-04-01")

294

295 prev_cursor=$(jq -r '.prev_page' <<< "$second_page")

296 curl -sS --fail-with-body \

297 "https://api.anthropic.com/v1/sessions?agent_id=$AGENT_ID&limit=1&page=$prev_cursor" \

298 -H "x-api-key: $ANTHROPIC_API_KEY" \

299 -H "anthropic-version: 2023-06-01" \

300 -H "anthropic-beta: managed-agents-2026-04-01" \

301 | jq '{prev_page, next_page}'

285 -H "anthropic-beta: managed-agents-2026-04-01"

286 # Pass next_page back as the page query parameter to fetch the next page,

287 # or prev_page to go back.

302288 ```

303289

304290 ```bash CLI

305291 # --format raw returns one page envelope with its prev_page and next_page

306292 # cursors; the default output auto-paginates and emits only the sessions.

307 cursors=$(ant beta:sessions list \

308 --agent-id "$AGENT_ID" \

309 --limit 1 \

310 --format raw \

311 --transform '{prev_page,next_page}')

312 printf '%s\n' "$cursors"

313

314 # Pass the next_page cursor back as --page to fetch the next page.

315 NEXT_PAGE=$(jq -r '.next_page' <<< "$cursors")

316293 ant beta:sessions list \

317294 --agent-id "$AGENT_ID" \

318295 --limit 1 \

319 --page "$NEXT_PAGE" \

320 --format raw \

321 --transform '{prev_page,next_page}'

322 # Pass that response's prev_page as --page to go back the same way.

296 --format raw

297 # Pass next_page back as --page to fetch the next page, or prev_page to go back.

323298 ```

324299

325300 ```python Python

managed-agents/session-threads Changed · +8 / -30 lines

from line 117

117117 -H "anthropic-version: 2023-06-01" \

118118 -H "anthropic-beta: managed-agents-2026-04-01" \

119119 -H "content-type: application/json" \

120 -d "{\"events\": [{\"type\": \"user.interrupt\", \"session_thread_id\": \"$THREAD_ID\"}]}"

120 -d '{"events": [{"type": "user.interrupt", "session_thread_id": "'"$THREAD_ID"'"}]}'

121121 ```

122122

123123 ```bash CLI

from line 271

271271 -H "anthropic-version: 2023-06-01" \

272272 -H "anthropic-beta: managed-agents-2026-04-01" \

273273 -H "content-type: application/json" \

274 -d "{\"events\": [{\"type\": \"user.interrupt\", \"session_thread_id\": \"$THREAD_ID\"}]}"

274 -d '{"events": [{"type": "user.interrupt", "session_thread_id": "'"$THREAD_ID"'"}]}'

275275

276276 curl -fsS -X POST "https://api.anthropic.com/v1/sessions/$SESSION_ID/threads/$THREAD_ID/archive" \

277277 -H "x-api-key: $ANTHROPIC_API_KEY" \

from line 421

421421 curl -fsSN "https://api.anthropic.com/v1/sessions/$SESSION_ID/threads/$THREAD_ID/stream?beta=true" \

422422 -H "x-api-key: $ANTHROPIC_API_KEY" \

423423 -H "anthropic-version: 2023-06-01" \

424 -H "anthropic-beta: managed-agents-2026-04-01" |

425 while IFS= read -r line; do

426 [[ $line == data:* ]] || continue

427 json=${line#data: }

428 case $(jq -r '.type' <<<"$json") in

429 agent.message)

430 printf '%s' "$(jq -j '.content[] | select(.type == "text") | .text' <<<"$json")"

431 ;;

432 session.thread_status_idle)

433 break

434 ;;

435 esac

436 done

424 -H "anthropic-beta: managed-agents-2026-04-01"

437425 ```

438426

439427 ```bash CLI

from line 575

587575 curl -fsS "https://api.anthropic.com/v1/sessions/$SESSION_ID/threads/$THREAD_ID/events" \

588576 -H "x-api-key: $ANTHROPIC_API_KEY" \

589577 -H "anthropic-version: 2023-06-01" \

590 -H "anthropic-beta: managed-agents-2026-04-01" \

591 | jq -r '.data[] | "[\(.type)] \(.processed_at)"'

578 -H "anthropic-beta: managed-agents-2026-04-01"

592579 ```

593580

594581 ```bash CLI

from line 682

695682

696683The following example goes inside the event loop of the [tool confirmation handler](https://platform.claude.com/docs/en/managed-agents/events-and-streaming#tool-confirmation). For each ID in `stop_reason.event_ids`, it sends a `user.tool_confirmation` that allows the call. The same pattern applies to `user.custom_tool_result`, which you can also send as soon as its `agent.custom_tool_use` event arrives.

697684

698<CodeGroup exclude="shell:CLI">

699 ```bash cURL

700 while IFS= read -r event_id; do

701 jq -n --arg id "$event_id" \

702 '{events: [{type: "user.tool_confirmation", tool_use_id: $id, result: "allow"}]}' |

703 curl -fsS "https://api.anthropic.com/v1/sessions/$SESSION_ID/events?beta=true" \

704 -H "x-api-key: $ANTHROPIC_API_KEY" \

705 -H "anthropic-version: 2023-06-01" \

706 -H "anthropic-beta: managed-agents-2026-04-01" \

707 -H "content-type: application/json" \

708 -d @-

709 done < <(jq -r '.stop_reason.event_ids[]' <<<"$data")

710 ```

685<CodeGroup exclude="shell:cURL, shell:CLI">

686 <CodeGroupItem language="cURL">

687 This workflow needs more logic than a single shell command. Use the [Claude SDK](https://platform.claude.com/docs/en/cli-sdks-libraries/overview) to run it.

688 </CodeGroupItem>

711689

712690 <CodeGroupItem language="CLI">

713691 This workflow needs more logic than a single shell command. Use the [Claude SDK](https://platform.claude.com/docs/en/cli-sdks-libraries/overview) to run it.

managed-agents/sessions Changed · +9 / -32 lines

from line 193

193193

194194<CodeGroup>

195195 ```bash cURL

196 seeded_session=$(curl -fsSL https://api.anthropic.com/v1/sessions \

196 curl -fsSL https://api.anthropic.com/v1/sessions \

197197 -H "x-api-key: $ANTHROPIC_API_KEY" \

198198 -H "anthropic-version: 2023-06-01" \

199199 -H "anthropic-beta: managed-agents-2026-04-01" \

from line 208

208208 }

209209 ]

210210 }'

211 )

212 SEEDED_SESSION_ID=$(jq -r '.id' <<< "$seeded_session")

213

214 # initial_events aren't echoed on the create response; list the session's

215 # events to see the seeded message.

216 seeded_events=$(curl -fsSL \

217 "https://api.anthropic.com/v1/sessions/$SEEDED_SESSION_ID/events" \

218 -H "x-api-key: $ANTHROPIC_API_KEY" \

219 -H "anthropic-version: 2023-06-01" \

220 -H "anthropic-beta: managed-agents-2026-04-01")

221 echo "Seeded event: $(jq -r \

222 '.data[] | select(.type == "user.message") | .content[0].text' <<< "$seeded_events")"

223211 ```

224212

225213 ```bash CLI

226 SEEDED_SESSION_ID=$(ant beta:sessions create \

227 --transform id --raw-output <<YAML

214 ant beta:sessions create <<YAML

228215 agent: $AGENT_ID

229216 environment_id: $ENVIRONMENT_ID

230217 initial_events:

from line 220

233220 - type: text

234221 text: List the files in the working directory.

235222 YAML

236 )

237

238 # initial_events aren't echoed on the create response; list the session's

239 # events to see the seeded message.

240 echo "Seeded event: $(ant beta:sessions:events list \

241 --session-id "$SEEDED_SESSION_ID" \

242 --format raw \

243 --transform 'data.#(type=="user.message").content.0.text' --raw-output)"

244223 ```

245224

246225 ```python Python

from line 414

435414 ```

436415</CodeGroup>

437416

417`initial_events` (java, php: `initialEvents`; csharp, go: `InitialEvents`) are not echoed on the create response. To see the seeded message, list the session's events.

418

438419No other event type is accepted. Events that respond to an agent turn (`user.tool_confirmation`, `user.tool_result`, and `user.custom_tool_result`) aren't accepted because no agent turn exists yet, and `user.interrupt` isn't accepted because there is no turn to stop. Unlike `initial_events` (java, php: `initialEvents`; csharp, go: `InitialEvents`) on a scheduled deployment, a session's `initial_events` (java, php: `initialEvents`; csharp, go: `InitialEvents`) don't accept `system.message`.

439420

440421Each event in `initial_events` (java, php: `initialEvents`; csharp, go: `InitialEvents`) is validated and persisted before the create response returns, in list order, with a server-assigned ID, exactly as if you had posted it to the [send events](https://platform.claude.com/docs/en/managed-agents/events-and-streaming#send-events) endpoint immediately after creation. Per-event content rules are also the same as on that endpoint. An empty list is equivalent to omitting the field. Validation is all-or-nothing: if any event fails validation, the whole request is rejected and no session is created.

from line 616

635616

636617Because a `model` (csharp, go: `Model`) override replaces the agent's `model` (csharp, go: `Model`) object in full, it also sets or clears the model's [inference geo](https://platform.claude.com/docs/en/manage-claude/data-residency) pin for the session: an override that includes `inference_geo` (java, php: `inferenceGeo`; csharp, go: `InferenceGeo`) pins the geography that serves the session's model requests, and one that omits it clears the agent's pin so the session follows the workspace's `default_inference_geo`. The overridden value is validated against the workspace's `allowed_inference_geos` when the session is created.

637618

638The following example starts a session from an agent whose model has no geo pin, pins the session's model requests to US inference by including `inference_geo` (java, php: `inferenceGeo`; csharp, go: `InferenceGeo`) in the `model` (csharp, go: `Model`) override, and prints the value echoed in the response's `agent.model` (csharp, go: `Agent.Model`):

619The following example starts a session from an agent whose model has no geo pin, and pins the session's model requests to US inference by including `inference_geo` (java, php: `inferenceGeo`; csharp, go: `InferenceGeo`) in the `model` (csharp, go: `Model`) override. The response echoes the value in `agent.model` (csharp, go: `Agent.Model`):

639620

640621<CodeGroup>

641622 ```bash cURL

642 # Replaces the agent's `model` in full: restate `id`, add `inference_geo` to pin.

643 session=$(curl -fsSL https://api.anthropic.com/v1/sessions \

623 # Replaces the whole model object of the agent: restate id, add inference_geo to pin.

624 curl -fsSL https://api.anthropic.com/v1/sessions \

644625 -H "x-api-key: $ANTHROPIC_API_KEY" \

645626 -H "anthropic-version: 2023-06-01" \

646627 -H "anthropic-beta: managed-agents-2026-04-01" \

from line 634

653634 },

654635 "environment_id": "'"$ENVIRONMENT_ID"'"

655636 }'

656 )

657 echo "Inference geo: $(jq -r '.agent.model.inference_geo' <<< "$session")"

658637 ```

659638

660639 ```bash CLI

661 # Replaces the agent's `model` in full: restate `id`, add `inference_geo` to pin.

662 session=$(ant beta:sessions create <<YAML

640 # Replaces the whole model object of the agent: restate id, add inference_geo to pin.

641 ant beta:sessions create <<YAML

663642 agent:

664643 type: agent_with_overrides

665644 id: $AGENT_ID

from line 647

668647 inference_geo: us

669648 environment_id: $ENVIRONMENT_ID

670649 YAML

671 )

672 echo "Inference geo: $(jq -r '.agent.model.inference_geo' <<< "$session")"

673650 ```

674651

675652 ```python Python

managed-agents/skills Changed · +5 / -9 lines

from line 218

218218

219219<CodeGroup defaultLanguage="CLI">

220220 ```bash cURL

221 agent=$(curl -sS https://api.anthropic.com/v1/agents \

221 curl -sS https://api.anthropic.com/v1/agents \

222222 -H "x-api-key: $ANTHROPIC_API_KEY" \

223223 -H "anthropic-version: 2023-06-01" \

224224 -H "anthropic-beta: managed-agents-2026-04-01" \

from line 231

231231 {"type": "custom", "skill_id": "skill_01AbCdEfGhIjKlMnOpQrStUv", "version": "latest"}

232232 ]

233233 }'

234 )

235234 ```

236235

237236 <CodeGroupItem>

from line 430

431430

432431<CodeGroup>

433432 ```bash cURL

434 session_id=$(curl -fsS https://api.anthropic.com/v1/sessions \

433 curl -fsS https://api.anthropic.com/v1/sessions \

435434 -H "x-api-key: $ANTHROPIC_API_KEY" \

436435 -H "anthropic-version: 2023-06-01" \

437436 -H "anthropic-beta: managed-agents-2026-04-01" \

438437 -H "content-type: application/json" \

439 --data @- <<JSON | jq -r '.id'

438 -d @- <<JSON

440439 {

441440 "agent": "$agent_id",

442441 "environment_id": "$environment_id",

from line 449

450449 ]

451450 }

452451 JSON

453 )

454452 ```

455453

456454 ```bash CLI

457 SESSION_ID=$(ant beta:sessions create \

455 ant beta:sessions create \

458456 --agent "$AGENT_ID" \

459 --environment-id "$ENVIRONMENT_ID" \

460 --transform id --raw-output <<'EOF'

457 --environment-id "$ENVIRONMENT_ID" <<'EOF'

461458 resources:

462459 - type: github_repository

463460 url: https://github.com/org/repo

from line 461

464461 mount_path: /workspace/repo

465462 authorization_token: ghp_your_github_token

466463 EOF

467 )

468464 ```

469465

470466 ```python Python

managed-agents/tools Changed · +2 / -4 lines

from line 41

4141

4242<CodeGroup defaultLanguage="CLI">

4343 ```bash cURL

44 agent=$(curl -fsSL https://api.anthropic.com/v1/agents \

44 curl -fsSL https://api.anthropic.com/v1/agents \

4545 -H "x-api-key: $ANTHROPIC_API_KEY" \

4646 -H "anthropic-version: 2023-06-01" \

4747 -H "anthropic-beta: managed-agents-2026-04-01" \

from line 58

5858 }

5959 ]

6060 }'

61 )

6261 ```

6362

6463 <CodeGroupItem>

from line 253

254253

255254<CodeGroup defaultLanguage="CLI">

256255 ```bash cURL

257 agent=$(curl -fsSL https://api.anthropic.com/v1/agents \

256 curl -fsSL https://api.anthropic.com/v1/agents \

258257 -H "x-api-key: $ANTHROPIC_API_KEY" \

259258 -H "anthropic-version: 2023-06-01" \

260259 -H "anthropic-beta: managed-agents-2026-04-01" \

from line 279

280279 }

281280 ]

282281 }'

283 )

284282 ```

285283

286284 <CodeGroupItem>

managed-agents/tools-web-restrictions Changed · +2 / -4 lines

from line 23

2323

2424## Set domain lists on an agent

2525

26The following example creates an agent that limits `web_search` to two sites and blocks one host for `web_fetch`. It also sets `user_location` (java, php: `userLocation`; csharp, go: `UserLocation`) and `max_content_tokens` (java, php: `maxContentTokens`; csharp, go: `MaxContentTokens`), which [Settings](https://platform.claude.com/docs/en/managed-agents/tools-web-restrictions#settings) describes. The example then prints the `configs` (csharp, go: `Configs`) array from the response.

26The following example creates an agent that limits `web_search` to two sites and blocks one host for `web_fetch`. It also sets `user_location` (java, php: `userLocation`; csharp, go: `UserLocation`) and `max_content_tokens` (java, php: `maxContentTokens`; csharp, go: `MaxContentTokens`), which [Settings](https://platform.claude.com/docs/en/managed-agents/tools-web-restrictions#settings) describes. The response echoes the `configs` (csharp, go: `Configs`) array.

2727

2828<CodeGroup defaultLanguage="CLI">

2929 ```bash cURL

30 agent=$(curl -fsSL https://api.anthropic.com/v1/agents \

30 curl -fsSL https://api.anthropic.com/v1/agents \

3131 -H "x-api-key: $ANTHROPIC_API_KEY" \

3232 -H "anthropic-version: 2023-06-01" \

3333 -H "anthropic-beta: managed-agents-2026-04-01" \

from line 59

5959 }

6060 ]

6161 }'

62 )

63 jq '.tools[0].configs' <<< "$agent"

6462 ```

6563

6664 <CodeGroupItem>

models/fable-5-1/migration-guide Changed · +3 / -7 lines

from line 9

99</Note>

1010

1111<Tip>

12 **Automate your migration with the Claude API skill.** In Claude Code, run `/claude-api migrate` to invoke the bundled [Claude API skill](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/claude-api-skill#migrating-to-a-newer-claude-model). It works for any current Claude model as the target:

12 **Automate your migration with the [Claude API skill](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/claude-api-skill#migrating-to-a-newer-claude-model).** It comes bundled with Claude Code and works for any current Claude model as the target:

1313

1414 Let Claude Code migrate your code for you

1515

from line 962

962962

963963 ```bash CLI

964964 ant beta:messages create \

965 --beta thinking-binding-controls-2026-08-01 \

966 --transform '{content.#(type=="text")#.text,input_transformations}' \

967 --format yaml <<'YAML'

965 --beta thinking-binding-controls-2026-08-01 <<'YAML'

968966 model: claude-fable-5-1

969967 max_tokens: 16000

970968 thinking:

from line 1252

12541252

12551253 ```bash CLI

12561254 ant beta:messages create \

1257 --beta mid-conversation-output-config-2026-07-01 \

1258 --transform 'content.#(type=="text").text' \

1259 --raw-output <<'YAML'

1255 --beta mid-conversation-output-config-2026-07-01 <<'YAML'

12601256 model: claude-fable-5-1

12611257 max_tokens: 4096

12621258 output_config:

test-and-evaluate/strengthen-guardrails/handle-streaming-refusals Changed · +8 / -32 lines

from line 56

5656

5757Here's how to detect and handle streaming refusals in your application:

5858

59<CodeGroup>

60 ```bash cURL

61 response=$(curl -N https://api.anthropic.com/v1/messages \

62 -H "anthropic-version: 2023-06-01" \

63 -H "content-type: application/json" \

64 -H "x-api-key: $ANTHROPIC_API_KEY" \

65 -d '{

66 "model": "claude-opus-5-5",

67 "messages": [{"role": "user", "content": "Hello"}],

68 "max_tokens": 1024,

69 "stream": true

70 }')

59<CodeGroup exclude="shell:cURL, shell:CLI">

60 <CodeGroupItem language="cURL">

61 Detecting a refusal in the stream and resetting the conversation needs more logic than a single shell command. Use the [Claude SDK](https://platform.claude.com/docs/en/cli-sdks-libraries/overview) to run it.

62 </CodeGroupItem>

7163

72 if echo "$response" | jq -R -e 'select(startswith("data: "))

73 | sub("^data: "; "") | fromjson

74 | select(.delta.stop_reason == "refusal")' >/dev/null; then

75 echo "Response refused - resetting conversation context"

76 # Reset your conversation state here

77 fi

78 ```

79

80 ```bash CLI

81 response=$(ant messages create --stream --format jsonl \

82 --model claude-opus-5-5 \

83 --max-tokens 1024 \

84 --message '{role: user, content: Hello}')

85

86 if echo "$response" | jq -e 'select(.delta.stop_reason == "refusal")' >/dev/null; then

87 echo "Response refused - resetting conversation context"

88 # Reset your conversation state here

89 fi

90 ```

64 <CodeGroupItem language="CLI">

65 Detecting a refusal in the stream and resetting the conversation needs more logic than a single shell command. Use the [Claude SDK](https://platform.claude.com/docs/en/cli-sdks-libraries/overview) to run it.

66 </CodeGroupItem>

9167

9268 ```python Python

9369 client = anthropic.Anthropic()

agents-and-tools/agent-skills/claude-api-skill Changed · +1 / -1 lines

from line 110

110110

111111## Migrating to a newer Claude model

112112

113The Claude API skill can perform Claude model migrations across a code base. Invoke it directly with `/claude-api migrate`:

113The Claude API skill can perform Claude model migrations across a code base. Invoke it directly with the `migrate` subcommand:

114114

115115Let Claude Code migrate your code for you

116116

agents-and-tools/tool-use/strict-tool-use Changed · +1 / -1 lines

from line 63

6363 ```

6464

6565 ```bash CLI

66 ant messages create --transform content <<'YAML'

66 ant messages create <<'YAML'

6767 model: claude-opus-5-5

6868 max_tokens: 1024

6969 messages:

One read of Claude Developer Platformapi-20261019T193710Z

What this read moved

manage-claude/workspaces Changed · +6 / -6 lines

managed-agents/agent-setup Changed · +13 / -28 lines

managed-agents/define-outcomes Changed · +16 / -28 lines

managed-agents/dreams Changed · +6 / -16 lines

managed-agents/event-deltas Changed · +16 / -139 lines

managed-agents/events-and-streaming Changed · +23 / -161 lines

managed-agents/files Changed · +37 / -25 lines

managed-agents/github Changed · +42 / -36 lines

managed-agents/mcp-connector Changed · +4 / -9 lines

managed-agents/memory Changed · +10 / -14 lines

managed-agents/migration Changed · +12 / -88 lines

managed-agents/multiagent-orchestration Changed · +82 / -86 lines

managed-agents/permission-policies Changed · +26 / -17 lines

managed-agents/quickstart Changed · +44 / -62 lines

managed-agents/secure-deployment Changed · +44 / -34 lines

managed-agents/session-operations Changed · +6 / -31 lines

managed-agents/session-threads Changed · +8 / -30 lines

managed-agents/sessions Changed · +9 / -32 lines

managed-agents/skills Changed · +5 / -9 lines

managed-agents/tools Changed · +2 / -4 lines

managed-agents/tools-web-restrictions Changed · +2 / -4 lines

models/fable-5-1/migration-guide Changed · +3 / -7 lines

test-and-evaluate/strengthen-guardrails/handle-streaming-refusals Changed · +8 / -32 lines

agents-and-tools/agent-skills/claude-api-skill Changed · +1 / -1 lines

agents-and-tools/tool-use/strict-tool-use Changed · +1 / -1 lines