Stream Session Thread Events changedapi/beta/sessions/threads/events/stream
Nearest release: v2.1.245, published an hour after this site recorded the change. Shown because the two are within 24 hours of each other. Nothing here says the release caused the edit.
Recorded here
Lines+328added
Lines−401removed
From line
1
where the diff opens
First seen
14 Aug 2026
this site's first read of the page
Recorded edits26to this page, all time
# Stream Session Thread Events ## Path parameters ## Query parameters ## Headers ## Returns ## Example ### Response (200) ## Stream Session Thread Events ### Path Parameters ### Query Parameters ### Header Parameters ### Returns ### Example #### Response
The whole hunk
from line 1, old and new numbered
/
The two sides of this change are more than 400 edits apart, too far apart to line up, so this is the differ's own diff of it and the words inside a line are not marked.
from line 1
1---
2title: Stream Session Thread Events
3url: https://platform.claude.com/docs/en/api/beta/sessions/threads/events/stream
4---
5
6## Stream Session Thread Events
7
8**get** `/v1/sessions/{session_id}/threads/{thread_id}/stream`
1# Stream Session Thread Events
2
3**GET** `/v1/sessions/{session_id}/threads/{thread_id}/stream`
94
105Stream Session Thread Events
116
12### Path Parameters
7## Path parameters
138
149- `session_id: string`
1510
1611- `thread_id: string`
1712
18### Query Parameters
13## Query parameters
1914
2015- `event_deltas: optional array of BetaManagedAgentsDeltaType`
2116
from line 20
2520
2621 - `"agent.thinking"`
2722
28### Header Parameters
23## Headers
2924
3025- `"anthropic-beta": optional array of AnthropicBeta`
3126
from line 98
10398
10499 - `"mid-conversation-tool-changes-2026-07-01"`
105100
106### Returns
101## Returns
107102
108103- `BetaManagedAgentsStreamSessionThreadEvents = BetaManagedAgentsUserMessageEvent or BetaManagedAgentsUserInterruptEvent or BetaManagedAgentsUserToolConfirmationEvent or 34 more`
109104
110105 Server-sent event in a single thread's stream.
111106
112 - `BetaManagedAgentsUserMessageEvent object { id, content, type, processed_at }`
107 - `BetaManagedAgentsUserMessageEvent object`
113108
114109 A user message event in the session conversation.
115110
from line 116
121116
122117 Array of content blocks comprising the user message.
123118
124 - `BetaManagedAgentsTextBlock object { text, type }`
119 - `BetaManagedAgentsTextBlock object`
125120
126121 Regular text content.
127122
from line 124
129124
130125 The text content.
131126
127 minLength: 1
128
132129 - `type: "text"`
133130
134 - `"text"`
135
136 - `BetaManagedAgentsImageBlock object { source, type }`
131 - `BetaManagedAgentsImageBlock object`
137132
138133 Image content specified directly as base64 data or as a reference via a URL.
139134
from line 136
141136
142137 Union type for image source variants.
143138
144 - `BetaManagedAgentsBase64ImageSource object { data, media_type, type }`
139 - `BetaManagedAgentsBase64ImageSource object`
145140
146141 Base64-encoded image data.
147142
from line 144
149144
150145 Base64-encoded image data.
151146
147 minLength: 1
148
152149 - `media_type: string`
153150
154151 MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp").
155152
153 minLength: 1
154
156155 - `type: "base64"`
157156
158 - `"base64"`
159
160 - `BetaManagedAgentsURLImageSource object { type, url }`
157 - `BetaManagedAgentsURLImageSource object`
161158
162159 Image referenced by URL.
163160
164161 - `type: "url"`
165162
166 - `"url"`
167
168163 - `url: string`
169164
170165 URL of the image to fetch.
171166
172 - `BetaManagedAgentsFileImageSource object { file_id, type }`
167 minLength: 1
168
169 - `BetaManagedAgentsFileImageSource object`
173170
174171 Image referenced by file ID.
175172
from line 174
177174
178175 ID of a previously uploaded file.
179176
177 minLength: 1
178
180179 - `type: "file"`
181180
182 - `"file"`
183
184181 - `type: "image"`
185182
186 - `"image"`
187
188 - `BetaManagedAgentsDocumentBlock object { source, type, context, title }`
183 - `BetaManagedAgentsDocumentBlock object`
189184
190185 Document content, either specified directly as base64 data, as text, or as a reference via a URL.
191186
from line 188
193188
194189 Union type for document source variants.
195190
196 - `BetaManagedAgentsBase64DocumentSource object { data, media_type, type }`
191 - `BetaManagedAgentsBase64DocumentSource object`
197192
198193 Base64-encoded document data.
199194
from line 196
201196
202197 Base64-encoded document data.
203198
199 minLength: 1
200
204201 - `media_type: string`
205202
206203 MIME type of the document (e.g., "application/pdf").
207204
205 minLength: 1
206
208207 - `type: "base64"`
209208
210 - `"base64"`
211
212 - `BetaManagedAgentsPlainTextDocumentSource object { data, media_type, type }`
209 - `BetaManagedAgentsPlainTextDocumentSource object`
213210
214211 Plain text document content.
215212
from line 214
217214
218215 The plain text content.
219216
217 minLength: 1
218
220219 - `media_type: "text/plain"`
221220
222221 MIME type of the text content. Must be "text/plain".
223222
224 - `"text/plain"`
225
226223 - `type: "text"`
227224
228 - `"text"`
229
230 - `BetaManagedAgentsURLDocumentSource object { type, url }`
225 - `BetaManagedAgentsURLDocumentSource object`
231226
232227 Document referenced by URL.
233228
234229 - `type: "url"`
235230
236 - `"url"`
237
238231 - `url: string`
239232
240233 URL of the document to fetch.
241234
242 - `BetaManagedAgentsFileDocumentSource object { file_id, type }`
235 minLength: 1
236
237 - `BetaManagedAgentsFileDocumentSource object`
243238
244239 Document referenced by file ID.
245240
from line 242
247242
248243 ID of a previously uploaded file.
249244
245 minLength: 1
246
250247 - `type: "file"`
251248
252 - `"file"`
253
254249 - `type: "document"`
255250
256 - `"document"`
257
258251 - `context: optional string or null`
259252
260253 Additional context about the document for the model.
from line 256
263256
264257 The title of the document.
265258
266 - `BetaManagedAgentsRedactedBlock object { type }`
259 - `BetaManagedAgentsRedactedBlock object`
267260
268261 Placeholder for content withheld by Anthropic model policy.
269262
270263 - `type: "redacted"`
271264
272 - `"redacted"`
273
274265 - `type: "user.message"`
275266
276 - `"user.message"`
277
278267 - `processed_at: optional string or null`
279268
280269 A timestamp in RFC 3339 format
281270
282 - `BetaManagedAgentsUserInterruptEvent object { id, type, processed_at, session_thread_id }`
271 format: date-time
272
273 - `BetaManagedAgentsUserInterruptEvent object`
283274
284275 An interrupt event that pauses agent execution and returns control to the user.
285276
from line 280
289280
290281 - `type: "user.interrupt"`
291282
292 - `"user.interrupt"`
293
294283 - `processed_at: optional string or null`
295284
296285 A timestamp in RFC 3339 format
297286
287 format: date-time
288
298289 - `session_thread_id: optional string or null`
299290
300291 If absent, interrupts every non-archived thread in a multiagent session (or the primary alone in a single-agent session). If present, interrupts only the named thread.
301292
302 - `BetaManagedAgentsUserToolConfirmationEvent object { id, result, tool_use_id, 4 more }`
293 - `BetaManagedAgentsUserToolConfirmationEvent object`
303294
304295 A tool confirmation event that approves or denies a pending tool execution.
305296
from line 312
321312
322313 - `type: "user.tool_confirmation"`
323314
324 - `"user.tool_confirmation"`
325
326315 - `deny_message: optional string or null`
327316
328317 Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'.
329318
319 maxLength: 10000
320
330321 - `processed_at: optional string or null`
331322
332323 A timestamp in RFC 3339 format
333324
325 format: date-time
326
334327 - `session_thread_id: optional string or null`
335328
336329 When set, the confirmation routes to this subagent's thread rather than the primary. Echo this from the `session_thread_id` on the `agent.tool_use` or `agent.mcp_tool_use` event that prompted the approval.
337330
338 - `BetaManagedAgentsUserCustomToolResultEvent object { id, custom_tool_use_id, type, 4 more }`
331 - `BetaManagedAgentsUserCustomToolResultEvent object`
339332
340333 Event sent by the client providing the result of a custom tool execution.
341334
from line 342
349342
350343 - `type: "user.custom_tool_result"`
351344
352 - `"user.custom_tool_result"`
353
354345 - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock`
355346
356347 The result content returned by the tool.
357348
358 - `BetaManagedAgentsTextBlock object { text, type }`
349 - `BetaManagedAgentsTextBlock object`
359350
360351 Regular text content.
361352
362 - `BetaManagedAgentsImageBlock object { source, type }`
353 - `BetaManagedAgentsImageBlock object`
363354
364355 Image content specified directly as base64 data or as a reference via a URL.
365356
366 - `BetaManagedAgentsDocumentBlock object { source, type, context, title }`
357 - `BetaManagedAgentsDocumentBlock object`
367358
368359 Document content, either specified directly as base64 data, as text, or as a reference via a URL.
369360
370 - `BetaManagedAgentsSearchResultBlock object { citations, content, source, 2 more }`
361 - `BetaManagedAgentsSearchResultBlock object`
371362
372363 A block containing a web search result.
373364
from line 378
387378
388379 The text content.
389380
381 minLength: 1
382
390383 - `type: "text"`
391384
392 - `"text"`
393
394385 - `source: string`
395386
396387 The URL source of the search result.
397388
389 minLength: 1
390
398391 - `title: string`
399392
400393 The title of the search result.
401394
395 minLength: 1
396
402397 - `type: "search_result"`
403398
404 - `"search_result"`
405
406399 - `is_error: optional boolean or null`
407400
408401 Whether the tool execution resulted in an error.
from line 404
411404
412405 A timestamp in RFC 3339 format
413406
407 format: date-time
408
414409 - `session_thread_id: optional string or null`
415410
416411 Routes this result to a subagent thread. Copy from the `agent.custom_tool_use` event's `session_thread_id`.
417412
418 - `BetaManagedAgentsAgentCustomToolUseEvent object { id, input, name, 3 more }`
413 - `BetaManagedAgentsAgentCustomToolUseEvent object`
419414
420415 Event emitted when the agent calls a custom tool. The session goes idle until the client sends a `user.custom_tool_result` event with the result.
421416
from line 430
435430
436431 A timestamp in RFC 3339 format
437432
433 format: date-time
434
438435 - `type: "agent.custom_tool_use"`
439436
440 - `"agent.custom_tool_use"`
441
442437 - `session_thread_id: optional string or null`
443438
444439 When set, this event was cross-posted from a subagent's thread to surface its custom tool use on the primary thread's stream. Empty on the thread's own events. Echo this on a `user.custom_tool_result` event to route the result back.
445440
446 - `BetaManagedAgentsAgentMessageEvent object { id, content, processed_at, type }`
441 - `BetaManagedAgentsAgentMessageEvent object`
447442
448443 An agent response event in the session conversation.
449444
from line 450
455450
456451 Array of text blocks comprising the agent response.
457452
458 - `BetaManagedAgentsTextBlock object { text, type }`
453 - `BetaManagedAgentsTextBlock object`
459454
460455 Regular text content.
461456
462 - `BetaManagedAgentsRedactedBlock object { type }`
457 - `BetaManagedAgentsRedactedBlock object`
463458
464459 Placeholder for content withheld by Anthropic model policy.
465460
from line 462
467462
468463 A timestamp in RFC 3339 format
469464
465 format: date-time
466
470467 - `type: "agent.message"`
471468
472 - `"agent.message"`
473
474 - `BetaManagedAgentsAgentThinkingEvent object { id, processed_at, type }`
469 - `BetaManagedAgentsAgentThinkingEvent object`
475470
476471 Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier.
477472
from line 478
483478
484479 A timestamp in RFC 3339 format
485480
481 format: date-time
482
486483 - `type: "agent.thinking"`
487484
488 - `"agent.thinking"`
489
490 - `BetaManagedAgentsAgentMCPToolUseEvent object { id, input, mcp_server_name, 5 more }`
485 - `BetaManagedAgentsAgentMCPToolUseEvent object`
491486
492487 Event emitted when the agent invokes a tool provided by an MCP server.
493488
from line 506
511506
512507 A timestamp in RFC 3339 format
513508
509 format: date-time
510
514511 - `type: "agent.mcp_tool_use"`
515512
516 - `"agent.mcp_tool_use"`
517
518513 - `evaluated_permission: optional "allow" or "ask" or "deny"`
519514
520515 AgentEvaluatedPermission enum
from line 524
529524
530525 When set, this event was cross-posted from a subagent's thread to surface its permission request on the primary thread's stream. Empty on the thread's own events. Echo this on a `user.tool_confirmation` event to route the approval back.
531526
532 - `BetaManagedAgentsAgentMCPToolResultEvent object { id, mcp_tool_use_id, processed_at, 3 more }`
527 - `BetaManagedAgentsAgentMCPToolResultEvent object`
533528
534529 Event representing the result of an MCP tool execution.
535530
from line 540
545540
546541 A timestamp in RFC 3339 format
547542
543 format: date-time
544
548545 - `type: "agent.mcp_tool_result"`
549546
550 - `"agent.mcp_tool_result"`
551
552547 - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock`
553548
554549 The result content returned by the tool.
555550
556 - `BetaManagedAgentsTextBlock object { text, type }`
551 - `BetaManagedAgentsTextBlock object`
557552
558553 Regular text content.
559554
560 - `BetaManagedAgentsImageBlock object { source, type }`
555 - `BetaManagedAgentsImageBlock object`
561556
562557 Image content specified directly as base64 data or as a reference via a URL.
563558
564 - `BetaManagedAgentsDocumentBlock object { source, type, context, title }`
559 - `BetaManagedAgentsDocumentBlock object`
565560
566561 Document content, either specified directly as base64 data, as text, or as a reference via a URL.
567562
568 - `BetaManagedAgentsSearchResultBlock object { citations, content, source, 2 more }`
563 - `BetaManagedAgentsSearchResultBlock object`
569564
570565 A block containing a web search result.
571566
from line 568
573568
574569 Whether the tool execution resulted in an error.
575570
576 - `BetaManagedAgentsAgentToolUseEvent object { id, input, name, 4 more }`
571 - `BetaManagedAgentsAgentToolUseEvent object`
577572
578573 Event emitted when the agent invokes a built-in agent tool.
579574
from line 588
593588
594589 A timestamp in RFC 3339 format
595590
591 format: date-time
592
596593 - `type: "agent.tool_use"`
597594
598 - `"agent.tool_use"`
599
600595 - `evaluated_permission: optional "allow" or "ask" or "deny"`
601596
602597 AgentEvaluatedPermission enum
from line 606
611606
612607 When set, this event was cross-posted from a subagent's thread to surface its permission request on the primary thread's stream. Empty on the thread's own events. Echo this on a `user.tool_confirmation` event to route the approval back.
613608
614 - `BetaManagedAgentsAgentToolResultEvent object { id, processed_at, tool_use_id, 3 more }`
609 - `BetaManagedAgentsAgentToolResultEvent object`
615610
616611 Event representing the result of an agent tool execution.
617612
from line 618
623618
624619 A timestamp in RFC 3339 format
625620
621 format: date-time
622
626623 - `tool_use_id: string`
627624
628625 The id of the `agent.tool_use` event this result corresponds to.
629626
630627 - `type: "agent.tool_result"`
631628
632 - `"agent.tool_result"`
633
634629 - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock`
635630
636631 The result content returned by the tool.
637632
638 - `BetaManagedAgentsTextBlock object { text, type }`
633 - `BetaManagedAgentsTextBlock object`
639634
640635 Regular text content.
641636
642 - `BetaManagedAgentsImageBlock object { source, type }`
637 - `BetaManagedAgentsImageBlock object`
643638
644639 Image content specified directly as base64 data or as a reference via a URL.
645640
646 - `BetaManagedAgentsDocumentBlock object { source, type, context, title }`
641 - `BetaManagedAgentsDocumentBlock object`
647642
648643 Document content, either specified directly as base64 data, as text, or as a reference via a URL.
649644
650 - `BetaManagedAgentsSearchResultBlock object { citations, content, source, 2 more }`
645 - `BetaManagedAgentsSearchResultBlock object`
651646
652647 A block containing a web search result.
653648
from line 650
655650
656651 Whether the tool execution resulted in an error.
657652
658 - `BetaManagedAgentsAgentThreadMessageReceivedEvent object { id, content, from_session_thread_id, 3 more }`
653 - `BetaManagedAgentsAgentThreadMessageReceivedEvent object`
659654
660655 Delivery event written to the target thread's input stream when an agent-to-agent message arrives.
661656
from line 662
667662
668663 Message content blocks.
669664
670 - `BetaManagedAgentsTextBlock object { text, type }`
665 - `BetaManagedAgentsTextBlock object`
671666
672667 Regular text content.
673668
674 - `BetaManagedAgentsImageBlock object { source, type }`
669 - `BetaManagedAgentsImageBlock object`
675670
676671 Image content specified directly as base64 data or as a reference via a URL.
677672
678 - `BetaManagedAgentsDocumentBlock object { source, type, context, title }`
673 - `BetaManagedAgentsDocumentBlock object`
679674
680675 Document content, either specified directly as base64 data, as text, or as a reference via a URL.
681676
682 - `BetaManagedAgentsRedactedBlock object { type }`
677 - `BetaManagedAgentsRedactedBlock object`
683678
684679 Placeholder for content withheld by Anthropic model policy.
685680
from line 686
691686
692687 A timestamp in RFC 3339 format
693688
689 format: date-time
690
694691 - `type: "agent.thread_message_received"`
695692
696 - `"agent.thread_message_received"`
697
698693 - `from_agent_name: optional string or null`
699694
700695 Name of the callable agent this message came from. Absent when received from the primary agent.
701696
702 - `BetaManagedAgentsAgentThreadMessageSentEvent object { id, content, processed_at, 3 more }`
697 - `BetaManagedAgentsAgentThreadMessageSentEvent object`
703698
704699 Observability event emitted to the sender's output stream when an agent-to-agent message is sent.
705700
from line 706
711706
712707 Message content blocks.
713708
714 - `BetaManagedAgentsTextBlock object { text, type }`
709 - `BetaManagedAgentsTextBlock object`
715710
716711 Regular text content.
717712
718 - `BetaManagedAgentsImageBlock object { source, type }`
713 - `BetaManagedAgentsImageBlock object`
719714
720715 Image content specified directly as base64 data or as a reference via a URL.
721716
722 - `BetaManagedAgentsDocumentBlock object { source, type, context, title }`
717 - `BetaManagedAgentsDocumentBlock object`
723718
724719 Document content, either specified directly as base64 data, as text, or as a reference via a URL.
725720
726 - `BetaManagedAgentsRedactedBlock object { type }`
721 - `BetaManagedAgentsRedactedBlock object`
727722
728723 Placeholder for content withheld by Anthropic model policy.
729724
from line 726
731726
732727 A timestamp in RFC 3339 format
733728
729 format: date-time
730
734731 - `to_session_thread_id: string`
735732
736733 Public `sthr_` ID of the thread the message was sent to.
737734
738735 - `type: "agent.thread_message_sent"`
739736
740 - `"agent.thread_message_sent"`
741
742737 - `to_agent_name: optional string or null`
743738
744739 Name of the callable agent this message was sent to. Absent when sent to the primary agent.
745740
746 - `BetaManagedAgentsAgentThreadContextCompactedEvent object { id, processed_at, type }`
741 - `BetaManagedAgentsAgentThreadContextCompactedEvent object`
747742
748743 Indicates that context compaction (summarization) occurred during the session.
749744
from line 750
755750
756751 A timestamp in RFC 3339 format
757752
753 format: date-time
754
758755 - `type: "agent.thread_context_compacted"`
759756
760 - `"agent.thread_context_compacted"`
761
762 - `BetaManagedAgentsSessionErrorEvent object { id, error, processed_at, type }`
757 - `BetaManagedAgentsSessionErrorEvent object`
763758
764759 An error event indicating a problem occurred during session execution.
765760
from line 766
771766
772767 An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone.
773768
774 - `BetaManagedAgentsUnknownError object { message, retry_status, type }`
769 - `BetaManagedAgentsUnknownError object`
775770
776771 An unknown or unexpected error occurred during session execution. A fallback variant; clients that don't recognize a new error code can match on `retry_status` and `message` alone.
777772
from line 778
783778
784779 What the client should do next in response to this error.
785780
786 - `BetaManagedAgentsRetryStatusRetrying object { type }`
781 - `BetaManagedAgentsRetryStatusRetrying object`
787782
788783 The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out.
789784
790785 - `type: "retrying"`
791786
792 - `"retrying"`
793
794 - `BetaManagedAgentsRetryStatusExhausted object { type }`
787 - `BetaManagedAgentsRetryStatusExhausted object`
795788
796789 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
797790
798791 - `type: "exhausted"`
799792
800 - `"exhausted"`
801
802 - `BetaManagedAgentsRetryStatusTerminal object { type }`
793 - `BetaManagedAgentsRetryStatusTerminal object`
803794
804795 The session encountered a terminal error and will transition to `terminated` state.
805796
806797 - `type: "terminal"`
807798
808 - `"terminal"`
809
810799 - `type: "unknown_error"`
811800
812 - `"unknown_error"`
813
814 - `BetaManagedAgentsModelOverloadedError object { message, retry_status, type }`
801 - `BetaManagedAgentsModelOverloadedError object`
815802
816803 The model is currently overloaded. Emitted after automatic retries are exhausted.
817804
from line 810
823810
824811 What the client should do next in response to this error.
825812
826 - `BetaManagedAgentsRetryStatusRetrying object { type }`
813 - `BetaManagedAgentsRetryStatusRetrying object`
827814
828815 The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out.
829816
830 - `BetaManagedAgentsRetryStatusExhausted object { type }`
817 - `BetaManagedAgentsRetryStatusExhausted object`
831818
832819 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
833820
834 - `BetaManagedAgentsRetryStatusTerminal object { type }`
821 - `BetaManagedAgentsRetryStatusTerminal object`
835822
836823 The session encountered a terminal error and will transition to `terminated` state.
837824
838825 - `type: "model_overloaded_error"`
839826
840 - `"model_overloaded_error"`
841
842 - `BetaManagedAgentsModelRateLimitedError object { message, retry_status, type }`
827 - `BetaManagedAgentsModelRateLimitedError object`
843828
844829 The model request was rate-limited.
845830
from line 836
851836
852837 What the client should do next in response to this error.
853838
854 - `BetaManagedAgentsRetryStatusRetrying object { type }`
839 - `BetaManagedAgentsRetryStatusRetrying object`
855840
856841 The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out.
857842
858 - `BetaManagedAgentsRetryStatusExhausted object { type }`
843 - `BetaManagedAgentsRetryStatusExhausted object`
859844
860845 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
861846
862 - `BetaManagedAgentsRetryStatusTerminal object { type }`
847 - `BetaManagedAgentsRetryStatusTerminal object`
863848
864849 The session encountered a terminal error and will transition to `terminated` state.
865850
866851 - `type: "model_rate_limited_error"`
867852
868 - `"model_rate_limited_error"`
869
870 - `BetaManagedAgentsModelRequestFailedError object { message, retry_status, type }`
853 - `BetaManagedAgentsModelRequestFailedError object`
871854
872855 A model request failed for a reason other than overload or rate-limiting.
873856
from line 862
879862
880863 What the client should do next in response to this error.
881864
882 - `BetaManagedAgentsRetryStatusRetrying object { type }`
865 - `BetaManagedAgentsRetryStatusRetrying object`
883866
884867 The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out.
885868
886 - `BetaManagedAgentsRetryStatusExhausted object { type }`
869 - `BetaManagedAgentsRetryStatusExhausted object`
887870
888871 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
889872
890 - `BetaManagedAgentsRetryStatusTerminal object { type }`
873 - `BetaManagedAgentsRetryStatusTerminal object`
891874
892875 The session encountered a terminal error and will transition to `terminated` state.
893876
894877 - `type: "model_request_failed_error"`
895878
896 - `"model_request_failed_error"`
897
898 - `BetaManagedAgentsMCPConnectionFailedError object { mcp_server_name, message, retry_status, type }`
879 - `BetaManagedAgentsMCPConnectionFailedError object`
899880
900881 Failed to connect to an MCP server.
901882
from line 892
911892
912893 What the client should do next in response to this error.
913894
914 - `BetaManagedAgentsRetryStatusRetrying object { type }`
895 - `BetaManagedAgentsRetryStatusRetrying object`
915896
916897 The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out.
917898
918 - `BetaManagedAgentsRetryStatusExhausted object { type }`
899 - `BetaManagedAgentsRetryStatusExhausted object`
919900
920901 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
921902
922 - `BetaManagedAgentsRetryStatusTerminal object { type }`
903 - `BetaManagedAgentsRetryStatusTerminal object`
923904
924905 The session encountered a terminal error and will transition to `terminated` state.
925906
926907 - `type: "mcp_connection_failed_error"`
927908
928 - `"mcp_connection_failed_error"`
929
930 - `BetaManagedAgentsMCPAuthenticationFailedError object { mcp_server_name, message, retry_status, type }`
909 - `BetaManagedAgentsMCPAuthenticationFailedError object`
931910
932911 Authentication to an MCP server failed.
933912
from line 922
943922
944923 What the client should do next in response to this error.
945924
946 - `BetaManagedAgentsRetryStatusRetrying object { type }`
925 - `BetaManagedAgentsRetryStatusRetrying object`
947926
948927 The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out.
949928
950 - `BetaManagedAgentsRetryStatusExhausted object { type }`
929 - `BetaManagedAgentsRetryStatusExhausted object`
951930
952931 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
953932
954 - `BetaManagedAgentsRetryStatusTerminal object { type }`
933 - `BetaManagedAgentsRetryStatusTerminal object`
955934
956935 The session encountered a terminal error and will transition to `terminated` state.
957936
958937 - `type: "mcp_authentication_failed_error"`
959938
960 - `"mcp_authentication_failed_error"`
961
962 - `BetaManagedAgentsBillingError object { message, retry_status, type }`
939 - `BetaManagedAgentsBillingError object`
963940
964941 The caller's organization or workspace cannot make model requests — out of credits or spend limit reached. Retrying with the same credentials will not succeed; the caller must resolve the billing state.
965942
from line 948
971948
972949 What the client should do next in response to this error.
973950
974 - `BetaManagedAgentsRetryStatusRetrying object { type }`
951 - `BetaManagedAgentsRetryStatusRetrying object`
975952
976953 The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out.
977954
978 - `BetaManagedAgentsRetryStatusExhausted object { type }`
955 - `BetaManagedAgentsRetryStatusExhausted object`
979956
980957 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
981958
982 - `BetaManagedAgentsRetryStatusTerminal object { type }`
959 - `BetaManagedAgentsRetryStatusTerminal object`
983960
984961 The session encountered a terminal error and will transition to `terminated` state.
985962
986963 - `type: "billing_error"`
987964
988 - `"billing_error"`
989
990 - `BetaManagedAgentsCredentialHostUnreachableError object { credential_id, message, retry_status, 2 more }`
965 - `BetaManagedAgentsCredentialHostUnreachableError object`
991966
992967 An `environment_variable` credential's `auth.networking.allowed_hosts` includes a host the environment's network policy does not permit.
993968
from line 978
1003978
1004979 What the client should do next in response to this error.
1005980
1006 - `BetaManagedAgentsRetryStatusRetrying object { type }`
981 - `BetaManagedAgentsRetryStatusRetrying object`
1007982
1008983 The server is retrying automatically. Client should wait; the same error type may fire again as retrying, then once as exhausted when the retry budget runs out.
1009984
1010 - `BetaManagedAgentsRetryStatusExhausted object { type }`
985 - `BetaManagedAgentsRetryStatusExhausted object`
1011986
1012987 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
1013988
1014 - `BetaManagedAgentsRetryStatusTerminal object { type }`
989 - `BetaManagedAgentsRetryStatusTerminal object`
1015990
1016991 The session encountered a terminal error and will transition to `terminated` state.
1017992
1018993 - `type: "credential_host_unreachable_error"`
1019994
1020 - `"credential_host_unreachable_error"`
1021
1022995 - `vault_id: string`
1023996
1024997 ID of the vault containing the affected credential.
from line 1000
10271000
10281001 A timestamp in RFC 3339 format
10291002
1003 format: date-time
1004
10301005 - `type: "session.error"`
10311006
1032 - `"session.error"`
1033
1034 - `BetaManagedAgentsSessionStatusRescheduledEvent object { id, processed_at, type }`
1007 - `BetaManagedAgentsSessionStatusRescheduledEvent object`
10351008
10361009 Indicates the session is recovering from an error state and is rescheduled for execution.
10371010
from line 1016
10431016
10441017 A timestamp in RFC 3339 format
10451018
1019 format: date-time
1020
10461021 - `type: "session.status_rescheduled"`
10471022
1048 - `"session.status_rescheduled"`
1049
1050 - `BetaManagedAgentsSessionStatusRunningEvent object { id, processed_at, type }`
1023 - `BetaManagedAgentsSessionStatusRunningEvent object`
10511024
10521025 Indicates the session is actively running and the agent is working.
10531026
from line 1032
10591032
10601033 A timestamp in RFC 3339 format
10611034
1035 format: date-time
1036
10621037 - `type: "session.status_running"`
10631038
1064 - `"session.status_running"`
1065
1066 - `BetaManagedAgentsSessionStatusIdleEvent object { id, processed_at, stop_reason, type }`
1039 - `BetaManagedAgentsSessionStatusIdleEvent object`
10671040
10681041 Indicates the agent has paused and is awaiting user input.
10691042
from line 1048
10751048
10761049 A timestamp in RFC 3339 format
10771050
1051 format: date-time
1052
10781053 - `stop_reason: BetaManagedAgentsSessionEndTurn or BetaManagedAgentsSessionRequiresAction or BetaManagedAgentsSessionRetriesExhausted or BetaManagedAgentsSessionBudgetReached`
10791054
10801055 The agent completed its turn naturally and is ready for the next user message.
10811056
1082 - `BetaManagedAgentsSessionEndTurn object { type }`
1057 - `BetaManagedAgentsSessionEndTurn object`
10831058
10841059 The agent completed its turn naturally and is ready for the next user message.
10851060
10861061 - `type: "end_turn"`
10871062
1088 - `"end_turn"`
1089
1090 - `BetaManagedAgentsSessionRequiresAction object { event_ids, type }`
1063 - `BetaManagedAgentsSessionRequiresAction object`
10911064
10921065 The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running.
10931066
from line 1070
10971070
10981071 - `type: "requires_action"`
10991072
1100 - `"requires_action"`
1101
1102 - `BetaManagedAgentsSessionRetriesExhausted object { type }`
1073 - `BetaManagedAgentsSessionRetriesExhausted object`
11031074
11041075 The turn ended because repeated errors exhausted the retry budget or an error escalated to `retry_status: 'exhausted'`.
11051076
11061077 - `type: "retries_exhausted"`
11071078
1108 - `"retries_exhausted"`
1109
1110 - `BetaManagedAgentsSessionBudgetReached object { type }`
1079 - `BetaManagedAgentsSessionBudgetReached object`
11111080
11121081 The agent stopped because the session's tracked list cost reached its budget, or because its usage includes a model with no list price (which the budget cannot measure). Raise the budget to continue — or, if raising is rejected because a model has no list price, remove the budget.
11131082
11141083 - `type: "budget_reached"`
11151084
1116 - `"budget_reached"`
1117
11181085 - `type: "session.status_idle"`
11191086
1120 - `"session.status_idle"`
1121
1122 - `BetaManagedAgentsSessionStatusTerminatedEvent object { id, processed_at, type }`
1087 - `BetaManagedAgentsSessionStatusTerminatedEvent object`
11231088
11241089 Indicates the session has terminated, either due to an error or completion.
11251090
from line 1096
11311096
11321097 A timestamp in RFC 3339 format
11331098
1099 format: date-time
1100
11341101 - `type: "session.status_terminated"`
11351102
1136 - `"session.status_terminated"`
1137
1138 - `BetaManagedAgentsSessionThreadCreatedEvent object { id, agent_name, processed_at, 2 more }`
1103 - `BetaManagedAgentsSessionThreadCreatedEvent object`
11391104
11401105 Emitted when a subagent is spawned as a new thread. Written to the parent thread's output stream so clients observing the session see child creation.
11411106
from line 1116
11511116
11521117 A timestamp in RFC 3339 format
11531118
1119 format: date-time
1120
11541121 - `session_thread_id: string`
11551122
11561123 Public `sthr_` ID of the newly created thread.
11571124
11581125 - `type: "session.thread_created"`
11591126
1160 - `"session.thread_created"`
1161
1162 - `BetaManagedAgentsSpanOutcomeEvaluationStartEvent object { id, iteration, outcome_id, 2 more }`
1127 - `BetaManagedAgentsSpanOutcomeEvaluationStartEvent object`
11631128
11641129 Emitted when an outcome evaluation cycle begins.
11651130
from line 1136
11711136
11721137 0-indexed revision cycle. 0 is the first evaluation; 1 is the re-evaluation after the first revision; etc.
11731138
1139 format: int32
1140
11741141 - `outcome_id: string`
11751142
11761143 The `outc_` ID of the outcome being evaluated.
from line 1146
11791146
11801147 A timestamp in RFC 3339 format
11811148
1149 format: date-time
1150
11821151 - `type: "span.outcome_evaluation_start"`
11831152
1184 - `"span.outcome_evaluation_start"`
1185
1186 - `BetaManagedAgentsSpanOutcomeEvaluationEndEvent object { id, explanation, iteration, 6 more }`
1153 - `BetaManagedAgentsSpanOutcomeEvaluationEndEvent object`
11871154
11881155 Emitted when an outcome evaluation cycle completes. Carries the verdict and aggregate token usage. A verdict of `needs_revision` means another evaluation cycle follows; `satisfied`, `max_iterations_reached`, `failed`, or `interrupted` are terminal — no further evaluation cycles follow.
11891156
from line 1166
11991166
12001167 0-indexed revision cycle, matching the corresponding `span.outcome_evaluation_start`.
12011168
1169 format: int32
1170
12021171 - `outcome_evaluation_start_id: string`
12031172
12041173 The id of the corresponding `span.outcome_evaluation_start` event.
from line 1180
12111180
12121181 A timestamp in RFC 3339 format
12131182
1183 format: date-time
1184
12141185 - `result: string`
12151186
12161187 Evaluation verdict. 'satisfied': criteria met, session goes idle. 'needs_revision': criteria not met, another revision cycle follows. 'max_iterations_reached': evaluation budget exhausted with criteria still unmet — one final acknowledgment turn follows before the session goes idle, but no further evaluation runs. 'failed': grader determined the rubric does not apply to the deliverables. 'interrupted': user sent an interrupt while evaluation was in progress.
12171188
12181189 - `type: "span.outcome_evaluation_end"`
12191190
1220 - `"span.outcome_evaluation_end"`
1221
12221191 - `usage: BetaManagedAgentsSpanModelUsage`
12231192
12241193 Token usage for a single model request.
from line 1196
12271196
12281197 Tokens used to create prompt cache in this request.
12291198
1199 format: int32
1200
12301201 - `cache_read_input_tokens: number`
12311202
12321203 Tokens read from prompt cache in this request.
12331204
1205 format: int32
1206
12341207 - `input_tokens: number`
12351208
12361209 Input tokens consumed by this request.
12371210
1211 format: int32
1212
12381213 - `output_tokens: number`
12391214
12401215 Output tokens generated by this request.
12411216
1217 format: int32
1218
12421219 - `speed: optional "standard" or "fast" or null`
12431220
12441221 Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time.
from line 1224
12471224
12481225 - `"fast"`
12491226
1250 - `BetaManagedAgentsSpanModelRequestStartEvent object { id, processed_at, type }`
1227 - `BetaManagedAgentsSpanModelRequestStartEvent object`
12511228
12521229 Emitted when a model request is initiated by the agent.
12531230
from line 1236
12591236
12601237 A timestamp in RFC 3339 format
12611238
1239 format: date-time
1240
12621241 - `type: "span.model_request_start"`
12631242
1264 - `"span.model_request_start"`
1265
1266 - `BetaManagedAgentsSpanModelRequestEndEvent object { id, is_error, model_request_start_id, 3 more }`
1243 - `BetaManagedAgentsSpanModelRequestEndEvent object`
12671244
12681245 Emitted when a model request completes.
12691246
from line 1264
12871264
12881265 A timestamp in RFC 3339 format
12891266
1267 format: date-time
1268
12901269 - `type: "span.model_request_end"`
12911270
1292 - `"span.model_request_end"`
1293
1294 - `BetaManagedAgentsSpanOutcomeEvaluationOngoingEvent object { id, iteration, outcome_id, 2 more }`
1271 - `BetaManagedAgentsSpanOutcomeEvaluationOngoingEvent object`
12951272
12961273 Periodic heartbeat emitted while an outcome evaluation cycle is in progress. Distinguishes 'evaluation is actively running' from 'evaluation is stuck' between the corresponding `span.outcome_evaluation_start` and `span.outcome_evaluation_end` events.
12971274
from line 1280
13031280
13041281 0-indexed revision cycle, matching the corresponding `span.outcome_evaluation_start`.
13051282
1283 format: int32
1284
13061285 - `outcome_id: string`
13071286
13081287 The `outc_` ID of the outcome being evaluated.
from line 1290
13111290
13121291 A timestamp in RFC 3339 format
13131292
1293 format: date-time
1294
13141295 - `type: "span.outcome_evaluation_ongoing"`
13151296
1316 - `"span.outcome_evaluation_ongoing"`
1317
1318 - `BetaManagedAgentsUserDefineOutcomeEvent object { id, description, max_iterations, 4 more }`
1297 - `BetaManagedAgentsUserDefineOutcomeEvent object`
13191298
13201299 Echo of a `user.define_outcome` input event. Carries the server-generated `outcome_id` that subsequent `span.outcome_evaluation_*` events reference.
13211300
from line 1310
13311310
13321311 Evaluate-then-revise cycles before giving up. Default 3, max 20.
13331312
1313 format: int32
1314
13341315 - `outcome_id: string`
13351316
13361317 Server-generated `outc_` ID for this outcome. Referenced by `span.outcome_evaluation_*` events and the session's `outcome_evaluations` list.
from line 1320
13391320
13401321 A timestamp in RFC 3339 format
13411322
1323 format: date-time
1324
13421325 - `rubric: BetaManagedAgentsFileRubric or BetaManagedAgentsTextRubric`
13431326
13441327 Rubric for grading the quality of an outcome.
13451328
1346 - `BetaManagedAgentsFileRubric object { file_id, type }`
1329 - `BetaManagedAgentsFileRubric object`
13471330
13481331 Rubric referenced by a file uploaded via the Files API.
13491332
from line 1336
13531336
13541337 - `type: "file"`
13551338
1356 - `"file"`
1357
1358 - `BetaManagedAgentsTextRubric object { content, type }`
1339 - `BetaManagedAgentsTextRubric object`
13591340
13601341 Rubric content provided inline as text.
13611342
from line 1346
13651346
13661347 - `type: "text"`
13671348
1368 - `"text"`
1369
13701349 - `type: "user.define_outcome"`
13711350
1372 - `"user.define_outcome"`
1373
1374 - `BetaManagedAgentsSessionDeletedEvent object { id, processed_at, type }`
1351 - `BetaManagedAgentsSessionDeletedEvent object`
13751352
13761353 Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session.
13771354
from line 1360
13831360
13841361 A timestamp in RFC 3339 format
13851362
1363 format: date-time
1364
13861365 - `type: "session.deleted"`
13871366
1388 - `"session.deleted"`
1389
1390 - `BetaManagedAgentsSessionThreadStatusRunningEvent object { id, agent_name, processed_at, 2 more }`
1367 - `BetaManagedAgentsSessionThreadStatusRunningEvent object`
13911368
13921369 A session thread has begun executing. Emitted on the thread's own stream and cross-posted to the primary stream for child threads.
13931370
from line 1380
14031380
14041381 A timestamp in RFC 3339 format
14051382
1383 format: date-time
1384
14061385 - `session_thread_id: string`
14071386
14081387 Public sthr_ ID of the thread that started running.
14091388
14101389 - `type: "session.thread_status_running"`
14111390
1412 - `"session.thread_status_running"`
1413
1414 - `BetaManagedAgentsSessionThreadStatusIdleEvent object { id, agent_name, processed_at, 3 more }`
1391 - `BetaManagedAgentsSessionThreadStatusIdleEvent object`
14151392
14161393 A session thread has yielded and is awaiting input. Emitted on the thread's own stream and cross-posted to the primary stream for child threads.
14171394
from line 1404
14271404
14281405 A timestamp in RFC 3339 format
14291406
1407 format: date-time
1408
14301409 - `session_thread_id: string`
14311410
14321411 Public sthr_ ID of the thread that went idle.
from line 1414
14351414
14361415 The agent completed its turn naturally and is ready for the next user message.
14371416
1438 - `BetaManagedAgentsSessionEndTurn object { type }`
1417 - `BetaManagedAgentsSessionEndTurn object`
14391418
14401419 The agent completed its turn naturally and is ready for the next user message.
14411420
1442 - `BetaManagedAgentsSessionRequiresAction object { event_ids, type }`
1421 - `BetaManagedAgentsSessionRequiresAction object`
14431422
14441423 The agent is idle waiting on one or more blocking user-input events (tool confirmation, custom tool result, etc.). Resolving all of them transitions the session back to running.
14451424
1446 - `BetaManagedAgentsSessionRetriesExhausted object { type }`
1425 - `BetaManagedAgentsSessionRetriesExhausted object`
14471426
14481427 The turn ended because repeated errors exhausted the retry budget or an error escalated to `retry_status: 'exhausted'`.
14491428
1450 - `BetaManagedAgentsSessionBudgetReached object { type }`
1429 - `BetaManagedAgentsSessionBudgetReached object`
14511430
14521431 The agent stopped because the session's tracked list cost reached its budget, or because its usage includes a model with no list price (which the budget cannot measure). Raise the budget to continue — or, if raising is rejected because a model has no list price, remove the budget.
14531432
14541433 - `type: "session.thread_status_idle"`
14551434
1456 - `"session.thread_status_idle"`
1457
1458 - `BetaManagedAgentsSessionThreadStatusTerminatedEvent object { id, agent_name, processed_at, 2 more }`
1435 - `BetaManagedAgentsSessionThreadStatusTerminatedEvent object`
14591436
14601437 A session thread has terminated and will accept no further input. Emitted on the thread's own stream and cross-posted to the primary stream for child threads.
14611438
from line 1448
14711448
14721449 A timestamp in RFC 3339 format
14731450
1451 format: date-time
1452
14741453 - `session_thread_id: string`
14751454
14761455 Public sthr_ ID of the thread that terminated.
14771456
14781457 - `type: "session.thread_status_terminated"`
14791458
1480 - `"session.thread_status_terminated"`
1481
1482 - `BetaManagedAgentsUserToolResultEvent object { id, tool_use_id, type, 4 more }`
1459 - `BetaManagedAgentsUserToolResultEvent object`
14831460
14841461 Event sent by the client providing the result of an agent-toolset tool execution. Only valid on `self_hosted` environments, where sandbox-routed tools are executed by the client rather than the server.
14851462
from line 1470
14931470
14941471 - `type: "user.tool_result"`
14951472
1496 - `"user.tool_result"`
1497
14981473 - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock`
14991474
15001475 The result content returned by the tool.
15011476
1502 - `BetaManagedAgentsTextBlock object { text, type }`
1477 - `BetaManagedAgentsTextBlock object`
15031478
15041479 Regular text content.
15051480
1506 - `BetaManagedAgentsImageBlock object { source, type }`
1481 - `BetaManagedAgentsImageBlock object`
15071482
15081483 Image content specified directly as base64 data or as a reference via a URL.
15091484
1510 - `BetaManagedAgentsDocumentBlock object { source, type, context, title }`
1485 - `BetaManagedAgentsDocumentBlock object`
15111486
15121487 Document content, either specified directly as base64 data, as text, or as a reference via a URL.
15131488
1514 - `BetaManagedAgentsSearchResultBlock object { citations, content, source, 2 more }`
1489 - `BetaManagedAgentsSearchResultBlock object`
15151490
15161491 A block containing a web search result.
15171492
from line 1498
15231498
15241499 A timestamp in RFC 3339 format
15251500
1501 format: date-time
1502
15261503 - `session_thread_id: optional string or null`
15271504
15281505 Routes this result to a subagent thread. Copy from the `agent.tool_use` event's `session_thread_id`.
15291506
1530 - `BetaManagedAgentsSessionThreadStatusRescheduledEvent object { id, agent_name, processed_at, 2 more }`
1507 - `BetaManagedAgentsSessionThreadStatusRescheduledEvent object`
15311508
15321509 A session thread hit a transient error and is retrying automatically. Emitted on the thread's own stream and cross-posted to the primary stream for child threads.
15331510
from line 1520
15431520
15441521 A timestamp in RFC 3339 format
15451522
1523 format: date-time
1524
15461525 - `session_thread_id: string`
15471526
15481527 Public sthr_ ID of the thread that is retrying.
15491528
15501529 - `type: "session.thread_status_rescheduled"`
15511530
1552 - `"session.thread_status_rescheduled"`
1553
1554 - `BetaManagedAgentsSessionUpdatedEvent object { id, processed_at, type, 4 more }`
1531 - `BetaManagedAgentsSessionUpdatedEvent object`
15551532
15561533 Emitted when an UpdateSession request changed at least one field. Carries only the fields that changed; absent fields were not part of the update. The new configuration applies from the next turn.
15571534
from line 1540
15631540
15641541 A timestamp in RFC 3339 format
15651542
1543 format: date-time
1544
15661545 - `type: "session.updated"`
15671546
1568 - `"session.updated"`
1569
15701547 - `agent: optional BetaManagedAgentsSessionAgent or null`
15711548
15721549 Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time.
from line 1558
15811558
15821559 - `type: "url"`
15831560
1584 - `"url"`
1585
15861561 - `url: string`
15871562
15881563 - `model: BetaManagedAgentsModelConfig`
from line 1634
16591634
16601635 How hard Claude works on each turn. Sets `output_config.effort` on every Messages call the session makes.
16611636
1662 - `BetaManagedAgentsEffortLow object { type }`
1637 - `BetaManagedAgentsEffortLow object`
16631638
16641639 Low effort. Favors latency over reasoning depth.
16651640
16661641 - `type: "low"`
16671642
1668 - `"low"`
1669
1670 - `BetaManagedAgentsEffortMedium object { type }`
1643 - `BetaManagedAgentsEffortMedium object`
16711644
16721645 Medium effort. Balances latency and reasoning depth.
16731646
16741647 - `type: "medium"`
16751648
1676 - `"medium"`
1677
1678 - `BetaManagedAgentsEffortHigh object { type }`
1649 - `BetaManagedAgentsEffortHigh object`
16791650
16801651 High effort. Favors reasoning depth.
16811652
16821653 - `type: "high"`
16831654
1684 - `"high"`
1685
1686 - `BetaManagedAgentsEffortXhigh object { type }`
1655 - `BetaManagedAgentsEffortXhigh object`
16871656
16881657 Extra-high effort. Not all models accept this level.
16891658
16901659 - `type: "xhigh"`
16911660
1692 - `"xhigh"`
1693
1694 - `BetaManagedAgentsEffortMax object { type }`
1661 - `BetaManagedAgentsEffortMax object`
16951662
16961663 Maximum effort. Favors reasoning depth over latency.
16971664
16981665 - `type: "max"`
16991666
1700 - `"max"`
1701
17021667 - `inference_geo: optional string`
17031668
17041669 Geographic region for model inference. When unset, requests fall through to the workspace's default_inference_geo.
from line 1684
17191684
17201685 Full `agent` definitions the coordinator may spawn as session threads.
17211686
1722 - `BetaManagedAgentsSessionThreadAgent object { id, description, mcp_servers, 7 more }`
1687 - `BetaManagedAgentsSessionThreadAgent object`
17231688
17241689 Resolved `agent` definition for a single `session_thread`. Snapshot of the agent at thread creation time. The multiagent roster is not repeated here; read it from `Session.agent`.
17251690
from line 1708
17431708
17441709 - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill`
17451710
1746 - `BetaManagedAgentsAnthropicSkill object { skill_id, type, version }`
1711 - `BetaManagedAgentsAnthropicSkill object`
17471712
17481713 A resolved Anthropic-managed skill.
17491714
from line 1716
17511716
17521717 - `type: "anthropic"`
17531718
1754 - `"anthropic"`
1755
17561719 - `version: string`
17571720
1758 - `BetaManagedAgentsCustomSkill object { skill_id, type, version }`
1721 - `BetaManagedAgentsCustomSkill object`
17591722
17601723 A resolved user-created custom skill.
17611724
from line 1726
17631726
17641727 - `type: "custom"`
17651728
1766 - `"custom"`
1767
17681729 - `version: string`
17691730
17701731 - `system: string or null`
17711732
17721733 - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool`
17731734
1774 - `BetaManagedAgentsAgentToolset20260401 object { configs, default_config, type }`
1735 - `BetaManagedAgentsAgentToolset20260401 object`
17751736
17761737 - `configs: array of BetaManagedAgentsAgentToolConfig`
17771738
1778 - `BetaManagedAgentsBashToolConfig object { enabled, name, permission_policy, type }`
1739 - `BetaManagedAgentsBashToolConfig object`
17791740
17801741 Configuration for the bash tool.
17811742
from line 1744
17831744
17841745 - `name: "bash"`
17851746
1786 - `"bash"`
1787
17881747 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
17891748
17901749 Permission policy for tool execution.
17911750
1792 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
1751 - `BetaManagedAgentsAlwaysAllowPolicy object`
17931752
17941753 Tool calls are automatically approved without user confirmation.
17951754
17961755 - `type: "always_allow"`
17971756
1798 - `"always_allow"`
1799
1800 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
1757 - `BetaManagedAgentsAlwaysAskPolicy object`
18011758
18021759 Tool calls require user confirmation before execution.
18031760
18041761 - `type: "always_ask"`
18051762
1806 - `"always_ask"`
1807
18081763 - `type: "bash"`
18091764
1810 - `"bash"`
1811
1812 - `BetaManagedAgentsEditToolConfig object { enabled, name, permission_policy, type }`
1765 - `BetaManagedAgentsEditToolConfig object`
18131766
18141767 Configuration for the edit tool.
18151768
from line 1770
18171770
18181771 - `name: "edit"`
18191772
1820 - `"edit"`
1821
18221773 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
18231774
18241775 Permission policy for tool execution.
18251776
1826 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
1777 - `BetaManagedAgentsAlwaysAllowPolicy object`
18271778
18281779 Tool calls are automatically approved without user confirmation.
18291780
1830 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
1781 - `BetaManagedAgentsAlwaysAskPolicy object`
18311782
18321783 Tool calls require user confirmation before execution.
18331784
18341785 - `type: "edit"`
18351786
1836 - `"edit"`
1837
1838 - `BetaManagedAgentsReadToolConfig object { enabled, name, permission_policy, type }`
1787 - `BetaManagedAgentsReadToolConfig object`
18391788
18401789 Configuration for the read tool.
18411790
from line 1792
18431792
18441793 - `name: "read"`
18451794
1846 - `"read"`
1847
18481795 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
18491796
18501797 Permission policy for tool execution.
18511798
1852 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
1799 - `BetaManagedAgentsAlwaysAllowPolicy object`
18531800
18541801 Tool calls are automatically approved without user confirmation.
18551802
1856 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
1803 - `BetaManagedAgentsAlwaysAskPolicy object`
18571804
18581805 Tool calls require user confirmation before execution.
18591806
18601807 - `type: "read"`
18611808
1862 - `"read"`
1863
1864 - `BetaManagedAgentsWriteToolConfig object { enabled, name, permission_policy, type }`
1809 - `BetaManagedAgentsWriteToolConfig object`
18651810
18661811 Configuration for the write tool.
18671812
from line 1814
18691814
18701815 - `name: "write"`
18711816
1872 - `"write"`
1873
18741817 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
18751818
18761819 Permission policy for tool execution.
18771820
1878 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
1821 - `BetaManagedAgentsAlwaysAllowPolicy object`
18791822
18801823 Tool calls are automatically approved without user confirmation.
18811824
1882 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
1825 - `BetaManagedAgentsAlwaysAskPolicy object`
18831826
18841827 Tool calls require user confirmation before execution.
18851828
18861829 - `type: "write"`
18871830
1888 - `"write"`
1889
1890 - `BetaManagedAgentsGlobToolConfig object { enabled, name, permission_policy, type }`
1831 - `BetaManagedAgentsGlobToolConfig object`
18911832
18921833 Configuration for the glob tool.
18931834
from line 1836
18951836
18961837 - `name: "glob"`
18971838
1898 - `"glob"`
1899
19001839 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
19011840
19021841 Permission policy for tool execution.
19031842
1904 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
1843 - `BetaManagedAgentsAlwaysAllowPolicy object`
19051844
19061845 Tool calls are automatically approved without user confirmation.
19071846
1908 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
1847 - `BetaManagedAgentsAlwaysAskPolicy object`
19091848
19101849 Tool calls require user confirmation before execution.
19111850
19121851 - `type: "glob"`
19131852
1914 - `"glob"`
1915
1916 - `BetaManagedAgentsGrepToolConfig object { enabled, name, permission_policy, type }`
1853 - `BetaManagedAgentsGrepToolConfig object`
19171854
19181855 Configuration for the grep tool.
19191856
from line 1858
19211858
19221859 - `name: "grep"`
19231860
1924 - `"grep"`
1925
19261861 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
19271862
19281863 Permission policy for tool execution.
19291864
1930 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
1865 - `BetaManagedAgentsAlwaysAllowPolicy object`
19311866
19321867 Tool calls are automatically approved without user confirmation.
19331868
1934 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
1869 - `BetaManagedAgentsAlwaysAskPolicy object`
19351870
19361871 Tool calls require user confirmation before execution.
19371872
19381873 - `type: "grep"`
19391874
1940 - `"grep"`
1941
1942 - `BetaManagedAgentsWebFetchToolConfig object { enabled, name, permission_policy, 4 more }`
1875 - `BetaManagedAgentsWebFetchToolConfig object`
19431876
19441877 Configuration for the web_fetch tool.
19451878
from line 1880
19471880
19481881 - `name: "web_fetch"`
19491882
1950 - `"web_fetch"`
1951
19521883 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
19531884
19541885 Permission policy for tool execution.
19551886
1956 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
1887 - `BetaManagedAgentsAlwaysAllowPolicy object`
19571888
19581889 Tool calls are automatically approved without user confirmation.
19591890
1960 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
1891 - `BetaManagedAgentsAlwaysAskPolicy object`
19611892
19621893 Tool calls require user confirmation before execution.
19631894
19641895 - `type: "web_fetch"`
19651896
1966 - `"web_fetch"`
1967
19681897 - `allowed_domains: optional array of string`
19691898
19701899 - `blocked_domains: optional array of string`
19711900
19721901 - `max_content_tokens: optional number or null`
19731902
1974 - `BetaManagedAgentsWebSearchToolConfig object { enabled, name, permission_policy, 4 more }`
1903 format: int32
1904
1905 - `BetaManagedAgentsWebSearchToolConfig object`
19751906
19761907 Configuration for the web_search tool.
19771908
from line 1910
19791910
19801911 - `name: "web_search"`
19811912
1982 - `"web_search"`
1983
19841913 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
19851914
19861915 Permission policy for tool execution.
19871916
1988 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
1917 - `BetaManagedAgentsAlwaysAllowPolicy object`
19891918
19901919 Tool calls are automatically approved without user confirmation.
19911920
1992 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
1921 - `BetaManagedAgentsAlwaysAskPolicy object`
19931922
19941923 Tool calls require user confirmation before execution.
19951924
19961925 - `type: "web_search"`
19971926
1998 - `"web_search"`
1999
20001927 - `allowed_domains: optional array of string`
20011928
20021929 - `blocked_domains: optional array of string`
from line 1936
20091936
20101937 Location precision. Only "approximate" is supported.
20111938
2012 - `"approximate"`
2013
20141939 - `city: optional string or null`
20151940
20161941 City name.
20171942
1943 minLength: 1, maxLength: 255
1944
20181945 - `country: optional string or null`
20191946
20201947 Two-letter ISO 3166-1 country code, uppercase.
from line 1950
20231950
20241951 Region or state name.
20251952
1953 minLength: 1, maxLength: 255
1954
20261955 - `timezone: optional string or null`
20271956
20281957 IANA timezone identifier, e.g. "America/Los_Angeles".
20291958
1959 minLength: 1, maxLength: 255
1960
20301961 - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig`
20311962
20321963 Resolved default configuration for agent tools.
from line 1968
20371968
20381969 Permission policy for tool execution.
20391970
2040 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
1971 - `BetaManagedAgentsAlwaysAllowPolicy object`
20411972
20421973 Tool calls are automatically approved without user confirmation.
20431974
2044 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
1975 - `BetaManagedAgentsAlwaysAskPolicy object`
20451976
20461977 Tool calls require user confirmation before execution.
20471978
20481979 - `type: "agent_toolset_20260401"`
20491980
2050 - `"agent_toolset_20260401"`
2051
2052 - `BetaManagedAgentsMCPToolset object { configs, default_config, mcp_server_name, type }`
1981 - `BetaManagedAgentsMCPToolset object`
20531982
20541983 - `configs: array of BetaManagedAgentsMCPToolConfig`
20551984
from line 1990
20611990
20621991 Permission policy for tool execution.
20631992
2064 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
1993 - `BetaManagedAgentsAlwaysAllowPolicy object`
20651994
20661995 Tool calls are automatically approved without user confirmation.
20671996
2068 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
1997 - `BetaManagedAgentsAlwaysAskPolicy object`
20691998
20701999 Tool calls require user confirmation before execution.
20712000
from line 2008
20792008
20802009 Permission policy for tool execution.
20812010
2082 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
2011 - `BetaManagedAgentsAlwaysAllowPolicy object`
20832012
20842013 Tool calls are automatically approved without user confirmation.
20852014
2086 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
2015 - `BetaManagedAgentsAlwaysAskPolicy object`
20872016
20882017 Tool calls require user confirmation before execution.
20892018
from line 2020
20912020
20922021 - `type: "mcp_toolset"`
20932022
2094 - `"mcp_toolset"`
2095
2096 - `BetaManagedAgentsCustomTool object { description, input_schema, name, type }`
2023 - `BetaManagedAgentsCustomTool object`
20972024
20982025 A custom tool as returned in API responses.
20992026
from line 2032
21052032
21062033 - `type: "object"`
21072034
2108 - `"object"`
2109
21102035 - `properties: optional map[unknown] or null`
21112036
21122037 - `required: optional array of string or null`
from line 2040
21152040
21162041 - `type: "custom"`
21172042
2118 - `"custom"`
2119
21202043 - `type: "agent"`
21212044
2122 - `"agent"`
2123
21242045 - `version: number`
21252046
2126 - `BetaManagedAgentsAdvisor object { model, type }`
2047 format: int32
2048
2049 - `BetaManagedAgentsAdvisor object`
21272050
21282051 Platform advisor roster entry: a model the session's primary thread may consult mid-turn.
21292052
from line 2056
21332056
21342057 - `type: "advisor"`
21352058
2136 - `"advisor"`
2137
21382059 - `type: "coordinator"`
21392060
2140 - `"coordinator"`
2141
21422061 - `name: string`
21432062
21442063 - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill`
21452064
2146 - `BetaManagedAgentsAnthropicSkill object { skill_id, type, version }`
2065 - `BetaManagedAgentsAnthropicSkill object`
21472066
21482067 A resolved Anthropic-managed skill.
21492068
2150 - `BetaManagedAgentsCustomSkill object { skill_id, type, version }`
2069 - `BetaManagedAgentsCustomSkill object`
21512070
21522071 A resolved user-created custom skill.
21532072
from line 2074
21552074
21562075 - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool`
21572076
2158 - `BetaManagedAgentsAgentToolset20260401 object { configs, default_config, type }`
2159
2160 - `BetaManagedAgentsMCPToolset object { configs, default_config, mcp_server_name, type }`
2161
2162 - `BetaManagedAgentsCustomTool object { description, input_schema, name, type }`
2077 - `BetaManagedAgentsAgentToolset20260401 object`
2078
2079 - `BetaManagedAgentsMCPToolset object`
2080
2081 - `BetaManagedAgentsCustomTool object`
21632082
21642083 A custom tool as returned in API responses.
21652084
21662085 - `type: "agent"`
21672086
2168 - `"agent"`
2169
21702087 - `version: number`
21712088
2089 format: int32
2090
21722091 - `budget: optional BetaManagedAgentsBudgetLimit or null`
21732092
21742093 A hard spend ceiling. The session stops issuing new model requests once the tracked list cost reaches `max_list_cost`.
from line 2104
21852104
21862105 Uppercase ISO-4217 currency code. `USD` is the only currency currently supported; the accepted set is closed and grows only when a new currency is priced.
21872106
2188 - `"USD"`
2189
21902107 - `type: "limit"`
21912108
2192 - `"limit"`
2193
21942109 - `metadata: optional map[string]`
21952110
21962111 The session's full metadata bag after the update. Present when the update set non-empty metadata; absent when metadata was unchanged or cleared to empty.
from line 2114
21992114
22002115 The session's new title. Present only when the update changed it.
22012116
2202 - `BetaManagedAgentsStartEvent object { event, type }`
2117 - `BetaManagedAgentsStartEvent object`
22032118
22042119 Opens a preview of a buffered event. Carries the previewed event's type and id only. Followed by zero or more event_delta events with the same event id, normally concluded by the buffered event carrying that id. If the producing model request ends without that event (an error or interrupt mid-stream), its terminal span.model_request_end closes the preview. Only sent on stream connections that opt in via event_deltas; never appears in event history.
22052120
from line 2122
22072122
22082123 The previewed event's type and id. The event type determines which delta types the preview's event_delta events carry: agent.message events stream content_delta fragments; agent.thinking previews are start-only — no deltas follow, and the buffered agent.thinking with the same id concludes them.
22092124
2210 - `BetaManagedAgentsAgentMessagePreview object { id, type }`
2125 - `BetaManagedAgentsAgentMessagePreview object`
22112126
22122127 - `id: string`
22132128
from line 2130
22152130
22162131 - `type: "agent.message"`
22172132
2218 - `"agent.message"`
2219
2220 - `BetaManagedAgentsAgentThinkingPreview object { id, type }`
2133 - `BetaManagedAgentsAgentThinkingPreview object`
22212134
22222135 - `id: string`
22232136
from line 2138
22252138
22262139 - `type: "agent.thinking"`
22272140
2228 - `"agent.thinking"`
2229
22302141 - `type: "event_start"`
22312142
2232 - `"event_start"`
2233
2234 - `BetaManagedAgentsDeltaEvent object { delta, event_id, type }`
2143 - `BetaManagedAgentsDeltaEvent object`
22352144
22362145 An incremental update to an event that is still being streamed. Deltas are best-effort and may stop early; when the buffered event with id == event_id is produced it carries the complete content. A model request that ends early (an error or interrupt) produces no buffered event — its terminal span.model_request_end closes the preview. Only sent on stream connections that opt in via event_deltas; never appears in event history.
22372146
from line 2154
22452154
22462155 - `type: "content_delta"`
22472156
2248 - `"content_delta"`
2249
22502157 - `index: optional number`
22512158
22522159 Which entry in the previewed event's content array this fragment lands in. Insert content as that entry when the index is new; append to the existing entry otherwise.
22532160
2161 format: uint32
2162
22542163 - `event_id: string`
22552164
22562165 The id of the event being previewed. Matches event.id on the corresponding event_start and the buffered event that reconciles the preview.
22572166
22582167 - `type: "event_delta"`
22592168
2260 - `"event_delta"`
2261
2262 - `BetaManagedAgentsSystemMessageEvent object { id, content, type, processed_at }`
2169 - `BetaManagedAgentsSystemMessageEvent object`
22632170
22642171 A mid-conversation system message event. Carries system-role content that is appended to the session as a `role: "system"` turn.
22652172
from line 2182
22752182
22762183 The text content.
22772184
2185 minLength: 1
2186
22782187 - `type: "text"`
22792188
2280 - `"text"`
2281
22822189 - `type: "system.message"`
22832190
2284 - `"system.message"`
2285
22862191 - `processed_at: optional string or null`
22872192
22882193 A timestamp in RFC 3339 format
22892194
2290 - `BetaManagedAgentsSessionUsageEvent object { id, processed_at, type, 2 more }`
2195 format: date-time
2196
2197 - `BetaManagedAgentsSessionUsageEvent object`
22912198
22922199 Periodic snapshot of the session's cumulative usage and tracked list cost.
22932200
from line 2206
22992206
23002207 A timestamp in RFC 3339 format
23012208
2209 format: date-time
2210
23022211 - `type: "session.usage"`
23032212
2304 - `"session.usage"`
2305
23062213 - `usage: BetaManagedAgentsSessionUsageSnapshot`
23072214
23082215 Point-in-time snapshot of a session's cumulative usage.
from line 2218
23112218
23122219 Cumulative time in seconds during which the session had at least one thread in running status. Overlapping activity from concurrent threads is counted once. This is the duration the session's runtime cost is priced on.
23132220
2221 format: double
2222
23142223 - `cache_creation: optional BetaManagedAgentsCacheCreationUsage`
23152224
23162225 Prompt-cache creation token usage broken down by cache lifetime.
from line 2228
23192228
23202229 Tokens used to create 1-hour ephemeral cache entries.
23212230
2231 format: int32
2232
23222233 - `ephemeral_5m_input_tokens: optional number`
23232234
23242235 Tokens used to create 5-minute ephemeral cache entries.
23252236
2237 format: int32
2238
23262239 - `cache_read_input_tokens: optional number`
23272240
23282241 Total tokens read from prompt cache.
23292242
2243 format: int32
2244
23302245 - `input_tokens: optional number`
23312246
23322247 Total input tokens consumed across all turns.
23332248
2249 format: int32
2250
23342251 - `list_cost: optional BetaMonetaryAmount`
23352252
23362253 A monetary amount in a specific currency.
from line 2256
23392256
23402257 Total output tokens generated across all turns.
23412258
2259 format: int32
2260
23422261 - `server_tool_use: optional BetaManagedAgentsServerToolUsage`
23432262
23442263 Cumulative count of server-executed tool invocations, broken down by tool.
from line 2266
23472266
23482267 Number of server-executed web fetch requests.
23492268
2269 format: int32
2270
23502271 - `web_search_requests: optional number`
23512272
23522273 Number of server-executed web search requests.
23532274
2275 format: int32
2276
23542277 - `budget: optional BetaManagedAgentsBudgetLimit or null`
23552278
23562279 A hard spend ceiling. The session stops issuing new model requests once the tracked list cost reaches `max_list_cost`.
23572280
2358### Example
2359
2360```http
2281- `BetaManagedAgentsStreamSessionThreadEvents = BetaManagedAgentsUserMessageEvent or BetaManagedAgentsUserInterruptEvent or BetaManagedAgentsUserToolConfirmationEvent or 34 more`
2282
2283 Server-sent event in a single thread's stream.
2284
2285## Example
2286
2287```bash
23612288curl https://api.anthropic.com/v1/sessions/$SESSION_ID/threads/$THREAD_ID/stream \
23622289 -H 'anthropic-version: 2023-06-01' \
23632290 -H 'anthropic-beta: managed-agents-2026-04-01' \
23642291 -H "X-Api-Key: $ANTHROPIC_API_KEY"
23652292```
23662293
2367#### Response
2294### Response (200)
23682295
23692296```json
23702297{
23712298
No line in this hunk matches that.