One read of Claude Developer Platformapi-20261112T203713Z
139 pages moved out of 916 read.
Pages moved
139
significant first
Pages read
916
in this capture
Captured
20:37 UTC
Corpus hash
59cd06ab8c5c
corpus-hash
What this read moved
101-125 of 139, page 5 of 6This capture is too large to show at once. Changes 101-125 of 139 are below, significant first; the rest are on the following screens.
api/compliance/organizations/users/list Changed · +4 / -4 lines
from line 29
2929
3030## Headers
3131
32- `"anthropic-version": optional string`
32- `"anthropic-version": string`
3333
34 The version of the Claude API you want to use.
34 The version of the Claude API to use. Send an available version on every request. Some other Compliance API endpoints return a 400 error for a request that omits this header, or sends a value that is not an available version. This endpoint treats such a request as version `2023-06-01`.
3535
36 Read more about versioning and our version history [here](https://platform.claude.com/docs/en/api/versioning?sdk_languages=http).
36 See [API versions](https://platform.claude.com/docs/en/api/versioning?sdk_languages=http) for the available versions.
3737
3838- `"x-api-key": optional string`
3939
from line 99
9999
100100```bash
101101curl https://api.anthropic.com/v1/compliance/organizations/$ORG_UUID/users \
102 -H 'anthropic-version: 2023-06-01' \
102 -H 'anthropic-version: 2026-10-21' \
103103 -H "Authorization: Bearer $ANTHROPIC_COMPLIANCE_API_KEY"
104104```
105105
api/organization Changed · +31 / -0 lines
This page is larger than the 256 KiB this site keeps, so one side of the diff below stops where the stored text does.
from line 9071
90719071
90729072 Number of users with Claude Design activity in the 7-day rolling window. Omitted from the response while the per-product breakdown is not enabled for this organization.
90739073
9074 - `claude_tag_daily_active_user_count: optional number or null`
9075
9076 Number of Slack users active in Claude Tag on the requested day. Counts distinct Slack users, including users who have not linked a Claude account, so it can exceed `daily_active_user_count` and `assigned_seat_count`. Null on a day with no measured value, when Claude Tag data cannot be read for the request, and when the response is scoped to an RBAC group, because an unlinked user belongs to no group. Omitted from the response on deployments that do not offer Claude Tag reporting.
9077
9078 - `claude_tag_monthly_active_user_count: optional number or null`
9079
9080 Number of Slack users active in Claude Tag in the 28-day rolling window. Counts distinct Slack users, including users who have not linked a Claude account, so it can exceed `daily_active_user_count` and `assigned_seat_count`. Null on a day with no measured value, when Claude Tag data cannot be read for the request, and when the response is scoped to an RBAC group, because an unlinked user belongs to no group. Omitted from the response on deployments that do not offer Claude Tag reporting.
9081
9082 - `claude_tag_weekly_active_user_count: optional number or null`
9083
9084 Number of Slack users active in Claude Tag in the 7-day rolling window. Counts distinct Slack users, including users who have not linked a Claude account, so it can exceed `daily_active_user_count` and `assigned_seat_count`. Null on a day with no measured value, when Claude Tag data cannot be read for the request, and when the response is scoped to an RBAC group, because an unlinked user belongs to no group. Omitted from the response on deployments that do not offer Claude Tag reporting.
9085
90749086 - `office_agent_daily_active_user_count: optional number or null`
90759087
90769088 Number of users with Claude in Office activity on the requested day. Omitted from the response while the per-product breakdown is not enabled for this organization.
from line 9154
91429154 "claude_design_daily_active_user_count": 0,
91439155 "claude_design_monthly_active_user_count": 0,
91449156 "claude_design_weekly_active_user_count": 0,
9157 "claude_tag_daily_active_user_count": 0,
9158 "claude_tag_monthly_active_user_count": 0,
9159 "claude_tag_weekly_active_user_count": 0,
91459160 "office_agent_daily_active_user_count": 0,
91469161 "office_agent_monthly_active_user_count": 0,
91479162 "office_agent_weekly_active_user_count": 0,
from line 9264
92499264
92509265 - `distinct_connectors_used_count: number or null`
92519266
9252 Distinct claude.ai connectors this user used. Excludes calls whose connector could not be identified and all calls from organizations with zero data retention. Approximate (HLL, typical error <2%) in date-range mode. Null on aggregated rows where a distinct count cannot be computed.
9253
9254 - `distinct_conversation_count: number or null`
9255
9256 Number of distinct conversations the user participated in. Approximate (HLL, typical error <2%) in date-range mode. Null on aggregated rows where a distinct count cannot be computed.
9257
9258 - `distinct_files_uploaded_count: number or null`
9259
9260 Number of distinct files uploaded. Approximate (HLL, typical error <2%) in date-range mode. Null on aggregated rows where a distinct count cannot be computed.
9261
9262 - `distinct_projects_created_count: number`
9263
9264 Number of distinct projects created. Exact in date-range mode: a creation belongs to exactly one day, so the per-day counts never overlap and their sum over the window is the exact count of distinct creations in it.
9265
9266 - `distinct_projects_used_count: number or null`
9267
9268 Number of distinct projects used. Approximate (HLL, typical error <2%) in date-range mode. Null on aggregated rows where a distinct count cannot be computed.
9269
9270 - `distinct_shared_artifacts_viewed_count: number or null`
9271
9272 Number of distinct shared artifacts the user viewed. Approximate (HLL, typical error <2%) in date-range mode. Null on aggregated rows where a distinct count cannot be computed.
9273
9274 - `distinct_skills_used_count: number or null`
9275
9276 Number of distinct skills used. Approximate (HLL, typical error <2%) in date-range mode. Null on aggregated rows where a distinct count cannot be computed.
9277
9278 - `message_count: number`
9279
9280 Number of messages sent
9281
9282 - `shared_conversations_viewed_count: number`
9283
9284 Number of times the user opened a shared conversation in a project
9285
9286 - `thinking_mess
9267 Distinct claude.ai connectors this user used. Excludes calls whose connect
api/organization/analytics Changed · +69 / -0 lines
### Analytics Claude Tag Metrics
from line 453
453453
454454 Accepted/rejected counts for a single Claude Code tool type.
455455
456### Analytics Claude Tag Metrics
457
458- `AnalyticsClaudeTagMetrics object`
459
460 Claude Tag activity metrics for a single linked user on a given day.
461
462 - `active_day_count: number or null`
463
464 1 on a day the user was active in Claude Tag in Slack, otherwise 0. Summed over the window in date-range mode, so it is the number of active days; on grouped rows, the total of each member's active days. Null when Claude Tag data cannot be read for the request. Otherwise, 0 on a row filtered by project, and null on any other row when no covered day was measured.
465
466 - `active_message_count: number or null`
467
468 Number of the user's Slack messages that made them active: @-mentions, direct messages, group direct message asks, and thread posts Claude answered. Other messages are not counted. Null when Claude Tag data cannot be read for the request. Otherwise, 0 on a row filtered by project, and null on any other row when no covered day was measured.
469
456470### Analytics Connector Activity
457471
458472- `AnalyticsConnectorActivity object`
from line 1269
12551269
12561270 Number of users with Claude Design activity in the 7-day rolling window. Omitted from the response while the per-product breakdown is not enabled for this organization.
12571271
1272 - `claude_tag_daily_active_user_count: optional number or null`
1273
1274 Number of Slack users active in Claude Tag on the requested day. Counts distinct Slack users, including users who have not linked a Claude account, so it can exceed `daily_active_user_count` and `assigned_seat_count`. Null on a day with no measured value, when Claude Tag data cannot be read for the request, and when the response is scoped to an RBAC group, because an unlinked user belongs to no group. Omitted from the response on deployments that do not offer Claude Tag reporting.
1275
1276 - `claude_tag_monthly_active_user_count: optional number or null`
1277
1278 Number of Slack users active in Claude Tag in the 28-day rolling window. Counts distinct Slack users, including users who have not linked a Claude account, so it can exceed `daily_active_user_count` and `assigned_seat_count`. Null on a day with no measured value, when Claude Tag data cannot be read for the request, and when the response is scoped to an RBAC group, because an unlinked user belongs to no group. Omitted from the response on deployments that do not offer Claude Tag reporting.
1279
1280 - `claude_tag_weekly_active_user_count: optional number or null`
1281
1282 Number of Slack users active in Claude Tag in the 7-day rolling window. Counts distinct Slack users, including users who have not linked a Claude account, so it can exceed `daily_active_user_count` and `assigned_seat_count`. Null on a day with no measured value, when Claude Tag data cannot be read for the request, and when the response is scoped to an RBAC group, because an unlinked user belongs to no group. Omitted from the response on deployments that do not offer Claude Tag reporting.
1283
12581284 - `office_agent_daily_active_user_count: optional number or null`
12591285
12601286 Number of users with Claude in Office activity on the requested day. Omitted from the response while the per-product breakdown is not enabled for this organization.
from line 2070
20442070
20452071 Same measure as `cowork_metrics.write_tool_count`, for activity recorded while members had Chat and Cowork unified turned on.
20462072
2073 - `claude_tag_metrics: optional AnalyticsClaudeTagMetrics or null`
2074
2075 Claude Tag activity in Slack by a user who has linked a Claude account. Activity by Slack users who have not linked an account appears only in the `/summaries` Claude Tag counts, so these rows do not add up to those counts. Omitted from the response on deployments that do not offer Claude Tag reporting.
2076
2077 - `active_day_count: number or null`
2078
2079 1 on a day the user was active in Claude Tag in Slack, otherwise 0. Summed over the window in date-range mode, so it is the number of active days; on grouped rows, the total of each member's active days. Null when Claude Tag data cannot be read for the request. Otherwise, 0 on a row filtered by project, and null on any other row when no covered day was measured.
2080
2081 - `active_message_count: number or null`
2082
2083 Number of the user's Slack messages that made them active: @-mentions, direct messages, group direct message asks, and thread posts Claude answered. Other messages are not counted. Null when Claude Tag data cannot be read for the request. Otherwise, 0 on a row filtered by project, and null on any other row when no covered day was measured.
2084
20472085 - `last_activity_date: optional string or null`
20482086
20492087 Most recent UTC day (YYYY-MM-DD) on which the user had any counted activity, within the requested window: equal to the requested `date` in single-day mode, and to the latest active day from `starting_date` (inclusive) to `ending_date` (exclusive) in date-range rollup mode — never a day earlier than the window start. On filtered requests (`filter[]`) only days matching the filter count: with `filter[]=rbac_group_id:{id}` it is the last day the user was active while a member of that group, consistent with the row's other metrics. On grouped (`group_by[]`) rows it is the latest day any member of the group was active (the requested `date` in single-day mode). Omitted from the response while last-activity reporting is not enabled for this organization.
from line 2269
22312269
22322270 Number of users with Claude Design activity in the 7-day rolling window. Omitted from the response while the per-product breakdown is not enabled for this organization.
22332271
2272 - `claude_tag_daily_active_user_count: optional number or null`
2273
2274 Number of Slack users active in Claude Tag on the requested day. Counts distinct Slack users, including users who have not linked a Claude account, so it can exceed `daily_active_user_count` and `assigned_seat_count`. Null on a day with no measured value, when Claude Tag data cannot be read for the request, and when the response is scoped to an RBAC group, because an unlinked user belongs to no group. Omitted from the response on deployments that do not offer Claude Tag reporting.
2275
2276 - `claude_tag_monthly_active_user_count: optional number or null`
2277
2278 Number of Slack users active in Claude Tag in the 28-day rolling window. Counts distinct Slack users, including users who have not linked a Claude account, so it can exceed `daily_active_user_count` and `assigned_seat_count`. Null on a day with no measured value, when Claude Tag data cannot be read for the request, and when the response is scoped to an RBAC group, because an unlinked user belongs to no group. Omitted from the response on deployments that do not offer Claude Tag reporting.
2279
2280 - `claude_tag_weekly_active_user_count: optional number or null`
2281
2282 Number of Slack users active in Claude Tag in the 7-day rolling window. Counts distinct Slack users, including users who have not linked a Claude account, so it can exceed `daily_active_user_count` and `assigned_seat_count`. Null on a day with no measured value, when Claude Tag data cannot be read for the request, and when the response is scoped to an RBAC group, because an unlinked user belongs to no group. Omitted from the response on deployments that do not offer Claude Tag reporting.
2283
22342284 - `office_agent_daily_active_user_count: optional number or null`
22352285
22362286 Number of users with Claude in Office activity on the requested day. Omitted from the response while the per-product breakdown is not enabled for this organization.
from line 2352
23022352 "claude_design_daily_active_user_count": 0,
23032353 "claude_design_monthly_active_user_count": 0,
23042354 "claude_design_weekly_active_user_count": 0,
2355 "claude_tag_daily_active_user_count": 0,
2356 "claude_tag_monthly_active_user_count": 0,
2357 "claude_tag_weekly_active_user_count": 0,
23052358 "office_agent_daily_active_user_count": 0,
23062359 "office_agent_monthly_active_user_count": 0,
23072360 "office_agent_weekly_active_user_count": 0,
from line 2880
28272880
28282881 Same measure as `cowork_metrics.write_tool_count`, for activity recorded while members had Chat and Cowork unified turned on.
28292882
2883 - `claude_tag_metrics: optional AnalyticsClaudeTagMetrics or null`
2884
2885 Claude Tag activity in Slack by a user who has linked a Claude account. Activity by Slack users who have not linked an account appears only in the `/summaries` Claude Tag counts, so these rows do not add up to those counts. Omitted from the response on deployments that do not offer Claude Tag reporting.
2886
2887 - `active_day_count: number or null`
2888
2889 1 on a day the user was active in Claude Tag in Slack, otherwise 0. Summed over the window in date-range mode, so it is the number of active days; on grouped rows, the total of each member's active days. Null when Claude Tag data cannot be read for the request. Otherwise, 0 on a row filtered by project, and null on any other row when no covered day was measured.
2890
2891 - `active_message_count: number or null`
2892
2893 Number of the user's Slack messages that made them active: @-mentions, direct messages, group direct message asks, and thread posts Claude answered. Other messages are not counted. Null when Claude Tag data cannot be read for the request. Otherwise, 0 on a row filtered by project, and null on any other row when no covered day was measured.
2894
28302895 - `last_activity_date: optional string or null`
28312896
28322897 Most recent UTC day (YYYY-MM-DD) on which the user had any counted activity, within the requested window: equal to the requested `date` in single-day mode, and to the latest active day from `starting_date` (inclusive) to `ending_date` (exclusive) in date-range rollup mode — never a day earlier than the window start. On filtered requests (`filter[]`) only days matching the filter count: with `filter[]=rbac_group_id:{id}` it is the last day the user was active while a member of that group, consistent with the row's other metrics. On grouped (`group_by[]`) rows it is the latest day any member of the group was active (the requested `date` in single-day mode). Omitted from the response while last-activity reporting is not enabled for this organization.
from line 3075
30103075 "skills_used_count": 0,
30113076 "write_tool_count": 0
30123077 }
3078 },
3079 "claude_tag_metrics": {
3080 "active_day_count": 0,
3081 "active_message_count": 0
30133082 },
30143083 "last_activity_date": "2019-12-27",
30153084 "rbac_group_id": "rbac_group_id",
api/organization/analytics/summaries Changed · +15 / -0 lines
from line 170
170170
171171 Number of users with Claude Design activity in the 7-day rolling window. Omitted from the response while the per-product breakdown is not enabled for this organization.
172172
173 - `claude_tag_daily_active_user_count: optional number or null`
174
175 Number of Slack users active in Claude Tag on the requested day. Counts distinct Slack users, including users who have not linked a Claude account, so it can exceed `daily_active_user_count` and `assigned_seat_count`. Null on a day with no measured value, when Claude Tag data cannot be read for the request, and when the response is scoped to an RBAC group, because an unlinked user belongs to no group. Omitted from the response on deployments that do not offer Claude Tag reporting.
176
177 - `claude_tag_monthly_active_user_count: optional number or null`
178
179 Number of Slack users active in Claude Tag in the 28-day rolling window. Counts distinct Slack users, including users who have not linked a Claude account, so it can exceed `daily_active_user_count` and `assigned_seat_count`. Null on a day with no measured value, when Claude Tag data cannot be read for the request, and when the response is scoped to an RBAC group, because an unlinked user belongs to no group. Omitted from the response on deployments that do not offer Claude Tag reporting.
180
181 - `claude_tag_weekly_active_user_count: optional number or null`
182
183 Number of Slack users active in Claude Tag in the 7-day rolling window. Counts distinct Slack users, including users who have not linked a Claude account, so it can exceed `daily_active_user_count` and `assigned_seat_count`. Null on a day with no measured value, when Claude Tag data cannot be read for the request, and when the response is scoped to an RBAC group, because an unlinked user belongs to no group. Omitted from the response on deployments that do not offer Claude Tag reporting.
184
173185 - `office_agent_daily_active_user_count: optional number or null`
174186
175187 Number of users with Claude in Office activity on the requested day. Omitted from the response while the per-product breakdown is not enabled for this organization.
from line 253
241253 "claude_design_daily_active_user_count": 0,
242254 "claude_design_monthly_active_user_count": 0,
243255 "claude_design_weekly_active_user_count": 0,
256 "claude_tag_daily_active_user_count": 0,
257 "claude_tag_monthly_active_user_count": 0,
258 "claude_tag_weekly_active_user_count": 0,
244259 "office_agent_daily_active_user_count": 0,
245260 "office_agent_monthly_active_user_count": 0,
246261 "office_agent_weekly_active_user_count": 0,
api/organization/analytics/summaries/list Changed · +15 / -0 lines
from line 168
168168
169169 Number of users with Claude Design activity in the 7-day rolling window. Omitted from the response while the per-product breakdown is not enabled for this organization.
170170
171 - `claude_tag_daily_active_user_count: optional number or null`
172
173 Number of Slack users active in Claude Tag on the requested day. Counts distinct Slack users, including users who have not linked a Claude account, so it can exceed `daily_active_user_count` and `assigned_seat_count`. Null on a day with no measured value, when Claude Tag data cannot be read for the request, and when the response is scoped to an RBAC group, because an unlinked user belongs to no group. Omitted from the response on deployments that do not offer Claude Tag reporting.
174
175 - `claude_tag_monthly_active_user_count: optional number or null`
176
177 Number of Slack users active in Claude Tag in the 28-day rolling window. Counts distinct Slack users, including users who have not linked a Claude account, so it can exceed `daily_active_user_count` and `assigned_seat_count`. Null on a day with no measured value, when Claude Tag data cannot be read for the request, and when the response is scoped to an RBAC group, because an unlinked user belongs to no group. Omitted from the response on deployments that do not offer Claude Tag reporting.
178
179 - `claude_tag_weekly_active_user_count: optional number or null`
180
181 Number of Slack users active in Claude Tag in the 7-day rolling window. Counts distinct Slack users, including users who have not linked a Claude account, so it can exceed `daily_active_user_count` and `assigned_seat_count`. Null on a day with no measured value, when Claude Tag data cannot be read for the request, and when the response is scoped to an RBAC group, because an unlinked user belongs to no group. Omitted from the response on deployments that do not offer Claude Tag reporting.
182
171183 - `office_agent_daily_active_user_count: optional number or null`
172184
173185 Number of users with Claude in Office activity on the requested day. Omitted from the response while the per-product breakdown is not enabled for this organization.
from line 251
239251 "claude_design_daily_active_user_count": 0,
240252 "claude_design_monthly_active_user_count": 0,
241253 "claude_design_weekly_active_user_count": 0,
254 "claude_tag_daily_active_user_count": 0,
255 "claude_tag_monthly_active_user_count": 0,
256 "claude_tag_weekly_active_user_count": 0,
242257 "office_agent_daily_active_user_count": 0,
243258 "office_agent_monthly_active_user_count": 0,
244259 "office_agent_weekly_active_user_count": 0,
api/organization/analytics/users Changed · +16 / -0 lines
from line 515
515515
516516 Same measure as `cowork_metrics.write_tool_count`, for activity recorded while members had Chat and Cowork unified turned on.
517517
518 - `claude_tag_metrics: optional AnalyticsClaudeTagMetrics or null`
519
520 Claude Tag activity in Slack by a user who has linked a Claude account. Activity by Slack users who have not linked an account appears only in the `/summaries` Claude Tag counts, so these rows do not add up to those counts. Omitted from the response on deployments that do not offer Claude Tag reporting.
521
522 - `active_day_count: number or null`
523
524 1 on a day the user was active in Claude Tag in Slack, otherwise 0. Summed over the window in date-range mode, so it is the number of active days; on grouped rows, the total of each member's active days. Null when Claude Tag data cannot be read for the request. Otherwise, 0 on a row filtered by project, and null on any other row when no covered day was measured.
525
526 - `active_message_count: number or null`
527
528 Number of the user's Slack messages that made them active: @-mentions, direct messages, group direct message asks, and thread posts Claude answered. Other messages are not counted. Null when Claude Tag data cannot be read for the request. Otherwise, 0 on a row filtered by project, and null on any other row when no covered day was measured.
529
518530 - `last_activity_date: optional string or null`
519531
520532 Most recent UTC day (YYYY-MM-DD) on which the user had any counted activity, within the requested window: equal to the requested `date` in single-day mode, and to the latest active day from `starting_date` (inclusive) to `ending_date` (exclusive) in date-range rollup mode — never a day earlier than the window start. On filtered requests (`filter[]`) only days matching the filter count: with `filter[]=rbac_group_id:{id}` it is the last day the user was active while a member of that group, consistent with the row's other metrics. On grouped (`group_by[]`) rows it is the latest day any member of the group was active (the requested `date` in single-day mode). Omitted from the response while last-activity reporting is not enabled for this organization.
from line 710
698710 "skills_used_count": 0,
699711 "write_tool_count": 0
700712 }
713 },
714 "claude_tag_metrics": {
715 "active_day_count": 0,
716 "active_message_count": 0
701717 },
702718 "last_activity_date": "2019-12-27",
703719 "rbac_group_id": "rbac_group_id",
api/organization/analytics/users/list Changed · +16 / -0 lines
from line 513
513513
514514 Same measure as `cowork_metrics.write_tool_count`, for activity recorded while members had Chat and Cowork unified turned on.
515515
516 - `claude_tag_metrics: optional AnalyticsClaudeTagMetrics or null`
517
518 Claude Tag activity in Slack by a user who has linked a Claude account. Activity by Slack users who have not linked an account appears only in the `/summaries` Claude Tag counts, so these rows do not add up to those counts. Omitted from the response on deployments that do not offer Claude Tag reporting.
519
520 - `active_day_count: number or null`
521
522 1 on a day the user was active in Claude Tag in Slack, otherwise 0. Summed over the window in date-range mode, so it is the number of active days; on grouped rows, the total of each member's active days. Null when Claude Tag data cannot be read for the request. Otherwise, 0 on a row filtered by project, and null on any other row when no covered day was measured.
523
524 - `active_message_count: number or null`
525
526 Number of the user's Slack messages that made them active: @-mentions, direct messages, group direct message asks, and thread posts Claude answered. Other messages are not counted. Null when Claude Tag data cannot be read for the request. Otherwise, 0 on a row filtered by project, and null on any other row when no covered day was measured.
527
516528 - `last_activity_date: optional string or null`
517529
518530 Most recent UTC day (YYYY-MM-DD) on which the user had any counted activity, within the requested window: equal to the requested `date` in single-day mode, and to the latest active day from `starting_date` (inclusive) to `ending_date` (exclusive) in date-range rollup mode — never a day earlier than the window start. On filtered requests (`filter[]`) only days matching the filter count: with `filter[]=rbac_group_id:{id}` it is the last day the user was active while a member of that group, consistent with the row's other metrics. On grouped (`group_by[]`) rows it is the latest day any member of the group was active (the requested `date` in single-day mode). Omitted from the response while last-activity reporting is not enabled for this organization.
from line 708
696708 "skills_used_count": 0,
697709 "write_tool_count": 0
698710 }
711 },
712 "claude_tag_metrics": {
713 "active_day_count": 0,
714 "active_message_count": 0
699715 },
700716 "last_activity_date": "2019-12-27",
701717 "rbac_group_id": "rbac_group_id",
managed-agents/events-and-streaming Changed · +8 / -8 lines
from line 683
6836833. For each blocking event ID, send a [`user.custom_tool_result`](https://platform.claude.com/docs/en/managed-agents/events-and-streaming#return-a-custom-tool-result) or a [`user.tool_confirmation`](https://platform.claude.com/docs/en/managed-agents/events-and-streaming#confirm-a-tool-call) event. A custom tool result doesn’t have to wait for step 2.
6846844. Once all blocking events are resolved, the session transitions back to `running`.
685685
686In a multiagent session, a subagent’s blocking events are cross-posted to the primary thread. See [Tool permissions and custom tools](https://platform.claude.com/docs/en/managed-agents/session-threads#tool-permissions-and-custom-tools).
686In a multiagent session, the server cross-posts a subagent’s blocking events to the primary thread. See [Tool permissions and custom tools](https://platform.claude.com/docs/en/managed-agents/session-threads#tool-permissions-and-custom-tools).
687687
688688### Return a custom tool result
689689
690690The `agent.custom_tool_use` event contains the tool name and input. Run the tool in your system. Then send a `user.custom_tool_result` event, passing the event ID in the `custom_tool_use_id` (java: `customToolUseId`; php: `customToolUseID`; csharp, go: `CustomToolUseID`) parameter along with the result content.
691691
692You can send the result as soon as the `agent.custom_tool_use` event arrives, without waiting for `session.status_idle`. The session still emits `session.status_idle` with a `requires_action` stop reason for the call, and your client can ignore it. A second result for the same call is accepted and has no effect.
692You can send the result as soon as the `agent.custom_tool_use` event arrives, without waiting for `session.status_idle`. The session still emits `session.status_idle` with a `requires_action` stop reason for the call, and your client can ignore it. The server accepts a second result for the same call, but that result has no effect.
693693
694When you [reconnect](https://platform.claude.com/docs/en/managed-agents/events-and-streaming#reconnect-without-missing-events) to a paused session, `stop_reason.event_ids` on the latest `session.status_idle` event lists the calls to answer.
694When you [reconnect to a paused session](https://platform.claude.com/docs/en/managed-agents/events-and-streaming#reconnect-without-missing-events), `stop_reason.event_ids` on the latest `session.status_idle` event lists the calls to answer.
695695
696696The following example answers each call as it arrives:
697697
from line 1251
12511251 ```
12521252</CodeGroup>
12531253
1254Conversation history is preserved unless the session is explicitly deleted. When a session goes idle, its sandbox is checkpointed. The checkpoint preserves the full sandbox state, including the filesystem, installed packages, and any files the agent created.
1254A session keeps its conversation history until you delete the session. When a session goes idle, Claude Managed Agents checkpoints its sandbox. The checkpoint preserves the full sandbox state, including the filesystem, installed packages, and any files the agent created.
12551255
12561256<Note>
12571257 Sandbox state is preserved for only 30 days after the sandbox is created, and activity does not extend this window. After 30 days the sandbox state (files, installed tools, and so on) is unrecoverable, and a resumed session starts from a fresh sandbox. If your workflow depends on sandbox contents, have the agent write important artifacts to [outputs](https://platform.claude.com/docs/en/managed-agents/define-outcomes#retrieving-deliverables) before the window ends.
from line 1607
16071607
16081608On a [supported model](https://platform.claude.com/docs/en/managed-agents/events-and-streaming#supported-models), send a `system.message` event to give the agent privileged system-level context. The context applies to the accompanying turn and all subsequent turns. Use it when the agent needs updated system-level guidance mid-session, for example a different persona, revised constraints, or context fetched at runtime.
16091609
1610The event’s `content` (csharp, go: `Content`) accepts 1–1,000 text items. The content is appended to the session’s system context as a `role: "system"` turn. It doesn’t replace the top-level system prompt, which the `system` (csharp, go: `System`; ruby: `system_`) field on the agent definition sets.
1610The event’s `content` (csharp, go: `Content`) accepts 1–1,000 text items. The server appends the content to the session’s system context as a `role: "system"` turn. It doesn’t replace the top-level system prompt, which the `system` (csharp, go: `System`; ruby: `system_`) field on the agent definition sets.
16111611
16121612<CodeGroup>
16131613 ```bash cURL
from line 1748
17481748
17491749### Supported models
17501750
1751`system.message` is supported by these models:
1751These models support `system.message`:
17521752
17531753* Claude Fable 5.2
17541754* Claude Mythos 5.2
from line 1762
17621762* Claude Sonnet 5.5
17631763* Claude Haiku 5.5
17641764
1765If the agent’s primary model does not support mid-conversation system injection, the event is rejected with a `model_does_not_support_mid_conversation_system` validation error. Subagent models are not checked, because `system.message` lands on the primary thread only.
1765If the agent’s primary model does not support mid-conversation system injection, the API rejects the event with a `model_does_not_support_mid_conversation_system` validation error. The API does not check subagent models, because `system.message` lands on the primary thread only.
17661766
17671767### System messages while a tool call is pending
17681768
managed-agents/migration Changed · +12 / -12 lines
### What you control ### What you still control
from line 41
4141
4242## From a Messages API agent loop
4343
44If you built an agent by calling `client.messages.create()` (csharp: `client.Messages.Create()`; go: `client.Messages.New()`; java: `client.messages().create()`; php: `$client->messages->create()`; cli: `ant messages create`; curl: `POST /v1/messages`) in a loop, running tool calls yourself, and appending results to the conversation history, most of that code goes away.
44If you built an agent by calling `client.messages.create()` (csharp: `client.Messages.Create()`; go: `client.Messages.New()`; java: `client.messages().create()`; php: `$client->messages->create()`; cli: `ant messages create`; curl: `POST /v1/messages`) in a loop, running tool calls yourself, and appending results to the conversation history, Claude Managed Agents replaces most of that loop code.
4545
4646### What you stop managing
4747
from line 530
530530 ```
531531</CodeGroup>
532532
533### What you still control
533### What you control
534534
535* **System prompt and model:** Same fields, now on the agent definition.
536* **Custom tools:** Still declared with JSON Schema. Execution moves from inline handling to responding to `agent.custom_tool_use` events. See [Session event stream](https://platform.claude.com/docs/en/managed-agents/events-and-streaming).
537* **Web search and web fetch settings:** Same `allowed_domains` (java, php: `allowedDomains`; csharp, go: `AllowedDomains`), `blocked_domains` (java, php: `blockedDomains`; csharp, go: `BlockedDomains`), `max_content_tokens` (java, php: `maxContentTokens`; csharp, go: `MaxContentTokens`), and `user_location` (java, php: `userLocation`; csharp, go: `UserLocation`) fields, now set once on the `web_search` and `web_fetch` entries of the agent toolset’s `configs` (csharp, go: `Configs`) array instead of on every request. The `max_uses` (java, php: `maxUses`; csharp, go: `MaxUses`), `citations` (csharp, go: `Citations`), and `cache_control` (java, php: `cacheControl`; csharp, go: `CacheControl`) fields are not available. See [Differences from the Messages API tools](https://platform.claude.com/docs/en/managed-agents/tools-web-restrictions#differences-from-the-messages-api-tools).
538* **Context:** You can still inject context through the system prompt, [file resources](https://platform.claude.com/docs/en/managed-agents/files), or [skills](https://platform.claude.com/docs/en/managed-agents/skills).
535* **System prompt and model:** Same fields, on the agent definition.
536* **Custom tools:** Declared with JSON Schema. Your client runs them when `agent.custom_tool_use` events arrive, not inside a request loop. See [Session event stream](https://platform.claude.com/docs/en/managed-agents/events-and-streaming).
537* **Web search and web fetch settings:** Same `allowed_domains` (java, php: `allowedDomains`; csharp, go: `AllowedDomains`), `blocked_domains` (java, php: `blockedDomains`; csharp, go: `BlockedDomains`), `max_content_tokens` (java, php: `maxContentTokens`; csharp, go: `MaxContentTokens`), and `user_location` (java, php: `userLocation`; csharp, go: `UserLocation`) fields, set once on the `web_search` and `web_fetch` entries of the agent toolset’s `configs` (csharp, go: `Configs`) array instead of on every request. The `max_uses` (java, php: `maxUses`; csharp, go: `MaxUses`), `citations` (csharp, go: `Citations`), and `cache_control` (java, php: `cacheControl`; csharp, go: `CacheControl`) fields are not available. See [Differences from the Messages API tools](https://platform.claude.com/docs/en/managed-agents/tools-web-restrictions#differences-from-the-messages-api-tools).
538* **Context:** You can inject context through the system prompt, [file resources](https://platform.claude.com/docs/en/managed-agents/files), or [skills](https://platform.claude.com/docs/en/managed-agents/skills).
539539
540540## From the Claude Agent SDK
541541
from line 552
552552| `cwd`, `add_dirs` (typescript: `additionalDirectories`) point at local paths | Upload or mount [files](https://platform.claude.com/docs/en/managed-agents/files) as session resources. |
553553| `system_prompt` (typescript: `systemPrompt`) and the `CLAUDE.md` hierarchy | A single `system` (csharp, go: `System`; ruby: `system_`) string on the agent. Each update that changes the agent produces a new server-side version; pin sessions to a specific version to promote or roll back without a deploy. See [Define your agent](https://platform.claude.com/docs/en/managed-agents/agent-setup). |
554554| `mcp_servers` (typescript: `mcpServers`) configured and authenticated in one place | Declare servers on the agent; provide credentials through a [vault](https://platform.claude.com/docs/en/managed-agents/vaults) on the session. |
555| `permission_mode` (typescript: `permissionMode`), `can_use_tool` (typescript: `canUseTool`) | Per-tool [`permission_policy` (java, php: `permissionPolicy`; csharp, go: `PermissionPolicy`)](https://platform.claude.com/docs/en/managed-agents/permission-policies) (`always_allow`, `always_ask`, or `auto`); send `user.tool_confirmation` events for calls that pause for your approval. |
555| `permission_mode` (typescript: `permissionMode`), `can_use_tool` (typescript: `canUseTool`) | Per-tool [`permission_policy` (java, php: `permissionPolicy`; csharp, go: `PermissionPolicy`)](https://platform.claude.com/docs/en/managed-agents/permission-policies) (`always_allow`, `always_ask`, or `auto`). Send `user.tool_confirmation` events for calls that pause for your approval. |
556556
557557### Code comparison
558558
from line 1267
126712672. Port your system prompt and tool selection to an [agent definition](https://platform.claude.com/docs/en/managed-agents/agent-setup).
126812683. Replace your loop: [create a session](https://platform.claude.com/docs/en/managed-agents/sessions) with `client.beta.sessions.create()` (go: `client.Beta.Sessions.New()`; csharp: `client.Beta.Sessions.Create()`; java: `client.beta().sessions().create()`; php: `$client->beta->sessions->create()`; cli: `ant beta:sessions create`; curl: `POST /v1/sessions`) and [stream its events](https://platform.claude.com/docs/en/managed-agents/events-and-streaming) with `client.beta.sessions.events.stream()` (ruby: `client.beta.sessions.events.stream_events()`; go: `client.Beta.Sessions.Events.StreamEvents()`; csharp: `client.Beta.Sessions.Events.StreamStreaming()`; java: `client.beta().sessions().events().streamStreaming()`; php: `$client->beta->sessions->events->streamStream()`; cli: `ant beta:sessions:events stream`; curl: `GET /v1/sessions/{session_id}/events/stream`).
126912694. For any local files the agent reads, upload them through the [Files API](https://platform.claude.com/docs/en/managed-agents/files) and mount them as `resources` (csharp, go: `Resources`).
12705. For any custom tool handlers, move execution into your event loop as responses to `agent.custom_tool_use` events.
12716. Verify with a test session before pointing production traffic at the new flow.
12705. For any custom tool handlers, run them in your event loop as responses to `agent.custom_tool_use` events.
12716. Run a test session before you point production traffic at the migrated flow.
12721272
12731273## Migrating between model versions
12741274
from line 1370
13701370
13711371Most model-level behavior changes documented in the [Migration guides](https://platform.claude.com/docs/en/about-claude/models/migration-guide) do not require action on your side:
13721372
1373* **Request parameter changes** (`max_tokens` (java, php: `maxTokens`; csharp, go: `MaxTokens`) defaults, `thinking` (csharp, go: `Thinking`) configuration) are handled by the Claude Managed Agents runtime. These fields are not exposed on the agent definition.
1373* **Request parameter changes** (`max_tokens` (java, php: `maxTokens`; csharp, go: `MaxTokens`) defaults, `thinking` (csharp, go: `Thinking`) configuration) need no action: the Claude Managed Agents runtime handles them. The agent definition does not expose these fields.
13741374* **Assistant message prefilling** does not exist in the event-based session model, so moving to a model that rejects prefill needs no change from you.
1375* **Tool argument JSON escaping** is parsed by the runtime before you receive `agent.custom_tool_use` events. You see structured data, not raw strings.
1375* **Tool argument JSON escaping** needs no action: the runtime parses the arguments before you receive `agent.custom_tool_use` events. You see structured data, not raw strings.
13761376
13771377The behavior descriptions in those guides (what the model does differently) still apply. The migration steps (how to change your request code) do not.
13781378
managed-agents/reference Changed · +24 / -24 lines
from line 41
4141
4242## Event types
4343
44Persisted event type strings follow a `{domain}.{action}` naming convention; the stream-only event deltas (see the **Event deltas** tab) are the exception. See [Session event stream](https://platform.claude.com/docs/en/managed-agents/events-and-streaming) for sending, streaming, and listing events. Webhook event types are listed separately in [Subscribe to webhooks](https://platform.claude.com/docs/en/managed-agents/webhooks#supported-event-types), and some of their names differ from the stream’s (for example, `session.status_idled` rather than `session.status_idle`).
44Persisted event type strings follow a `{domain}.{action}` naming convention; the stream-only event deltas (see the **Event deltas** tab) are the exception. See [Session event stream](https://platform.claude.com/docs/en/managed-agents/events-and-streaming) for sending, streaming, and listing events. [Subscribe to webhooks](https://platform.claude.com/docs/en/managed-agents/webhooks#supported-event-types) lists webhook event types separately, and some of their names differ from the stream’s (for example, `session.status_idled` rather than `session.status_idle`).
4545
4646<Tabs>
4747 <Tab title="User events">
from line 56
5656 </Tab>
5757
5858 <Tab title="Agent events">
59 | Type | Description |
60 | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
61 | `agent.message` | Agent response content blocks. |
62 | `agent.thinking` | Signals the agent is making forward progress through extended thinking. This is a progress signal only and does not carry the thinking content. |
63 | `agent.tool_use` | Agent calls a pre-built agent tool (bash, file operations, and so on). Carries `evaluated_permission` (java, php: `evaluatedPermission`; csharp, go: `EvaluatedPermission`) and, usually, `evaluation` (csharp, go: `Evaluation`) (see [how each call was evaluated](https://platform.claude.com/docs/en/managed-agents/permission-policies#see-how-each-call-was-evaluated)). |
64 | `agent.tool_result` | Result of a pre-built agent tool execution. |
65 | `agent.mcp_tool_use` | Agent calls an MCP server tool. Carries `evaluated_permission` (java, php: `evaluatedPermission`; csharp, go: `EvaluatedPermission`) and, usually, `evaluation` (csharp, go: `Evaluation`) (see [how each call was evaluated](https://platform.claude.com/docs/en/managed-agents/permission-policies#see-how-each-call-was-evaluated)). |
66 | `agent.mcp_tool_result` | Result of an MCP tool execution. |
67 | `agent.custom_tool_use` | Agent calls one of your custom tools. Respond with a `user.custom_tool_result` event. |
68 | `agent.thread_context_compacted` | Conversation history was compacted to fit the context window. |
69 | `agent.thread_message_received` | In a [multiagent](https://platform.claude.com/docs/en/managed-agents/multiagent-orchestration) session, a message from another thread arrived on the thread whose stream carries this event; on the primary thread, an agent sent a report or question to the agent that the session runs. |
70 | `agent.thread_message_sent` | In a [multiagent](https://platform.claude.com/docs/en/managed-agents/multiagent-orchestration) session, the thread whose stream carries this event sent a message to another thread; on the primary thread, the agent that the session runs sent a task or follow-up message to another agent. |
59 | Type | Description |
60 | -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
61 | `agent.message` | Agent response content blocks. |
62 | `agent.thinking` | Signals the agent is making forward progress through extended thinking. This is a progress signal only and does not carry the thinking content. |
63 | `agent.tool_use` | Agent calls a prebuilt agent tool (bash, file operations, and so on). Carries `evaluated_permission` (java, php: `evaluatedPermission`; csharp, go: `EvaluatedPermission`) and, usually, `evaluation` (csharp, go: `Evaluation`) (see [how each call was evaluated](https://platform.claude.com/docs/en/managed-agents/permission-policies#see-how-each-call-was-evaluated)). |
64 | `agent.tool_result` | Result of running a prebuilt agent tool. |
65 | `agent.mcp_tool_use` | Agent calls an MCP server tool. Carries `evaluated_permission` (java, php: `evaluatedPermission`; csharp, go: `EvaluatedPermission`) and, usually, `evaluation` (csharp, go: `Evaluation`) (see [how each call was evaluated](https://platform.claude.com/docs/en/managed-agents/permission-policies#see-how-each-call-was-evaluated)). |
66 | `agent.mcp_tool_result` | Result of running an MCP tool. |
67 | `agent.custom_tool_use` | Agent calls one of your custom tools. Respond with a `user.custom_tool_result` event. |
68 | `agent.thread_context_compacted` | Conversation history was compacted to fit the context window. |
69 | `agent.thread_message_received` | In a [multiagent](https://platform.claude.com/docs/en/managed-agents/multiagent-orchestration) session, a message from another thread arrived on the thread whose stream carries this event. On the primary thread, an agent sent a report or question to the agent that the session runs. |
70 | `agent.thread_message_sent` | In a [multiagent](https://platform.claude.com/docs/en/managed-agents/multiagent-orchestration) session, the thread whose stream carries this event sent a message to another thread. On the primary thread, the agent that the session runs sent a task or follow-up message to another agent. |
7171
72 Message content in these events can include a `redacted` content block, `{"type": "redacted"}`: a placeholder for content withheld by Anthropic model policy. The block carries no other fields. Redacted blocks appear only in content the platform emits; a user event that includes one is rejected with a 400 error.
72 Message content in these events can include a `redacted` content block, `{"type": "redacted"}`: a placeholder for content withheld by Anthropic model policy. The block carries no other fields. Redacted blocks appear only in content the platform emits. If a user event includes one, the API rejects it with a 400 error.
7373 </Tab>
7474
7575 <Tab title="Session events">
from line 79
7979 | `session.status_idle` | Agent finished its current task and is waiting for input. Includes a `stop_reason` (java, php: `stopReason`; csharp, go: `StopReason`) indicating why the agent stopped. |
8080 | `session.status_rescheduled` | A transient error occurred and the session is retrying automatically. |
8181 | `session.status_terminated` | Session ended, either because of an unrecoverable error or because it was archived. |
82 | `session.deleted` | Session was deleted. Ends any active event stream; no further events are emitted for this session. |
82 | `session.deleted` | Session was deleted. Ends any active event stream. The session emits no further events. |
8383 | `session.updated` | Session update request changed at least one field. Includes only the fields that changed. Updates apply on the next turn. |
8484 | `session.error` | An error occurred during processing. Includes a typed `error` (csharp, go: `Error`) object with a `retry_status` (java, php: `retryStatus`; csharp, go: `RetryStatus`). |
8585 | `session.usage` | Snapshot of the session’s cumulative usage and tracked list cost. Carries the session’s usage totals and, if the session has one, its [budget](https://platform.claude.com/docs/en/managed-agents/budgets). |
from line 94
9494 | Type | Description |
9595 | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
9696 | `workflow_run.created` | A workflow run was created. Includes `workflow_run_id` (java: `workflowRunId`; php: `workflowRunID`; csharp, go: `WorkflowRunID`), the run’s `name` (csharp, go: `Name`) and `description` (csharp, go: `Description`), and `phases` (csharp, go: `Phases`), the phases declared for the run. A status event follows, though after an interrupt it might not. |
97 | `workflow_run.status_running` | A workflow run is running. Sent when the run starts to execute, which can be a while after `workflow_run.created`, and again when it resumes after a pause at the budget. A resume after an interrupt might not send it. A run that is idle from the start might get `workflow_run.status_idle` first. Includes `workflow_run_id` (java: `workflowRunId`; php: `workflowRunID`; csharp, go: `WorkflowRunID`). |
97 | `workflow_run.status_running` | A workflow run is running. Sent when the run starts, which can be a while after `workflow_run.created`, and again when it resumes after a pause at the budget. A resume after an interrupt might not send it. A run that is idle from the start might get `workflow_run.status_idle` first. Includes `workflow_run_id` (java: `workflowRunId`; php: `workflowRunID`; csharp, go: `WorkflowRunID`). |
9898 | `workflow_run.status_idle` | A workflow run went idle: it was paused, for example at the session’s budget. A pause after an interrupt might not send it. Includes `workflow_run_id` (java: `workflowRunId`; php: `workflowRunID`; csharp, go: `WorkflowRunID`). |
9999 | `workflow_run.status_ended` | A workflow run ended. Includes `workflow_run_id` (java: `workflowRunId`; php: `workflowRunID`; csharp, go: `WorkflowRunID`) and `result` (csharp, go: `Result`), whose `type` (csharp, go: `Type`) says how the run ended. |
100100 | `workflow_run.error` | An error of a workflow run, or a start that the server refused. A run that ends in error gets it, with the same error, before its `workflow_run.status_ended`. Includes `error` (csharp, go: `Error`) and `workflow_run_id` (java: `workflowRunId`; php: `workflowRunID`; csharp, go: `WorkflowRunID`), which is `null` (python: `None`; ruby: `nil`; java: `Optional.empty()`; go: `""`) when no run was created. |
from line 115
115115 </Tab>
116116
117117 <Tab title="System events">
118 | Type | Description |
119 | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
120 | `system.message` | Append privileged system-level context that applies to the accompanying turn and all subsequent turns. For the models that accept it, see [Supported models](https://platform.claude.com/docs/en/managed-agents/events-and-streaming#supported-models). On an unsupported primary model the event is rejected with `model_does_not_support_mid_conversation_system`. |
118 | Type | Description |
119 | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
120 | `system.message` | Append privileged system-level context that applies to the accompanying turn and all subsequent turns. For the models that accept it, see [Supported models](https://platform.claude.com/docs/en/managed-agents/events-and-streaming#supported-models). On an unsupported primary model, the API rejects the event with `model_does_not_support_mid_conversation_system`. |
121121 </Tab>
122122
123123 <Tab title="Event deltas">
124 Event deltas are stream-only preview events. They are emitted on stream connections (session-level or per-thread) that opt in with the `event_deltas` (curl: `event_deltas[]`; cli: `--event-delta`; java, php: `eventDeltas`; csharp, go: `EventDeltas`) parameter, and they are never persisted to the session’s event history. See [Preview responses with event deltas](https://platform.claude.com/docs/en/managed-agents/event-deltas) for opting in, accumulating, and reconciling them.
124 Event deltas are stream-only preview events. The server emits them on stream connections (session-level or per-thread) that opt in with the `event_deltas` (curl: `event_deltas[]`; cli: `--event-delta`; java, php: `eventDeltas`; csharp, go: `EventDeltas`) parameter. The server never persists them to the session’s event history. See [Preview responses with event deltas](https://platform.claude.com/docs/en/managed-agents/event-deltas) for opting in, accumulating, and reconciling them.
125125
126126 | Type | Description |
127127 | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
from line 132
132132
133133## Self-hosted worker
134134
135See [Self-hosted worker reference](https://platform.claude.com/docs/en/managed-agents/self-hosted-sandboxes-reference) for the `ant beta:worker` CLI flags, environment variables, filesystem paths, and SDK helper options of the pre-built workers that drive a `self_hosted` environment.
135See [Self-hosted worker reference](https://platform.claude.com/docs/en/managed-agents/self-hosted-sandboxes-reference) for the prebuilt workers that drive a `self_hosted` environment. It covers their `ant beta:worker` CLI flags, environment variables, filesystem paths, and SDK helper options.
136136
137137## Supported MCP server types
138138
139Claude Managed Agents connects to [remote MCP servers](https://platform.claude.com/docs/en/agents-and-tools/remote-mcp-servers) that expose an HTTP endpoint, or to private MCP servers through [MCP tunnels](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/overview). The server should support the MCP protocol’s streamable HTTP transport; servers that only support the deprecated SSE transport still work through an automatic fallback. See [MCP connector](https://platform.claude.com/docs/en/managed-agents/mcp-connector) for declaring servers on an agent.
139Claude Managed Agents connects to [remote MCP servers](https://platform.claude.com/docs/en/agents-and-tools/remote-mcp-servers) that expose an HTTP endpoint, or to private MCP servers through [MCP tunnels](https://platform.claude.com/docs/en/agents-and-tools/mcp-tunnels/overview). The server should support MCP’s streamable HTTP transport; servers that only support the deprecated SSE transport still work through an automatic fallback. See [MCP connector](https://platform.claude.com/docs/en/managed-agents/mcp-connector) for declaring servers on an agent.
140140
141141For more information on MCP and building MCP servers, see the [MCP documentation](https://modelcontextprotocol.io).
142142
from line 153
153153
154154## Branding guidelines
155155
156For partners integrating Claude Managed Agents, use of Claude branding is optional. When referencing Claude in your product:
156For partners integrating Claude Managed Agents, use of Claude branding is optional. When you reference Claude in your product, follow these rules:
157157
158158**Allowed:**
159159
from line 161
161161* “Claude” (when within a menu already labeled “Agents”)
162162* “\{YourAgentName} Powered by Claude” (if you have an existing agent name)
163163
164**Not permitted:**
164**Not allowed:**
165165
166166* “Claude Code” or “Claude Code Agent”
167167* “Claude Cowork” or “Claude Cowork Agent”
managed-agents/secure-deployment Changed · +17 / -17 lines
from line 39
3939
4040This guide lists the settings that limit what an agent on Claude Managed Agents can reach and do, most important first. Each section links to the page that covers the setting in full.
4141
42| Section | Setting or decision | Recommended |
43| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
44| [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 |
45| [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 |
46| [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 |
47| [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 |
48| [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 |
49| [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 |
50| [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 |
51| [Keep untrusted input away from powerful tools](https://platform.claude.com/docs/en/managed-agents/secure-deployment#keep-untrusted-input-away-from-powerful-tools) | Which tools and credentials an agent holds when it reads untrusted input | No agent that reads untrusted input has a tool on `always_allow` that writes files, runs commands, or changes records |
52| [Set limits and a way to stop](https://platform.claude.com/docs/en/managed-agents/secure-deployment#set-limits-and-a-way-to-stop) | `budget` on each session and deployment | A cap sized to what you expect a run to cost |
53| [Optionally have an offline reviewer read every transcript](https://platform.claude.com/docs/en/managed-agents/secure-deployment-monitoring#optionally-have-an-offline-reviewer-read-every-transcript) | An offline review job you run that reads each session’s events | Optional. A review of each session that went idle or terminated, on a schedule |
54| [Monitor sessions and review retention](https://platform.claude.com/docs/en/managed-agents/secure-deployment-monitoring#monitor-sessions-and-review-retention) | Webhooks and session deletion | An alert when a session goes idle, reaches its budget, or terminates, and a check of why it went idle. Store the events you want to keep in your own logs, and delete sessions you no longer need |
42| Section | Setting or decision | Recommended |
43| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
44| [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 |
45| [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 |
46| [Keep credentials in vaults](https://platform.claude.com/docs/en/managed-agents/secure-deployment#keep-credentials-in-vaults) | `injection_location` (java, php: `injectionLocation`; csharp, go: `InjectionLocation`) and `networking` (csharp, go: `Networking`) on each environment variable credential | Request headers only, and `limited` networking with only the hosts the key is for |
47| [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 |
48| [Restrict web search and web fetch](https://platform.claude.com/docs/en/managed-agents/secure-deployment#restrict-web-search-and-web-fetch) | `allowed_domains` (java, php: `allowedDomains`; csharp, go: `AllowedDomains`) 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 |
49| [Approve risky actions](https://platform.claude.com/docs/en/managed-agents/secure-deployment#approve-risky-actions) | `permission_policy` (java, php: `permissionPolicy`; csharp, go: `PermissionPolicy`) 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 |
50| [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` (java, php: `defaultConfig.enabled`; csharp, go: `DefaultConfig.Enabled`) on the agent toolset | `false`, then enable the tools the agent needs |
51| [Keep untrusted input away from powerful tools](https://platform.claude.com/docs/en/managed-agents/secure-deployment#keep-untrusted-input-away-from-powerful-tools) | Which tools and credentials an agent holds when it reads untrusted input | No agent that reads untrusted input has a tool on `always_allow` that writes files, runs commands, or changes records |
52| [Set limits and a way to stop](https://platform.claude.com/docs/en/managed-agents/secure-deployment#set-limits-and-a-way-to-stop) | `budget` (csharp, go: `Budget`) on each session and deployment | A cap sized to what you expect a run to cost |
53| [Optionally have an offline reviewer read every transcript](https://platform.claude.com/docs/en/managed-agents/secure-deployment-monitoring#optionally-have-an-offline-reviewer-read-every-transcript) | An offline review job you run that reads each session’s events | Optional. A review of each session that went idle or terminated, on a schedule |
54| [Monitor sessions and review retention](https://platform.claude.com/docs/en/managed-agents/secure-deployment-monitoring#monitor-sessions-and-review-retention) | Webhooks and session deletion | An alert when a session goes idle, reaches its budget, or terminates, and a check of why it went idle. Store the events you want to keep in your own logs, and delete sessions you no longer need |
5555
5656[Security risks and sandbox boundaries](https://platform.claude.com/docs/en/managed-agents/secure-deployment-risks) explains why these settings matter and what they do not protect against. To review and monitor sessions, see [Review and monitor agent sessions](https://platform.claude.com/docs/en/managed-agents/secure-deployment-monitoring).
5757
from line 238
238238Leave `allow_mcp_servers` (java: `allowMcpServers`; php: `allowMCPServers`; csharp: `AllowMcpServers`; go: `AllowMCPServers`) off, which is the default, and list the host of each MCP server you operate or trust in `allowed_hosts` (java, php: `allowedHosts`; csharp, go: `AllowedHosts`). Each host you list is also open to code in the sandbox. With `allow_mcp_servers` (java: `allowMcpServers`; php: `allowMCPServers`; csharp: `AllowMcpServers`; go: `AllowMCPServers`) off, a check at session creation rejects the request if an MCP server’s host is not listed. See [Provide authentication at session creation](https://platform.claude.com/docs/en/managed-agents/mcp-connector#provide-authentication-at-session-creation). The same check runs when a session update changes `mcp_servers` (java, php: `mcpServers`; csharp: `McpServers`; go: `MCPServers`).
239239
240240<Warning>
241 Network access is granted by host, not by operation. The sandbox can send any request to an allowed host, including uploads such as `git push` and package publishing. It can also use any credential the command supplies, even one that someone hid in text the agent reads.
241 The environment grants network access by host, not by operation. The sandbox can send any request to an allowed host, including uploads such as `git push` and package publishing. It can also use any credential the command supplies, even one that someone hid in text the agent reads.
242242</Warning>
243243
244244When you choose hosts for `allowed_hosts` (java, php: `allowedHosts`; csharp, go: `AllowedHosts`), follow these two rules:
from line 326
326326
327327## Approve risky actions
328328
329Set `auto` on `bash`, `write`, `edit`, and `web_fetch`, and on MCP tools that only read data. Use `always_ask` instead on a tool if you cannot undo its changes outside the sandbox. Also use it on a tool that should not run just because end-user text you relay asks for it. A [permission policy](https://platform.claude.com/docs/en/managed-agents/permission-policies) determines whether a tool call runs, waits for your approval, or is evaluated by the server.
329Set `auto` on `bash`, `write`, `edit`, `web_fetch`, and MCP tools that only read data. Use `always_ask` instead on a tool if you cannot undo its changes outside the sandbox. Also use it on a tool if end-user text that you relay should not be enough to make the tool run. A [permission policy](https://platform.claude.com/docs/en/managed-agents/permission-policies) determines whether the server allows a tool call, holds it for your approval, or evaluates it.
330330
331331| Tool | Recommended policy | Why |
332332| ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
from line 822
822822
823823* **Split reading from acting.** In one multiagent session, a [lead agent](https://platform.claude.com/docs/en/managed-agents/multiagent-orchestration#list-the-subagents) gives tasks to a fetcher, which reads the web, and a writer, which changes files or records.
824824* **Give the agent one narrow custom tool.** Your application runs the tool, checks its input, and holds the credential. The support agent uses this design, not the split. See [Answer tool calls that pause the session](https://platform.claude.com/docs/en/managed-agents/events-and-streaming#answer-tool-calls-that-pause-the-session).
825* **Keep a person in the loop.** Use `always_ask` on the powerful tool so a person approves each call.
825* **Require a person’s approval.** Use `always_ask` on the powerful tool so a person approves each call.
826826
827827The split uses three agents:
828828
from line 832
832832| Fetcher | Webpages and search results | `web_fetch` and `web_search` only, each with `allowed_domains` (java, php: `allowedDomains`; csharp, go: `AllowedDomains`) | Short results, in a format you ask for in its system prompt |
833833| Writer | The task from the lead | The tools that write files, run commands, or change records, on `auto` or `always_ask`. No web tools | Its result |
834834
835The fetcher’s results are built from untrusted pages, and the lead can pass their text on to the writer. Keep `auto` or `always_ask` on the writer’s tools. The fetcher can still send some of what it reads to the sites on its `web_fetch` list, and to the search provider in its queries.
835The fetcher builds its results from untrusted pages, and the lead can pass their text on to the writer. Keep `auto` or `always_ask` on the writer’s tools. The fetcher can still send some of what it reads to the sites on its `web_fetch` list, and to the search provider in its queries.
836836
837837Agents in one multiagent session [share the sandbox](https://platform.claude.com/docs/en/managed-agents/multiagent-orchestration#how-it-works), its files, and the vault credentials, so this split separates only their tools and conversations. For a stronger split, use two sessions with separate environments and vaults. Have your application pass only fixed fields, such as an order ID, between the two sessions.
838838
managed-agents/secure-deployment-monitoring Changed · +5 / -5 lines
from line 41
4141
4242## Optionally have an offline reviewer read every transcript
4343
44An offline reviewer is a job you run, separate from the sessions it reviews, that reads each session’s events after they are written. Long sessions have too many events for a person to read, so the job has Claude read them. The review flags behavior beyond what the agent was granted. For a review prompt, setup steps, and working code, see the [security review recipe](https://platform.claude.com/cookbook/managed-agents-cma-agent-security-review) in the Claude Cookbook.
44An offline reviewer is a job you run, separate from the sessions it reviews, that reads each session’s events after they are written. Long sessions have too many events for a person to read, so the job has Claude read them. The review flags behavior beyond what you granted the agent. For a review prompt, setup steps, and working code, see the [security review recipe](https://platform.claude.com/cookbook/managed-agents-cma-agent-security-review) in the Claude Cookbook.
4545
4646## Monitor sessions and review retention
4747
from line 53
5353| Sessions that reach a budget or terminate | The `session.budget_reached` and `session.status_terminated` webhooks |
5454| Scheduled runs that fail to start a session | The `deployment_run.failed` and `deployment.paused` webhooks |
5555| MCP OAuth credentials that cannot refresh | The `vault_credential.refresh_failed` webhook |
56| Tool calls the server denied or paused | `evaluated_permission` on `agent.tool_use` and `agent.mcp_tool_use` events. In a multiagent session, also list each thread’s events |
56| Tool calls the server denied or paused | `evaluated_permission` (java, php: `evaluatedPermission`; csharp, go: `EvaluatedPermission`) on `agent.tool_use` and `agent.mcp_tool_use` events. In a multiagent session, also list each thread’s events |
5757| What an agent did in a session | The Claude Console session viewer |
58| Behavior beyond what the agent was granted | An optional offline review job you run that reads each session’s events. See [Optionally have an offline reviewer read every transcript](https://platform.claude.com/docs/en/managed-agents/secure-deployment-monitoring#optionally-have-an-offline-reviewer-read-every-transcript) |
58| Behavior beyond what you granted the agent | An optional offline review job you run that reads each session’s events. See [Optionally have an offline reviewer read every transcript](https://platform.claude.com/docs/en/managed-agents/secure-deployment-monitoring#optionally-have-an-offline-reviewer-read-every-transcript) |
5959
60To see why a session went idle, list its events with `types` set to `session.status_idle`, `order` set to `desc`, and `limit` set to `1`. The event is named `session.status_idle`, and the webhook is named `session.status_idled`. If `stop_reason.type` is `requires_action`, the session is waiting on you, and `stop_reason.event_ids` lists the events it is waiting on. To answer them, see [Answer tool calls that pause the session](https://platform.claude.com/docs/en/managed-agents/events-and-streaming#answer-tool-calls-that-pause-the-session). In a self-hosted sandbox, an `agent.tool_use` event can be waiting for your sandbox to return the tool’s result. With workflow runs open, a tool call can wait for your answer while the session stays `running`. Answer each call when its event arrives. See [While a run is open](https://platform.claude.com/docs/en/managed-agents/workflow-runs#while-a-run-is-open).
60To see why a session went idle, list its events with `types` (curl: `types[]`; cli: `--type`; csharp, go: `Types`) set to `session.status_idle`, `order` (csharp, go: `Order`) set to `desc`, and `limit` (csharp, go: `Limit`) set to `1`. The event is named `session.status_idle`, and the webhook is named `session.status_idled`. If `stop_reason.type` is `requires_action`, the session is waiting on you, and `stop_reason.event_ids` lists the events it is waiting on. To answer them, see [Answer tool calls that pause the session](https://platform.claude.com/docs/en/managed-agents/events-and-streaming#answer-tool-calls-that-pause-the-session). In a self-hosted sandbox, an `agent.tool_use` event can be waiting for your sandbox to return the tool’s result. With workflow runs open, a tool call can wait for your answer while the session stays `running`. Answer each call when its event arrives. See [While a run is open](https://platform.claude.com/docs/en/managed-agents/workflow-runs#while-a-run-is-open).
6161
62A webhook delivery can be missed, so also list your sessions on a schedule and check the idle ones.
62You can miss a webhook delivery, so also list your sessions on a schedule and check the idle ones.
6363
6464See [Subscribe to webhooks](https://platform.claude.com/docs/en/managed-agents/webhooks) and [Inspect sessions and track usage](https://platform.claude.com/docs/en/managed-agents/session-observability#inspect-a-session-in-the-console).
6565
managed-agents/secure-deployment-risks Changed · +10 / -10 lines
from line 49
4949| ---------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
5050| Untrusted input steers the agent | A ticket tells the agent to cancel every open order | [Smallest tool set](https://platform.claude.com/docs/en/managed-agents/secure-deployment#give-the-agent-the-smallest-tool-set), [untrusted input kept away from powerful tools](https://platform.claude.com/docs/en/managed-agents/secure-deployment#keep-untrusted-input-away-from-powerful-tools), [approvals for risky actions](https://platform.claude.com/docs/en/managed-agents/secure-deployment#approve-risky-actions) |
5151| Code in the sandbox can use a credential | A script the agent was tricked into running sends the agent’s key to an outside host, or uses it to read every customer’s orders | [Credentials in vaults](https://platform.claude.com/docs/en/managed-agents/secure-deployment#keep-credentials-in-vaults), [limited networking](https://platform.claude.com/docs/en/managed-agents/secure-deployment#limit-the-network), [approvals for risky actions](https://platform.claude.com/docs/en/managed-agents/secure-deployment#approve-risky-actions) |
52| An open network lets data out | A bash command posts a file to an outside host | [Limited networking](https://platform.claude.com/docs/en/managed-agents/secure-deployment#limit-the-network), the [`web_fetch` domain list](https://platform.claude.com/docs/en/managed-agents/secure-deployment#restrict-web-search-and-web-fetch) |
52| An open network lets data out | A `bash` command posts a file to an outside host | [Limited networking](https://platform.claude.com/docs/en/managed-agents/secure-deployment#limit-the-network), the [`web_fetch` domain list](https://platform.claude.com/docs/en/managed-agents/secure-deployment#restrict-web-search-and-web-fetch) |
5353| Claude takes a step you did not expect | To get past an obstacle, it uses a tool or credential it can reach | The settings in [Secure your Managed Agents deployment](https://platform.claude.com/docs/en/managed-agents/secure-deployment). An [offline reviewer](https://platform.claude.com/docs/en/managed-agents/secure-deployment-monitoring#optionally-have-an-offline-reviewer-read-every-transcript) can flag the step afterward |
5454
5555These settings lower the risk but do not remove it, so do not put data in the sandbox that must never leave it. An agent can still put data it is allowed to read into its own reply or tool output. Limit a key’s permissions at the service that issued it, because these settings do not limit them. The settings do not secure your custom tools, your MCP servers, or your self-hosted infrastructure.
from line 58
5858
5959Managed Agents keeps the agent loop, session history, and vault secrets outside the sandbox by design. For the design background, see [Scaling Managed Agents](https://www.anthropic.com/engineering/managed-agents).
6060
61| Part | Where it runs | What limits it |
62| ---------------------------- | -------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
63| Agent loop | Anthropic’s servers | The tool set, permission policies, and budget that you set |
64| `bash` and file tools | The sandbox. In a cloud environment, each session gets its own isolated Linux container | Environment networking, the tool set, and permission policies |
65| `web_search` and `web_fetch` | Anthropic’s servers | The tool’s own domain list, your organization’s web search and web fetch settings in the Claude Console, and, in a `limited` cloud environment, the environment’s allowed hosts. `web_fetch` also opens only URLs that have already appeared in the session |
66| Vault secret | Outside the sandbox. MCP credentials never enter it. For an environment variable credential, code sees a placeholder | For an MCP credential, the MCP server URL it is for. For an environment variable credential, the hosts the credential allows, its injection location, and the environment’s allowed hosts |
67| Session history | Anthropic’s servers, until you delete the session | The API keys for the workspace, the Developer and Admin roles in the Claude Console, and session deletion |
68| Custom tools | Your application | Your code |
61| Part | Where it runs | What limits it |
62| ---------------------------- | -------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
63| Agent loop | Anthropic’s servers | The tool set, permission policies, and budget that you set |
64| `bash` and file tools | The sandbox. In a cloud environment, each session gets its own isolated Linux container | Environment networking, the tool set, and permission policies |
65| `web_search` and `web_fetch` | Anthropic’s servers | The tool’s own domain list and your organization’s web search and web fetch settings in the Claude Console. In a `limited` cloud environment, the environment’s allowed hosts limit them too. `web_fetch` also opens only URLs that have already appeared in the session |
66| Vault secret | Outside the sandbox. MCP credentials never enter it. For an environment variable credential, code sees a placeholder | For an MCP credential, the MCP server URL it is for. For an environment variable credential, the hosts the credential allows, its injection location, and the environment’s allowed hosts |
67| Session history | Anthropic’s servers, until you delete the session | The API keys for the workspace, the Developer and Admin roles in the Claude Console, and session deletion |
68| Custom tools | Your application | Your code |
6969
70In a cloud environment, sessions do not share filesystem state. A memory store attached to more than one session is shared between them.
70In a cloud environment, sessions do not share filesystem state. Sessions that attach the same memory store share it.
7171
7272These limits do not replace each other. For example, limiting the environment’s hosts does not stop the agent from using a credential on a host you allowed.
7373
managed-agents/self-hosted-sandboxes-custom-tools Changed · +3 / -3 lines
from line 42
4242The environment key authorizes posting custom tool results, so your Claude API key stays off the worker host.
4343
4444<Note>
45 Serving custom tools requires the SDK worker. The `ant` CLI worker has no way to register a custom tool implementation. In the sandbox-per-session pattern, [run the SDK worker inside the sandbox](https://platform.claude.com/docs/en/managed-agents/self-hosted-sandboxes-workers#run-the-sdk-worker-inside-the-sandbox).
45 To serve custom tools, you need the SDK worker. The `ant` CLI worker has no way to register a custom tool implementation. In the sandbox-per-session pattern, [run the SDK worker inside the sandbox](https://platform.claude.com/docs/en/managed-agents/self-hosted-sandboxes-workers#run-the-sdk-worker-inside-the-sandbox).
4646</Note>
4747
4848## Serve a custom tool
from line 216
216216 </Step>
217217</Steps>
218218
219The worker answers only the tools registered with it. If a tool is declared on the agent but no worker or client serves it, the session pauses with a `requires_action` stop reason. It stays paused until something posts the result. See [Answer tool calls that pause the session](https://platform.claude.com/docs/en/managed-agents/events-and-streaming#answer-tool-calls-that-pause-the-session) for the event flow.
219The worker answers only the tools registered with it. If you declare a tool on the agent but no worker or client serves it, the session pauses with a `requires_action` stop reason. It stays paused until something posts the result. See [Answer tool calls that pause the session](https://platform.claude.com/docs/en/managed-agents/events-and-streaming#answer-tool-calls-that-pause-the-session) for the event flow.
220220
221221## Wrap an MCP server as custom tools
222222
from line 856
856856
857857| Field | Rule |
858858| ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
859| `name` | Unique per agent. Letters, digits, underscores, and hyphens, 1–128 characters. Cannot match a built-in agent tool such as `bash` or `read`, or use the reserved `mcp__` prefix or `ant__` prefix. |
859| `name` | Unique within the agent. Letters, digits, underscores, and hyphens, 1–128 characters. Cannot match a built-in agent tool such as `bash` or `read`, or use the reserved `mcp__` or `ant__` prefix. |
860860| `description` | Required and non-empty. |
861861| `input_schema` | Accepts the JSON Schema keywords MCP servers commonly emit, such as `additionalProperties` and `title`. Rejects reference keywords such as `$ref` anywhere, and top-level `oneOf`, `anyOf`, and `allOf`. Property names use letters, digits, underscores, dots, and hyphens, 1–64 characters. |
862862| The agent’s `tools` array | At most 256 entries. Each wrapped tool is one entry, and the built-in toolset is one more. |
managed-agents/self-hosted-sandboxes-memory Changed · +2 / -4 lines
from line 44
4444## Requirements
4545
4646* **A worker that mounts memory stores:** Use `ant` CLI 1.33.0 or later, or `EnvironmentWorker` from the Python, TypeScript, or Go SDK.
47* **A POSIX filesystem:** Windows hosts are not supported, because the worker requires `O_NOFOLLOW` when it opens memory files. A case-sensitive filesystem is recommended, so that memory paths that differ only in case do not collide. macOS volumes are case-insensitive by default, so such paths collide there.
47* **A POSIX filesystem:** Windows hosts are not supported, because the worker requires `O_NOFOLLOW` when it opens memory files. Anthropic recommends a case-sensitive filesystem, so that memory paths that differ only in case do not collide. macOS volumes are case-insensitive by default, so such paths collide there.
4848* **A writable `/mnt/memory` directory:** See [Prepare the host](https://platform.claude.com/docs/en/managed-agents/self-hosted-sandboxes-memory#prepare-the-host). On macOS, see [Prepare a macOS host](https://platform.claude.com/docs/en/managed-agents/self-hosted-sandboxes-memory#prepare-a-macos-host).
4949* **The work item’s secret:** If your own code launches the worker, [forward the work item’s secret](https://platform.claude.com/docs/en/managed-agents/self-hosted-sandboxes-workers#forward-the-work-items-secret) to it.
5050
5151<Note>
52 Memory stores cannot be attached to sessions on self-hosted environments on [Claude Platform on AWS](https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws).
53
54 On [Claude Models on Google Cloud (Anthropic managed)](https://platform.claude.com/docs/en/build-with-claude/claude-models-on-google-cloud/anthropic-managed), memory stores aren’t supported for sessions on self-hosted environments.
52 Memory stores are not available for sessions on self-hosted environments on [Claude Models on Google Cloud (Anthropic managed)](https://platform.claude.com/docs/en/build-with-claude/claude-models-on-google-cloud/anthropic-managed) or [Claude Platform on AWS](https://platform.claude.com/docs/en/build-with-claude/claude-platform-on-aws).
5553</Note>
5654
5755## Prepare the host
managed-agents/self-hosted-sandboxes-reference Changed · +15 / -15 lines
from line 37
3737 Claude Models on Google Cloud (Anthropic managed): beta
3838---
3939
40This page documents the pre-built workers that serve a `self_hosted` environment. For task-oriented guides, start with [Self-hosted sandboxes](https://platform.claude.com/docs/en/managed-agents/self-hosted-sandboxes) and [Deploy self-hosted workers](https://platform.claude.com/docs/en/managed-agents/self-hosted-sandboxes-workers).
40This page documents the prebuilt workers that serve a `self_hosted` environment. For task-oriented guides, start with [Self-hosted sandboxes](https://platform.claude.com/docs/en/managed-agents/self-hosted-sandboxes) and [Deploy self-hosted workers](https://platform.claude.com/docs/en/managed-agents/self-hosted-sandboxes-workers).
4141
4242## CLI commands and flags
4343
from line 50
5050| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
5151| `--environment-id` | The environment to poll for work. Also reads from `ANTHROPIC_ENVIRONMENT_ID`. |
5252| `--environment-key` | Authenticates the worker with this environment. Also reads from `ANTHROPIC_ENVIRONMENT_KEY`. |
53| `--workdir` | Directory where skills are downloaded and tools read and write files. Defaults to `.` (the current directory). |
54| `--on-work` | Script to call for each claimed work item instead of running tools in-process. Receives session details as environment variables and the work item as JSON on standard input. |
53| `--workdir` | Directory where the worker downloads skills, and where tools read and write files. Defaults to `.` (the current directory). |
54| `--on-work` | Script to call for each claimed work item instead of running tools in process. Receives session details as environment variables and the work item as JSON on standard input. |
5555| `--max-idle` | How long the worker waits while a session is idle before `ant beta:worker run` exits or `ant beta:worker poll` moves on to the next work item. Idle time with a [`requires_action` stop reason](https://platform.claude.com/docs/en/managed-agents/events-and-streaming#respond-when-the-session-goes-idle) does not count. Defaults to `60s`. Set it to `0` to turn off the timeout. With an `--on-work` script, `ant beta:worker poll` ignores this flag. Pass it instead to the `ant beta:worker run` command that your script starts. |
5656| `--log-format` | Log output format. Use `json` for structured log ingestion. Defaults to `text`. |
5757
from line 63
6363| `ANTHROPIC_ENVIRONMENT_KEY` | Authenticates the worker to its queue. | You, on the worker host. The poller passes it to the `--on-work` script. |
6464| `ANTHROPIC_SESSION_ID` | The session that a claimed work item represents. | The poller, for the `--on-work` script. |
6565| `ANTHROPIC_WORK_ID` | The claimed work item. | The poller, for the `--on-work` script. |
66| `ANTHROPIC_WORK_SECRET` | The work item’s per-session secret. | You. The poller does not set it. See [Forward the work item’s secret](https://platform.claude.com/docs/en/managed-agents/self-hosted-sandboxes-workers#forward-the-work-items-secret). |
66| `ANTHROPIC_WORK_SECRET` | The work item’s secret for its session. | You. The poller does not set it. See [Forward the work item’s secret](https://platform.claude.com/docs/en/managed-agents/self-hosted-sandboxes-workers#forward-the-work-items-secret). |
6767| `ANTHROPIC_BASE_URL` | Overrides the default API endpoint. Optional. | You, on the worker host. |
6868| `ANTHROPIC_WEBHOOK_SIGNING_KEY` | Verifies incoming webhook payloads. | You, on a webhook handler host. |
6969
7070## Host requirements
7171
72| Worker | Requirement |
73| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
74| All workers | A Linux or macOS host with `/bin/bash` at that exact path. The worker’s bash tool invokes it directly, without consulting `PATH`. On macOS, that is the system Bash 3.2. |
75| TypeScript SDK | `unzip` and `tar` on the `PATH`, and Node.js 22 or later. |
76| Python and Go SDKs | No additional binaries. These SDKs use their standard libraries for archive extraction. |
72| Worker | Requirement |
73| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
74| All workers | A Linux or macOS host with `/bin/bash` at that exact path. The worker’s `bash` tool runs it directly, without consulting `PATH`. On macOS, that is the system Bash 3.2. |
75| TypeScript SDK | `unzip` and `tar` on the `PATH`, and Node.js 22 or later. |
76| Python and Go SDKs | No additional binaries. These SDKs use their standard libraries for archive extraction. |
7777
7878[Memory stores](https://platform.claude.com/docs/en/managed-agents/self-hosted-sandboxes-memory#requirements) add their own requirements.
7979
from line 83
8383
8484| Path | Contents |
8585| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
86| `/workspace` | The system default working directory for tool execution and skill download. If you use a different working directory, update your agent’s system prompt so Claude can locate the skill files. |
86| `/workspace` | The system default working directory for running tools and downloading skills. If you use a different working directory, update your agent’s system prompt so Claude can locate the skill files. |
8787| `<workdir>/skills/<name>/` | The agent’s downloaded skills. |
8888| `/mnt/memory/<store>/` | One directory per attached memory store, at the store’s `mount_path` (java, php: `mountPath`; csharp, go: `MountPath`) (for example, `/mnt/memory/user-preferences/`). The worker creates these directories when it claims the session and removes them when the session ends. |
8989
from line 97
9797
9898| Helper | What it does | Use it when |
9999| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
100| [`EnvironmentWorker`](https://platform.claude.com/docs/en/managed-agents/self-hosted-sandboxes-reference#environment-worker) | Handles polling, setup, and execution end to end. | Most cases. |
101| [`work.poller()` (go: `environments.NewWorkPoller()`)](https://platform.claude.com/docs/en/managed-agents/self-hosted-sandboxes-reference#work-poller) | Polls the work queue and gives you each claimed session. | You determine what happens for each session, for example launching a sandbox rather than running tools in-process. |
102| [`client.beta.sessions.events.tool_runner()` (typescript: `client.beta.sessions.events.toolRunner()`; go: `client.Beta.Sessions.Events.NewToolRunner()`)](https://platform.claude.com/docs/en/managed-agents/self-hosted-sandboxes-reference#session-tool-runner) | Runs tool calls for a single session, given the session ID and a tool list. | You’ve already claimed the work and only need the execution layer. |
100| [`EnvironmentWorker`](https://platform.claude.com/docs/en/managed-agents/self-hosted-sandboxes-reference#environment-worker) | Handles polling, setup, and tool runs end to end. | Most cases. |
101| [`work.poller()` (go: `environments.NewWorkPoller()`)](https://platform.claude.com/docs/en/managed-agents/self-hosted-sandboxes-reference#work-poller) | Polls the work queue and gives you each claimed session. | You determine how to handle each session, for example by launching a sandbox rather than running tools in process. |
102| [`client.beta.sessions.events.tool_runner()` (typescript: `client.beta.sessions.events.toolRunner()`; go: `client.Beta.Sessions.Events.NewToolRunner()`)](https://platform.claude.com/docs/en/managed-agents/self-hosted-sandboxes-reference#session-tool-runner) | Runs tool calls for a single session, given the session ID and a tool list. | You’ve already claimed the work and only need to run the tools. |
103103
104104### EnvironmentWorker
105105
from line 162
162162| Option | Description |
163163| ------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
164164| `drain` (go: `Drain`) | Whether to stop polling once the queue is empty rather than waiting for new work. |
165| `block_ms` (typescript: `blockMs`; go: `BlockMs`) | How long each poll waits for work to arrive before returning, in milliseconds. Must be between 1 and 999; the helper re-polls automatically. Pass `null` (python: `None`; go: `param.Null[int64]()`) for a non-blocking check. Defaults to a 999ms long-poll. |
166| `reclaim_older_than_ms` (typescript: `reclaimOlderThanMs`; go: `ReclaimOlderThanMs`) | Re-claims work items that were claimed but never acknowledged within this many milliseconds. |
165| `block_ms` (typescript: `blockMs`; go: `BlockMs`) | How long each poll waits for work to arrive before returning, in milliseconds. Must be between 1 and 999. The helper polls again automatically. Pass `null` (python: `None`; go: `param.Null[int64]()`) for a non-blocking check. Defaults to a 999ms long-poll. |
166| `reclaim_older_than_ms` (typescript: `reclaimOlderThanMs`; go: `ReclaimOlderThanMs`) | Reclaims work items that were claimed but never acknowledged within this many milliseconds. |
167167| `auto_stop` (typescript: `autoStop`; go: `AutoStop`) | Whether to post a stop signal for each work item once your loop body finishes with it. Set it to `false` (python: `False`; go: `param.NewOpt(false)`) when whatever runs the work item posts the stop itself. `handle_item()` (typescript: `handleItem()`; go: `HandleItem()`) does, and so does a sandbox you launch that owns the stop call. |
168168
169169For a complete example, see [Launch sandboxes from the SDK poller](https://platform.claude.com/docs/en/managed-agents/self-hosted-sandboxes-workers#launch-sandboxes-from-the-sdk-poller).
managed-agents/session-threads Changed · +5 / -5 lines
from line 50
5050A [session budget](https://platform.claude.com/docs/en/managed-agents/budgets) is a single shared cap across all of a session’s threads. As the cap is reached, threads pause independently, and each thread’s cost is priced at the thread’s own served model.
5151
5252<Note>
53 A session can have at most 25 child threads at a time. Idle threads count until you archive them, and the primary thread doesn’t count. The primary thread’s agent can call multiple copies of a single subagent, creating multiple threads associated with one `agent`. [Advisor](https://platform.claude.com/docs/en/managed-agents/multiagent-orchestration#give-the-session-an-advisor) consultation threads are exempt from this limit. So are a [workflow run](https://platform.claude.com/docs/en/managed-agents/workflow-runs)’s threads.
53 A session can have at most 25 child threads at a time. Idle threads count until you archive them, and the primary thread doesn’t count. The primary thread’s agent can call multiple copies of a single subagent, creating multiple threads associated with one `agent`. [Advisor consultation threads](https://platform.claude.com/docs/en/managed-agents/multiagent-orchestration#give-the-session-an-advisor) are exempt from this limit. So are a [workflow run](https://platform.claude.com/docs/en/managed-agents/workflow-runs)’s threads.
5454</Note>
5555
5656## List threads
from line 283
283283 ```
284284</CodeGroup>
285285
286Archive only succeeds if the thread is `idle`. A thread parked on `requires_action` counts as idle, so you can archive it directly. To archive a running thread, interrupt it first:
286Archiving succeeds only if the thread is `idle`. A thread that waits on `requires_action` counts as idle, so you can archive it directly. To archive a running thread, interrupt it first:
287287
288288<CodeGroup>
289289 ```bash cURL
from line 408
408408| `session.thread_created` | A thread was created. Includes `session_thread_id` (java: `sessionThreadId`; php: `sessionThreadID`; csharp, go: `SessionThreadID`) and `agent_name` (java, php: `agentName`; csharp, go: `AgentName`). |
409409| `session.thread_status_running` | A thread started activity. |
410410| `session.thread_status_idle` | The agent associated with the thread is awaiting input. Includes a `stop_reason` (java, php: `stopReason`; csharp, go: `StopReason`) indicating why the agent stopped. |
411| `session.thread_status_terminated` | A thread terminated and accepts no further input, for example because it was archived or encountered an unrecoverable error. An advisor thread also terminates when its consultation ends. |
411| `session.thread_status_terminated` | A thread terminated and accepts no further input, for example, because it was archived or encountered an unrecoverable error. An advisor thread also terminates when its consultation ends. |
412412| `agent.thread_message_received` | On the primary thread, a subagent sent the primary thread’s agent a report or question. Includes `from_session_thread_id` (java: `fromSessionThreadId`; php: `fromSessionThreadID`; csharp, go: `FromSessionThreadID`), `from_agent_name` (java, php: `fromAgentName`; csharp, go: `FromAgentName`), and `content` (csharp, go: `Content`). |
413413| `agent.thread_message_sent` | On the primary thread, the primary thread’s agent sent a subagent a task or follow-up message. Includes `to_session_thread_id` (java: `toSessionThreadId`; php: `toSessionThreadID`; csharp, go: `ToSessionThreadID`), `to_agent_name` (java, php: `toAgentName`; csharp, go: `ToAgentName`), and `content` (csharp, go: `Content`). |
414414
415Advisor consultations emit these same thread events under the reserved name `anthropic.advisor` (as `agent_name` (java, php: `agentName`; csharp, go: `AgentName`) on the thread lifecycle events and `from_agent_name` (java, php: `fromAgentName`; csharp, go: `FromAgentName`) on the advice delivery); see [Give the session an advisor](https://platform.claude.com/docs/en/managed-agents/multiagent-orchestration#give-the-session-an-advisor) for the sequence.
415Advisor consultations emit these same thread events under the reserved name `anthropic.advisor`. The name appears as `agent_name` (java, php: `agentName`; csharp, go: `AgentName`) on the thread lifecycle events and as `from_agent_name` (java, php: `fromAgentName`; csharp, go: `FromAgentName`) on the advice delivery. See [Give the session an advisor](https://platform.claude.com/docs/en/managed-agents/multiagent-orchestration#give-the-session-an-advisor) for the sequence.
416416
417417A [workflow run](https://platform.claude.com/docs/en/managed-agents/workflow-runs)’s threads show on the primary stream as follows:
418418
from line 419
419419* **Lifecycle events:** Each run thread sends `session.thread_created`, with the run’s `workflow_run_id` (java: `workflowRunId`; php: `workflowRunID`; csharp, go: `WorkflowRunID`), and its `session.thread_status_running`, `session.thread_status_idle`, and `session.thread_status_terminated` events.
420420* **Message events:** A run thread’s prompt, an `agent.thread_message_received` event, stays on its own stream.
421421* **Run events:** `workflow_run.*` events also arrive on this stream; see [Run events](https://platform.claude.com/docs/en/managed-agents/workflow-runs#run-events).
422* **Tool calls that wait on you:** A run thread’s tool calls that need your client are cross-posted to this stream, as for any child thread. See [Tool permissions and custom tools](https://platform.claude.com/docs/en/managed-agents/session-threads#tool-permissions-and-custom-tools).
422* **Tool calls that wait on you:** The server cross-posts a run thread’s tool calls that need your client to this stream, as for any child thread. See [Tool permissions and custom tools](https://platform.claude.com/docs/en/managed-agents/session-threads#tool-permissions-and-custom-tools).
423423
424424## Session thread events
425425
managed-agents/workflow-runs Changed · +26 / -19 lines
from line 53
5353
5454* **Workflow run:** The server runs the workflow in the background, as one workflow run. A session can have several runs open at the same time.
5555* **Phases:** A workflow can divide its work into phases. A phase is a named stage of the run, such as “Read the contracts.” You follow a run’s progress by its phase events.
56* **Agent threads:** In a phase, the program runs agents. Each agent works in its own [session thread](https://platform.claude.com/docs/en/managed-agents/session-threads), on a prompt that the program wrote. An agent in a run can be an inline agent, which the program defines itself, or a [predefined agent](https://platform.claude.com/docs/en/managed-agents/multiagent-orchestration#predefined-and-inline-agents), which you list in the `predefined_agents` (java, php: `predefinedAgents`; csharp, go: `PredefinedAgents`) list of `workflows` (csharp, go: `Workflows`). For what each thread shows, see [A run’s threads](https://platform.claude.com/docs/en/managed-agents/workflow-runs#a-runs-threads).
56* **Agent threads:** In a phase, the program runs agents. Each agent works in its own [session thread](https://platform.claude.com/docs/en/managed-agents/session-threads), on a prompt that the program wrote. An agent in a run can be an inline agent, which the program defines itself. It can also be a [predefined agent](https://platform.claude.com/docs/en/managed-agents/multiagent-orchestration#predefined-and-inline-agents), which you list in the `predefined_agents` (java, php: `predefinedAgents`; csharp, go: `PredefinedAgents`) list of `workflows` (csharp, go: `Workflows`). For what each thread shows, see [A run’s threads](https://platform.claude.com/docs/en/managed-agents/workflow-runs#a-runs-threads).
5757
5858The program can do the following:
5959
from line 65
6565
6666When the run ends, the agent that the session runs gets a turn to read what the run did. It can then answer you or start another run. [Run events](https://platform.claude.com/docs/en/managed-agents/workflow-runs#run-events) lists the cases where that turn comes later or doesn’t come.
6767
68You can guide how a run does the work, for example how it splits the work and what it does when an agent fails. See [Tell the agent when to use a run](https://platform.claude.com/docs/en/managed-agents/multiagent-orchestration#tell-the-agent-when-to-use-a-run).
68You can guide how a run does the work, for example, how it splits the work and what it does when an agent fails. See [Tell the agent when to use a run](https://platform.claude.com/docs/en/managed-agents/multiagent-orchestration#tell-the-agent-when-to-use-a-run).
6969
7070There’s no approval step before a run starts: the agent starts a run in the same turn that it writes the workflow. To review a plan first, tell the agent to describe the run and wait for your approval. As a run starts, `workflow_run.created` shows its name, description, and phases. If a run starts that you didn’t approve, ask the agent to stop it (see [Interrupt a session with runs open](https://platform.claude.com/docs/en/managed-agents/workflow-runs#interrupt-a-session-with-runs-open)).
7171
from line 75
7575 
7676</Frame>
7777
78A run starts as running or as idle. Reaching the budget, for example, pauses a running run, which makes it idle; raising or removing the budget then makes it run again, unless an interrupt paused it too. A running run ends when its workflow completes, the agent stops it, it fails, its lifetime passes, or the session is archived. An idle run can end too, for example when the agent stops it or the session is archived.
78A run starts as running or as idle. Reaching the budget, for example, pauses a running run, which makes it idle. Raising or removing the budget then makes it run again, unless an interrupt paused it too. A running run ends when its workflow completes, the agent stops it, it fails, its lifetime passes, or the session is archived. An idle run can end too, for example, when the agent stops it or the session is archived.
7979
80A run is **open** from its `workflow_run.created` event until its `workflow_run.status_ended` event, whether it’s running or idle. A run is idle while it’s paused, for example at the session’s budget. A run has a [lifetime](https://platform.claude.com/docs/en/managed-agents/workflow-runs#limits), which the agent can set when it starts the run. Time that a run spends waiting on your client counts toward that lifetime. A pause doesn’t stop a run’s lifetime from passing, so a run that stays paused can end with `timeout_error`. The following events report a run’s start, its phases, and its end. A pause at the budget sends one too. A pause after an interrupt might send none. Every `workflow_run.*` event includes `workflow_run_id` (java: `workflowRunId`; php: `workflowRunID`; csharp, go: `WorkflowRunID`), which is `null` (python: `None`; ruby: `nil`; java: `Optional.empty()`; go: `""`) only on a `workflow_run.error` when no run was created.
80A run is **open** from its `workflow_run.created` event until its `workflow_run.status_ended` event, whether it’s running or idle. A run is idle while it’s paused, for example, at the session’s budget. A run has a [lifetime limit](https://platform.claude.com/docs/en/managed-agents/workflow-runs#limits), which the agent can set when it starts the run. Time that a run spends waiting on your client counts toward that lifetime. A pause doesn’t stop a run’s lifetime from passing, so a run that stays paused can end with `timeout_error`. The following events report a run’s start, its phases, and its end. A pause at the budget sends one too. A pause after an interrupt might send none. Every `workflow_run.*` event includes `workflow_run_id` (java: `workflowRunId`; php: `workflowRunID`; csharp, go: `WorkflowRunID`), which is `null` (python: `None`; ruby: `nil`; java: `Optional.empty()`; go: `""`) only on a `workflow_run.error` when no run was created.
8181
8282## Run events
8383
84Run events arrive on the session’s event stream, which is the primary thread’s stream, and listing the session’s events returns them too. Run events don’t trigger [webhooks](https://platform.claude.com/docs/en/managed-agents/webhooks). Status events from the run’s threads arrive on the same stream. Each names its thread in `session_thread_id` (java: `sessionThreadId`; php: `sessionThreadID`; csharp, go: `SessionThreadID`), and a run’s threads are the ones whose `session.thread_created` event had the run’s `workflow_run_id` (java: `workflowRunId`; php: `workflowRunID`; csharp, go: `WorkflowRunID`).
84Run events arrive on the session’s event stream, which is the primary thread’s stream, and listing the session’s events returns them too. Run events don’t [trigger webhooks](https://platform.claude.com/docs/en/managed-agents/webhooks). Status events from the run’s threads arrive on the same stream. Each names its thread in `session_thread_id` (java: `sessionThreadId`; php: `sessionThreadID`; csharp, go: `SessionThreadID`), and a run’s threads are the ones whose `session.thread_created` event had the run’s `workflow_run_id` (java: `workflowRunId`; php: `workflowRunID`; csharp, go: `WorkflowRunID`).
8585
8686| Event | When it arrives | What to do |
8787| -------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
8888| `workflow_run.created` | The agent started a run. Includes `workflow_run_id` (java: `workflowRunId`; php: `workflowRunID`; csharp, go: `WorkflowRunID`) (`wrun_…`), the run’s `name` (csharp, go: `Name`) and `description` (csharp, go: `Description`), and `phases` (csharp, go: `Phases`), the phases the workflow declares, each with an `id` (csharp, go: `ID`), a `name` (csharp, go: `Name`), and a `description` (csharp, go: `Description`). A `description` (csharp, go: `Description`) is `null` (python: `None`; ruby: `nil`; java: `Optional.empty()`; go: `""`) when the workflow gives none. `phases` (csharp, go: `Phases`) is always present and can be empty. The run’s and phases’ `name` (csharp, go: `Name`) and `description` (csharp, go: `Description`) are text the model wrote, so they can repeat words from your request. A run’s `name` (csharp, go: `Name`) can also be one the server assigned. | Track the run as open. Show its `name` (csharp, go: `Name`), and progress against `phases` (csharp, go: `Phases`). |
8989| `workflow_run.status_running` | When the run starts its work, which can be a while after `created`, and each time it resumes after a pause at the budget. A resume after an interrupt might not send it. A run that starts idle might get `workflow_run.status_idle` first. | Show the run as running. |
90| `workflow_run.status_idle` | The run was paused, for example at the session’s budget. The event doesn’t say why. A pause after an interrupt might not send it. | To continue, see [Cost and budgets](https://platform.claude.com/docs/en/managed-agents/workflow-runs#cost-and-budgets) or [Interrupt a session with runs open](https://platform.claude.com/docs/en/managed-agents/workflow-runs#interrupt-a-session-with-runs-open). |
90| `workflow_run.status_idle` | The run paused, for example, at the session’s budget. The event doesn’t say why. A pause after an interrupt might not send it. | To continue, see [Cost and budgets](https://platform.claude.com/docs/en/managed-agents/workflow-runs#cost-and-budgets) or [Interrupt a session with runs open](https://platform.claude.com/docs/en/managed-agents/workflow-runs#interrupt-a-session-with-runs-open). |
9191| `workflow_run.phase_started`, `workflow_run.phase_ended` | The workflow entered or left a phase, or the run’s end closed a phase that was still open. The end event doesn’t say whether the phase’s work completed. Both include `workflow_run_phase_id` (java: `workflowRunPhaseId`; php: `workflowRunPhaseID`; csharp, go: `WorkflowRunPhaseID`). The end also has `phase_started_id` (java: `phaseStartedId`; php: `phaseStartedID`; csharp, go: `PhaseStartedID`), the `id` (csharp, go: `ID`) of the start event it closes. Neither has the phase’s name: look it up by `workflow_run_phase_id` (java: `workflowRunPhaseId`; php: `workflowRunPhaseID`; csharp, go: `WorkflowRunPhaseID`) in the `phases` (csharp, go: `Phases`) of `workflow_run.created`. | Update progress. Phases run one at a time, in the order of `phases` (csharp, go: `Phases`), each at most once, but the API doesn’t guarantee it. Match a phase’s end to its start by `phase_started_id` (java: `phaseStartedId`; php: `phaseStartedID`; csharp, go: `PhaseStartedID`). Handle more than one open phase, a phase that isn’t in `phases` (csharp, go: `Phases`), and a listed phase that never starts, even in a run that completes. Every phase that starts also ends, before the run’s `workflow_run.status_ended`. |
9292| `workflow_run.status_ended` | The run ended. Always the last of the run’s `workflow_run.*` events. Includes `result` (csharp, go: `Result`). | Read `result` (csharp, go: `Result`) (next table). The agent then gets a turn to read how the run ended. At the budget, or while the primary thread waits on your client, that turn comes later. After an interrupt, that turn might not come: send a `user.message`, or read `result` (csharp, go: `Result`) yourself. After an archive or termination, it doesn’t come. |
9393| `workflow_run.error` | The server reports an error of a run, or a start that it refused. A run that ends in `error` gets this event, with the same error, before its `workflow_run.status_ended`. Includes `error` (csharp, go: `Error`): a `type` (csharp, go: `Type`) and a `message` (csharp, go: `Message`) that is safe to log. `workflow_run_id` (java: `workflowRunId`; php: `workflowRunID`; csharp, go: `WorkflowRunID`) is `null` (python: `None`; ruby: `nil`; java: `Optional.empty()`; go: `""`) when no run was created. | Log it, and don’t take it as the run’s end. If `workflow_run_id` (java: `workflowRunId`; php: `workflowRunID`; csharp, go: `WorkflowRunID`) is `null` (python: `None`; ruby: `nil`; java: `Optional.empty()`; go: `""`), no run started. Otherwise keep tracking the run until its `workflow_run.status_ended`. |
from line 96
9696| --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
9797| `{"type": "completed"}` | The workflow finished running. The result doesn’t say whether the work passed. A run can end `completed` even though work on its threads failed, or a thread couldn’t be created. To find failed work, read the events of each of the [run’s threads](https://platform.claude.com/docs/en/managed-agents/workflow-runs#a-runs-threads). |
9898| `{"type": "stopped"}` | The agent stopped the run, or the session was archived. The event doesn’t say which. Don’t treat these as the only causes. |
99| `error` with `timeout_error` | The run reached its [lifetime](https://platform.claude.com/docs/en/managed-agents/workflow-runs#limits), which the agent can set. |
99| `error` with `timeout_error` | The run reached its [lifetime limit](https://platform.claude.com/docs/en/managed-agents/workflow-runs#limits), which the agent can set. |
100100| `error` with `program_error` | The workflow failed. Its code failed, or it broke a rule for workflows, other than a limit. Or one of the run’s threads failed, or couldn’t be created, and the workflow let that end the run. |
101101| `error` with `thread_limit_error` | The run went over its [limit on the agents that a workflow starts](https://platform.claude.com/docs/en/managed-agents/workflow-runs#limits). |
102102| `error` with `unknown_error` | The server couldn’t continue the run, or the run went over one of the server’s other limits on workflows. |
from line 160
160160Each agent in a run works in its own [session thread](https://platform.claude.com/docs/en/managed-agents/session-threads), which the server creates as the workflow needs it. You can list, read, and stream a run’s threads like any child thread, and answer their tool calls from the primary stream. To stop them, ask the agent to stop the run (see [Interrupt a session with runs open](https://platform.claude.com/docs/en/managed-agents/workflow-runs#interrupt-a-session-with-runs-open)).
161161
162162* **Grouping:** A run’s thread has the run’s `workflow_run_id` (java: `workflowRunId`; php: `workflowRunID`; csharp, go: `WorkflowRunID`), as does the `session.thread_created` event that announces it. Other threads, and the `session.thread_created` events that announce them, have `workflow_run_id` (java: `workflowRunId`; php: `workflowRunID`; csharp, go: `WorkflowRunID`) set to `null` (python: `None`; ruby: `nil`; java: `Optional.empty()`; go: `""`).
163* **Agent:** `agent` (csharp, go: `Agent`) shows the agent the thread runs. For an agent you listed in the [`predefined_agents` (java, php: `predefinedAgents`; csharp, go: `PredefinedAgents`) list of `workflows` (csharp, go: `Workflows`)](https://platform.claude.com/docs/en/managed-agents/multiagent-orchestration#turn-on-dynamic-workflows) in `multiagent` (csharp, go: `Multiagent`), `agent` (csharp, go: `Agent`) has that agent’s `id` (csharp, go: `ID`) and `version` (csharp, go: `Version`), as on the thread of a subagent you listed. For an agent the workflow defines (an inline agent), `agent` (csharp, go: `Agent`) has `type` `inline` and no `id` (csharp, go: `ID`) or `version` (csharp, go: `Version`). It has the system prompt the workflow wrote, not the session agent’s. It also has the name and description the workflow gave it. The server assigns a name if the workflow gave none. It uses the model of the session agent, the agent the session runs. Its tools, MCP servers, and skills are a subset of the session agent’s. It gets all of them, but the API doesn’t guarantee that. Its tools keep their permission policies.
163* **Agent:** `agent` (csharp, go: `Agent`) shows the agent the thread runs. For an agent you listed in the [`predefined_agents` (java, php: `predefinedAgents`; csharp, go: `PredefinedAgents`) list of `workflows` (csharp, go: `Workflows`)](https://platform.claude.com/docs/en/managed-agents/multiagent-orchestration#turn-on-dynamic-workflows) in `multiagent` (csharp, go: `Multiagent`), `agent` (csharp, go: `Agent`) has that agent’s `id` (csharp, go: `ID`) and `version` (csharp, go: `Version`). The thread of a subagent you listed shows them too. For an agent the workflow defines (an inline agent), `agent` (csharp, go: `Agent`) has `type` `inline` and no `id` (csharp, go: `ID`) or `version` (csharp, go: `Version`). It has the system prompt the workflow wrote, not the session agent’s. It also has the name and description the workflow gave it. The server assigns a name if the workflow gave none. It uses the model of the session agent, the agent the session runs. Its tools, MCP servers, and skills are a subset of the session agent’s. It gets all of them, but the API doesn’t guarantee that. Its tools keep their permission policies.
164164* **What the threads share:** A run’s threads work in the session’s sandbox, so every thread works with the same files. That includes the files of a memory store the session mounts. An agent the workflow defines uses its MCP servers with the credentials the session resolves for them. Each thread has its own conversation history.
165* **Events:** A run thread’s `session.thread_created`, `session.thread_status_running`, `session.thread_status_idle`, and `session.thread_status_terminated` events also arrive on the primary stream (see [Run events](https://platform.claude.com/docs/en/managed-agents/workflow-runs#run-events)). Its message events stay on its own stream. Its thread webhooks are sent as for any child thread. For what the thread’s own stream records, see [Session thread events](https://platform.claude.com/docs/en/managed-agents/session-threads#session-thread-events).
166* **Phases:** No event or field says which phase a thread works in, and threads of one run can have the same `agent_name`. Follow a run’s progress by its phase events, and tell its threads apart by `session_thread_id` (java: `sessionThreadId`; php: `sessionThreadID`; csharp, go: `SessionThreadID`).
165* **Events:** A run thread’s `session.thread_created`, `session.thread_status_running`, `session.thread_status_idle`, and `session.thread_status_terminated` events also arrive on the primary stream (see [Run events](https://platform.claude.com/docs/en/managed-agents/workflow-runs#run-events)). Its message events stay on its own stream. The server sends its thread webhooks as for any child thread. For what the thread’s own stream records, see [Session thread events](https://platform.claude.com/docs/en/managed-agents/session-threads#session-thread-events).
166* **Phases:** No event or field says which phase a thread works in, and threads of one run can have the same `agent_name` (java, php: `agentName`; csharp, go: `AgentName`). Follow a run’s progress by its phase events, and tell its threads apart by `session_thread_id` (java: `sessionThreadId`; php: `sessionThreadID`; csharp, go: `SessionThreadID`).
167167* **Archiving:** The server archives each thread no later than the end of its run. It can archive one sooner, once the thread returns its result or the run finishes with it. If the thread is still running or waiting on your client at that point, the server stops it first. An archived thread stays in the thread list, with status `terminated`. You don’t need to archive a run’s threads yourself.
168168* **Tools:** A run can create more than one thread for the same piece of work, so make the tools your agents call safe to call twice.
169169
170170<Tip>
171 You can ask the agent for the workflow that it wrote for your request. Wait until the run has ended and the session is `idle`. Then send a `user.message` that asks the agent to print the workflow that it started the run with, word for word, and not to start another run.
171 You can ask the agent for the workflow that it wrote for your request. Wait until the run has ended and the session is `idle`. Then send a `user.message` that asks the agent to print that workflow word for word, and not to start another run.
172172
173173 ```text wrap
174174 Print the workflow that you started the run with, word for word, in one code block. Do not start another run.
from line 192
192192This sample follows a session from your message to the agent’s answer. It opens the stream and sends the message. Then it does the following:
193193
194194* **Tracks each run** from its `workflow_run.created` to its `workflow_run.status_ended`, and prints each phase as it starts.
195
195196* **Answers custom tool calls** when each `agent.custom_tool_use` arrives, because a run’s thread can wait on your client while the session stays `running`. If your agent’s tools [ask for confirmation](https://platform.claude.com/docs/en/managed-agents/events-and-streaming#tool-confirmation), add a branch that answers each `agent.tool_use` or `agent.mcp_tool_use` whose `evaluated_permission` (java, php: `evaluatedPermission`; csharp, go: `EvaluatedPermission`) is `ask`. The sample has none, because a branch that allows every call would turn `always_ask` into always allow.
196* **Stops** when the [work is done](https://platform.claude.com/docs/en/managed-agents/workflow-runs#know-when-the-work-is-done): no run is open, and the session goes idle with `end_turn`. It also stops if the session terminates. On an idle with any other stop reason except `requires_action`, such as `budget_reached`, `retries_exhausted`, or `refusal`, it prints the reason and stops, so handle those in your own code. It stops on `retries_exhausted` even when the server is about to start a new turn by itself. It keeps waiting on `requires_action`, and on `end_turn` while a run is open.
197197
198* **Stops** when the [work is done](https://platform.claude.com/docs/en/managed-agents/workflow-runs#know-when-the-work-is-done): no run is open, and the session goes idle with `end_turn`. It also stops in these cases:
199
200 * The session terminates.
201 * The session goes idle with any stop reason other than `end_turn` or `requires_action`, such as `budget_reached`, `retries_exhausted`, or `refusal`. The sample prints the reason and stops, so handle those in your own code. It stops on `retries_exhausted` even when the server is about to start a new turn by itself.
202
203* **Keeps waiting** on `requires_action`, and on `end_turn` while a run is open.
204
198205<CodeGroup exclude="shell">
199206 <CodeGroupItem language="cURL">
200207 This workflow needs more logic than a single shell command. Use the [Anthropic SDK](https://platform.claude.com/docs/en/cli-sdks-libraries/overview) to run it.
from line 785
778785
779786Send [`user.interrupt`](https://platform.claude.com/docs/en/managed-agents/events-and-streaming#interrupt-the-agent) with no `session_thread_id` (java: `sessionThreadId`; php: `sessionThreadID`; csharp, go: `SessionThreadID`), or with the primary thread’s ID. It stops the agent’s turn. It ends no run. The session’s runs might pause or keep running, and their events might not show which. A paused run’s lifetime keeps passing, so the run can end with `timeout_error` while it’s paused.
780787
781* **Waiting tool calls:** After the interrupt, a run thread’s tool call might still wait on your client. Answer each one. To cancel a call that asks for confirmation, deny it. To cancel a custom tool call, send a result with `is_error` (java, php: `isError`; csharp, go: `IsError`) set to `true` and a text in `content` (csharp, go: `Content`) that says why. While the session is `idle` with `requires_action`, a `user.message` returns 400, so answer the calls first.
782* **To stop the runs:** Send a `user.message` asking the agent to stop its runs. A stopped run ends with `result` `{"type": "stopped"}`. While the session is `idle` with `budget_reached`, a `user.message` returns 400 until you raise or remove the budget. Raising or removing it also resumes the runs that the budget paused, unless the interrupt also paused them.
783* **To continue:** Send a `user.message` asking the agent to continue its runs. After an interrupt, the runs might wait for this message. If the session is `idle` with `budget_reached`, raise or remove the budget first.
788* **Waiting tool calls:** After the interrupt, a run thread’s tool call might still wait on your client. Answer each one. To cancel a call that asks for confirmation, deny it. To cancel a custom tool call, send a result with `is_error` (java, php: `isError`; csharp, go: `IsError`) set to `true` and text in `content` (csharp, go: `Content`) that says why. While the session is `idle` with `requires_action`, a `user.message` returns 400, so answer the calls first.
789* **Stopping the runs:** Send a `user.message` asking the agent to stop its runs. A stopped run ends with `result` (csharp, go: `Result`) `{"type": "stopped"}`. While the session is `idle` with `budget_reached`, a `user.message` returns 400 until you raise or remove the budget. Raising or removing it also resumes the runs that the budget paused, unless the interrupt also paused them.
790* **Continuing the runs:** Send a `user.message` asking the agent to continue its runs. After an interrupt, the runs might wait for this message. If the session is `idle` with `budget_reached`, raise or remove the budget first.
784791* **Run results:** A run that ends after the interrupt still sends `workflow_run.status_ended`.
785792
786793## While a run is open
from line 821
814821
815822The server shortens a run’s or phase’s `name` (csharp, go: `Name`) to 64 characters and its `description` (csharp, go: `Description`) to 256. The server has other limits on workflows, and rules for them, that aren’t listed here. What you see depends on when the server finds the problem:
816823
817| What happens | What you see |
824| What occurs | What you see |
818825| -------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
819| The workflow is over one of the other limits when the agent starts the run | The start is refused. You get a `workflow_run.error`, and no run. |
826| The workflow is over one of the other limits when the agent starts the run | The server refuses the start. You get a `workflow_run.error`, and no run. |
820827| The run goes over one of the other limits later | You get a `workflow_run.error`, and then the run can end with `unknown_error`. |
821828| The server finds after the start that the workflow breaks a rule for workflows, other than a limit | You get a `workflow_run.error`, and the run can then end with `program_error`. |
822829
from line 844
837844| Your client’s requests to retrieve or list the session, its threads, and their events | The read limit for [Managed Agents endpoints](https://platform.claude.com/docs/en/managed-agents/reference#rate-limits) | Follow a run on the session’s event stream instead of polling. |
838845| Model requests from a run’s threads | Your [Messages API rate limits](https://platform.claude.com/docs/en/api/rate-limits) for the model each thread uses, along with your other traffic | Leave room for a run in those limits, or [request higher limits](https://platform.claude.com/docs/en/api/rate-limits#requesting-higher-limits). |
839846
840When a model request from one of a run’s threads is rate limited, or the model is overloaded, the thread’s own stream can get a `session.error` of type `model_rate_limited_error` or `model_overloaded_error`:
847A thread’s own stream can get a `session.error` when one of its model requests is rate limited or the model is overloaded. The error’s type is `model_rate_limited_error` or `model_overloaded_error`:
841848
842849* If its `retry_status.type` is `retrying`, the server is retrying the request, and the thread is still working.
843850* If it’s `exhausted`, the thread has failed. If the workflow lets that failure end the run, the run ends with `program_error`, which doesn’t name the cause. Read the failed threads’ events to find it.
api/beta/organization/claude_tag/slack_channels Changed · +2 / -2 lines
from line 165
165165
166166 - `environment_id: optional string or null`
167167
168 The environment Claude's sessions run in: the identifier of an active environment of the organization, starting with `env_`. Null clears it.
168 The environment Claude's sessions run in: the identifier of an active environment of the organization, starting with `env_`, or of a self-hosted runner pool of the organization that every member may use, starting with `ccpool_`. Null clears it.
169169
170170 minLength: 1, maxLength: 64
171171
from line 1529
15291529
15301530 - `environment_id: optional string or null`
15311531
1532 The environment Claude's sessions run in: the identifier of an active environment of the organization, starting with `env_`. Null clears it.
1532 The environment Claude's sessions run in: the identifier of an active environment of the organization, starting with `env_`, or of a self-hosted runner pool of the organization that every member may use, starting with `ccpool_`. Null clears it.
15331533
15341534 minLength: 1, maxLength: 64
15351535
api/beta/organization/claude_tag/slack_channels/create Changed · +1 / -1 lines
from line 163
163163
164164 - `environment_id: optional string or null`
165165
166 The environment Claude's sessions run in: the identifier of an active environment of the organization, starting with `env_`. Null clears it.
166 The environment Claude's sessions run in: the identifier of an active environment of the organization, starting with `env_`, or of a self-hosted runner pool of the organization that every member may use, starting with `ccpool_`. Null clears it.
167167
168168 minLength: 1, maxLength: 64
169169
api/beta/organization/claude_tag/slack_channels/update Changed · +1 / -1 lines
from line 153
153153
154154 - `environment_id: optional string or null`
155155
156 The environment Claude's sessions run in: the identifier of an active environment of the organization, starting with `env_`. Null clears it.
156 The environment Claude's sessions run in: the identifier of an active environment of the organization, starting with `env_`, or of a self-hosted runner pool of the organization that every member may use, starting with `ccpool_`. Null clears it.
157157
158158 minLength: 1, maxLength: 64
159159
api/beta/organization/claude_tag/slack_workspaces Changed · +1 / -1 lines
from line 1022
10221022
10231023 - `environment_id: optional string or null`
10241024
1025 The environment Claude's sessions run in: the identifier of an active environment of the organization, starting with `env_`. Null clears it.
1025 The environment Claude's sessions run in: the identifier of an active environment of the organization, starting with `env_`, or of a self-hosted runner pool of the organization that every member may use, starting with `ccpool_`. Null clears it.
10261026
10271027 minLength: 1, maxLength: 64
10281028
api/beta/organization/claude_tag/slack_workspaces/update Changed · +1 / -1 lines
from line 153
153153
154154 - `environment_id: optional string or null`
155155
156 The environment Claude's sessions run in: the identifier of an active environment of the organization, starting with `env_`. Null clears it.
156 The environment Claude's sessions run in: the identifier of an active environment of the organization, starting with `env_`, or of a self-hosted runner pool of the organization that every member may use, starting with `ccpool_`. Null clears it.
157157
158158 minLength: 1, maxLength: 64
159159
api/beta/organization/plugin_marketplaces Changed · +2 / -2 lines
from line 33
3333
3434- `organization_id: optional string`
3535
36 For a `read:org_audit` or `read:compliance_org_data` key created for all of a parent organization's linked organizations: a child organization of that parent to read instead of the organization the key was created in, given as the organization's UUID or its `org_`-prefixed ID. A value that is neither returns a 400; an organization that is not a child of the key's parent, or where the Plugins API is not available, returns a 404. Any other key may pass only its own organization's ID here; another organization returns a 404.
36 For a `read:org_audit` or `read:compliance_org_data` key created for all of a parent organization's linked organizations: a child organization of that parent to read instead of the organization the key was created in, given as the organization's UUID or its `org_`-prefixed ID. A value that is neither returns a 400; an organization that is not a child of the key's parent, or where the Plugins API is not available, returns a 404. Any other key may pass only its own organization's ID here; another organization returns a 404. A key with no organization of its own must always pass `organization_id`.
3737
3838- `owner_type: optional "organization" or "user"`
3939
from line 340
340340
341341- `organization_id: optional string`
342342
343 For a `read:org_audit` or `read:compliance_org_data` key created for all of a parent organization's linked organizations: a child organization of that parent to read instead of the organization the key was created in, given as the organization's UUID or its `org_`-prefixed ID. A value that is neither returns a 400; an organization that is not a child of the key's parent, or where the Plugins API is not available, returns a 404. Any other key may pass only its own organization's ID here; another organization returns a 404.
343 For a `read:org_audit` or `read:compliance_org_data` key created for all of a parent organization's linked organizations: a child organization of that parent to read instead of the organization the key was created in, given as the organization's UUID or its `org_`-prefixed ID. A value that is neither returns a 400; an organization that is not a child of the key's parent, or where the Plugins API is not available, returns a 404. Any other key may pass only its own organization's ID here; another organization returns a 404. A key with no organization of its own must always pass `organization_id`.
344344
345345### Headers
346346
api/beta/organization/plugin_marketplaces/list Changed · +1 / -1 lines
from line 31
3131
3232- `organization_id: optional string`
3333
34 For a `read:org_audit` or `read:compliance_org_data` key created for all of a parent organization's linked organizations: a child organization of that parent to read instead of the organization the key was created in, given as the organization's UUID or its `org_`-prefixed ID. A value that is neither returns a 400; an organization that is not a child of the key's parent, or where the Plugins API is not available, returns a 404. Any other key may pass only its own organization's ID here; another organization returns a 404.
34 For a `read:org_audit` or `read:compliance_org_data` key created for all of a parent organization's linked organizations: a child organization of that parent to read instead of the organization the key was created in, given as the organization's UUID or its `org_`-prefixed ID. A value that is neither returns a 400; an organization that is not a child of the key's parent, or where the Plugins API is not available, returns a 404. Any other key may pass only its own organization's ID here; another organization returns a 404. A key with no organization of its own must always pass `organization_id`.
3535
3636- `owner_type: optional "organization" or "user"`
3737