Stream Events changedapi/beta/sessions/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 Events ## Path parameters ## Query parameters ## Headers ## Returns ## Example ### Response (200) ## Stream 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 Events
3url: https://platform.claude.com/docs/en/api/beta/sessions/events/stream
4---
5
6## Stream Events
7
8**get** `/v1/sessions/{session_id}/events/stream`
1# Stream Events
2
3**GET** `/v1/sessions/{session_id}/events/stream`
94
105Stream Events
116
12### Path Parameters
7## Path parameters
138
149- `session_id: string`
1510
16### Query Parameters
11## Query parameters
1712
1813- `event_deltas: optional array of BetaManagedAgentsDeltaType`
1914
from line 18
2318
2419 - `"agent.thinking"`
2520
26### Header Parameters
21## Headers
2722
2823- `"anthropic-beta": optional array of AnthropicBeta`
2924
from line 96
10196
10297 - `"mid-conversation-tool-changes-2026-07-01"`
10398
104### Returns
99## Returns
105100
106101- `BetaManagedAgentsStreamSessionEvents = BetaManagedAgentsUserMessageEvent or BetaManagedAgentsUserInterruptEvent or BetaManagedAgentsUserToolConfirmationEvent or 34 more`
107102
108103 Server-sent event in the session stream.
109104
110 - `BetaManagedAgentsUserMessageEvent object { id, content, type, processed_at }`
105 - `BetaManagedAgentsUserMessageEvent object`
111106
112107 A user message event in the session conversation.
113108
from line 114
119114
120115 Array of content blocks comprising the user message.
121116
122 - `BetaManagedAgentsTextBlock object { text, type }`
117 - `BetaManagedAgentsTextBlock object`
123118
124119 Regular text content.
125120
from line 122
127122
128123 The text content.
129124
125 minLength: 1
126
130127 - `type: "text"`
131128
132 - `"text"`
133
134 - `BetaManagedAgentsImageBlock object { source, type }`
129 - `BetaManagedAgentsImageBlock object`
135130
136131 Image content specified directly as base64 data or as a reference via a URL.
137132
from line 134
139134
140135 Union type for image source variants.
141136
142 - `BetaManagedAgentsBase64ImageSource object { data, media_type, type }`
137 - `BetaManagedAgentsBase64ImageSource object`
143138
144139 Base64-encoded image data.
145140
from line 142
147142
148143 Base64-encoded image data.
149144
145 minLength: 1
146
150147 - `media_type: string`
151148
152149 MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp").
153150
151 minLength: 1
152
154153 - `type: "base64"`
155154
156 - `"base64"`
157
158 - `BetaManagedAgentsURLImageSource object { type, url }`
155 - `BetaManagedAgentsURLImageSource object`
159156
160157 Image referenced by URL.
161158
162159 - `type: "url"`
163160
164 - `"url"`
165
166161 - `url: string`
167162
168163 URL of the image to fetch.
169164
170 - `BetaManagedAgentsFileImageSource object { file_id, type }`
165 minLength: 1
166
167 - `BetaManagedAgentsFileImageSource object`
171168
172169 Image referenced by file ID.
173170
from line 172
175172
176173 ID of a previously uploaded file.
177174
175 minLength: 1
176
178177 - `type: "file"`
179178
180 - `"file"`
181
182179 - `type: "image"`
183180
184 - `"image"`
185
186 - `BetaManagedAgentsDocumentBlock object { source, type, context, title }`
181 - `BetaManagedAgentsDocumentBlock object`
187182
188183 Document content, either specified directly as base64 data, as text, or as a reference via a URL.
189184
from line 186
191186
192187 Union type for document source variants.
193188
194 - `BetaManagedAgentsBase64DocumentSource object { data, media_type, type }`
189 - `BetaManagedAgentsBase64DocumentSource object`
195190
196191 Base64-encoded document data.
197192
from line 194
199194
200195 Base64-encoded document data.
201196
197 minLength: 1
198
202199 - `media_type: string`
203200
204201 MIME type of the document (e.g., "application/pdf").
205202
203 minLength: 1
204
206205 - `type: "base64"`
207206
208 - `"base64"`
209
210 - `BetaManagedAgentsPlainTextDocumentSource object { data, media_type, type }`
207 - `BetaManagedAgentsPlainTextDocumentSource object`
211208
212209 Plain text document content.
213210
from line 212
215212
216213 The plain text content.
217214
215 minLength: 1
216
218217 - `media_type: "text/plain"`
219218
220219 MIME type of the text content. Must be "text/plain".
221220
222 - `"text/plain"`
223
224221 - `type: "text"`
225222
226 - `"text"`
227
228 - `BetaManagedAgentsURLDocumentSource object { type, url }`
223 - `BetaManagedAgentsURLDocumentSource object`
229224
230225 Document referenced by URL.
231226
232227 - `type: "url"`
233228
234 - `"url"`
235
236229 - `url: string`
237230
238231 URL of the document to fetch.
239232
240 - `BetaManagedAgentsFileDocumentSource object { file_id, type }`
233 minLength: 1
234
235 - `BetaManagedAgentsFileDocumentSource object`
241236
242237 Document referenced by file ID.
243238
from line 240
245240
246241 ID of a previously uploaded file.
247242
243 minLength: 1
244
248245 - `type: "file"`
249246
250 - `"file"`
251
252247 - `type: "document"`
253248
254 - `"document"`
255
256249 - `context: optional string or null`
257250
258251 Additional context about the document for the model.
from line 254
261254
262255 The title of the document.
263256
264 - `BetaManagedAgentsRedactedBlock object { type }`
257 - `BetaManagedAgentsRedactedBlock object`
265258
266259 Placeholder for content withheld by Anthropic model policy.
267260
268261 - `type: "redacted"`
269262
270 - `"redacted"`
271
272263 - `type: "user.message"`
273264
274 - `"user.message"`
275
276265 - `processed_at: optional string or null`
277266
278267 A timestamp in RFC 3339 format
279268
280 - `BetaManagedAgentsUserInterruptEvent object { id, type, processed_at, session_thread_id }`
269 format: date-time
270
271 - `BetaManagedAgentsUserInterruptEvent object`
281272
282273 An interrupt event that pauses agent execution and returns control to the user.
283274
from line 278
287278
288279 - `type: "user.interrupt"`
289280
290 - `"user.interrupt"`
291
292281 - `processed_at: optional string or null`
293282
294283 A timestamp in RFC 3339 format
295284
285 format: date-time
286
296287 - `session_thread_id: optional string or null`
297288
298289 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.
299290
300 - `BetaManagedAgentsUserToolConfirmationEvent object { id, result, tool_use_id, 4 more }`
291 - `BetaManagedAgentsUserToolConfirmationEvent object`
301292
302293 A tool confirmation event that approves or denies a pending tool execution.
303294
from line 310
319310
320311 - `type: "user.tool_confirmation"`
321312
322 - `"user.tool_confirmation"`
323
324313 - `deny_message: optional string or null`
325314
326315 Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'.
327316
317 maxLength: 10000
318
328319 - `processed_at: optional string or null`
329320
330321 A timestamp in RFC 3339 format
331322
323 format: date-time
324
332325 - `session_thread_id: optional string or null`
333326
334327 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.
335328
336 - `BetaManagedAgentsUserCustomToolResultEvent object { id, custom_tool_use_id, type, 4 more }`
329 - `BetaManagedAgentsUserCustomToolResultEvent object`
337330
338331 Event sent by the client providing the result of a custom tool execution.
339332
from line 340
347340
348341 - `type: "user.custom_tool_result"`
349342
350 - `"user.custom_tool_result"`
351
352343 - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock`
353344
354345 The result content returned by the tool.
355346
356 - `BetaManagedAgentsTextBlock object { text, type }`
347 - `BetaManagedAgentsTextBlock object`
357348
358349 Regular text content.
359350
360 - `BetaManagedAgentsImageBlock object { source, type }`
351 - `BetaManagedAgentsImageBlock object`
361352
362353 Image content specified directly as base64 data or as a reference via a URL.
363354
364 - `BetaManagedAgentsDocumentBlock object { source, type, context, title }`
355 - `BetaManagedAgentsDocumentBlock object`
365356
366357 Document content, either specified directly as base64 data, as text, or as a reference via a URL.
367358
368 - `BetaManagedAgentsSearchResultBlock object { citations, content, source, 2 more }`
359 - `BetaManagedAgentsSearchResultBlock object`
369360
370361 A block containing a web search result.
371362
from line 376
385376
386377 The text content.
387378
379 minLength: 1
380
388381 - `type: "text"`
389382
390 - `"text"`
391
392383 - `source: string`
393384
394385 The URL source of the search result.
395386
387 minLength: 1
388
396389 - `title: string`
397390
398391 The title of the search result.
399392
393 minLength: 1
394
400395 - `type: "search_result"`
401396
402 - `"search_result"`
403
404397 - `is_error: optional boolean or null`
405398
406399 Whether the tool execution resulted in an error.
from line 402
409402
410403 A timestamp in RFC 3339 format
411404
405 format: date-time
406
412407 - `session_thread_id: optional string or null`
413408
414409 Routes this result to a subagent thread. Copy from the `agent.custom_tool_use` event's `session_thread_id`.
415410
416 - `BetaManagedAgentsAgentCustomToolUseEvent object { id, input, name, 3 more }`
411 - `BetaManagedAgentsAgentCustomToolUseEvent object`
417412
418413 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.
419414
from line 428
433428
434429 A timestamp in RFC 3339 format
435430
431 format: date-time
432
436433 - `type: "agent.custom_tool_use"`
437434
438 - `"agent.custom_tool_use"`
439
440435 - `session_thread_id: optional string or null`
441436
442437 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.
443438
444 - `BetaManagedAgentsAgentMessageEvent object { id, content, processed_at, type }`
439 - `BetaManagedAgentsAgentMessageEvent object`
445440
446441 An agent response event in the session conversation.
447442
from line 448
453448
454449 Array of text blocks comprising the agent response.
455450
456 - `BetaManagedAgentsTextBlock object { text, type }`
451 - `BetaManagedAgentsTextBlock object`
457452
458453 Regular text content.
459454
460 - `BetaManagedAgentsRedactedBlock object { type }`
455 - `BetaManagedAgentsRedactedBlock object`
461456
462457 Placeholder for content withheld by Anthropic model policy.
463458
from line 460
465460
466461 A timestamp in RFC 3339 format
467462
463 format: date-time
464
468465 - `type: "agent.message"`
469466
470 - `"agent.message"`
471
472 - `BetaManagedAgentsAgentThinkingEvent object { id, processed_at, type }`
467 - `BetaManagedAgentsAgentThinkingEvent object`
473468
474469 Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier.
475470
from line 476
481476
482477 A timestamp in RFC 3339 format
483478
479 format: date-time
480
484481 - `type: "agent.thinking"`
485482
486 - `"agent.thinking"`
487
488 - `BetaManagedAgentsAgentMCPToolUseEvent object { id, input, mcp_server_name, 5 more }`
483 - `BetaManagedAgentsAgentMCPToolUseEvent object`
489484
490485 Event emitted when the agent invokes a tool provided by an MCP server.
491486
from line 504
509504
510505 A timestamp in RFC 3339 format
511506
507 format: date-time
508
512509 - `type: "agent.mcp_tool_use"`
513510
514 - `"agent.mcp_tool_use"`
515
516511 - `evaluated_permission: optional "allow" or "ask" or "deny"`
517512
518513 AgentEvaluatedPermission enum
from line 522
527522
528523 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.
529524
530 - `BetaManagedAgentsAgentMCPToolResultEvent object { id, mcp_tool_use_id, processed_at, 3 more }`
525 - `BetaManagedAgentsAgentMCPToolResultEvent object`
531526
532527 Event representing the result of an MCP tool execution.
533528
from line 538
543538
544539 A timestamp in RFC 3339 format
545540
541 format: date-time
542
546543 - `type: "agent.mcp_tool_result"`
547544
548 - `"agent.mcp_tool_result"`
549
550545 - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock`
551546
552547 The result content returned by the tool.
553548
554 - `BetaManagedAgentsTextBlock object { text, type }`
549 - `BetaManagedAgentsTextBlock object`
555550
556551 Regular text content.
557552
558 - `BetaManagedAgentsImageBlock object { source, type }`
553 - `BetaManagedAgentsImageBlock object`
559554
560555 Image content specified directly as base64 data or as a reference via a URL.
561556
562 - `BetaManagedAgentsDocumentBlock object { source, type, context, title }`
557 - `BetaManagedAgentsDocumentBlock object`
563558
564559 Document content, either specified directly as base64 data, as text, or as a reference via a URL.
565560
566 - `BetaManagedAgentsSearchResultBlock object { citations, content, source, 2 more }`
561 - `BetaManagedAgentsSearchResultBlock object`
567562
568563 A block containing a web search result.
569564
from line 566
571566
572567 Whether the tool execution resulted in an error.
573568
574 - `BetaManagedAgentsAgentToolUseEvent object { id, input, name, 4 more }`
569 - `BetaManagedAgentsAgentToolUseEvent object`
575570
576571 Event emitted when the agent invokes a built-in agent tool.
577572
from line 586
591586
592587 A timestamp in RFC 3339 format
593588
589 format: date-time
590
594591 - `type: "agent.tool_use"`
595592
596 - `"agent.tool_use"`
597
598593 - `evaluated_permission: optional "allow" or "ask" or "deny"`
599594
600595 AgentEvaluatedPermission enum
from line 604
609604
610605 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.
611606
612 - `BetaManagedAgentsAgentToolResultEvent object { id, processed_at, tool_use_id, 3 more }`
607 - `BetaManagedAgentsAgentToolResultEvent object`
613608
614609 Event representing the result of an agent tool execution.
615610
from line 616
621616
622617 A timestamp in RFC 3339 format
623618
619 format: date-time
620
624621 - `tool_use_id: string`
625622
626623 The id of the `agent.tool_use` event this result corresponds to.
627624
628625 - `type: "agent.tool_result"`
629626
630 - `"agent.tool_result"`
631
632627 - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock`
633628
634629 The result content returned by the tool.
635630
636 - `BetaManagedAgentsTextBlock object { text, type }`
631 - `BetaManagedAgentsTextBlock object`
637632
638633 Regular text content.
639634
640 - `BetaManagedAgentsImageBlock object { source, type }`
635 - `BetaManagedAgentsImageBlock object`
641636
642637 Image content specified directly as base64 data or as a reference via a URL.
643638
644 - `BetaManagedAgentsDocumentBlock object { source, type, context, title }`
639 - `BetaManagedAgentsDocumentBlock object`
645640
646641 Document content, either specified directly as base64 data, as text, or as a reference via a URL.
647642
648 - `BetaManagedAgentsSearchResultBlock object { citations, content, source, 2 more }`
643 - `BetaManagedAgentsSearchResultBlock object`
649644
650645 A block containing a web search result.
651646
from line 648
653648
654649 Whether the tool execution resulted in an error.
655650
656 - `BetaManagedAgentsAgentThreadMessageReceivedEvent object { id, content, from_session_thread_id, 3 more }`
651 - `BetaManagedAgentsAgentThreadMessageReceivedEvent object`
657652
658653 Delivery event written to the target thread's input stream when an agent-to-agent message arrives.
659654
from line 660
665660
666661 Message content blocks.
667662
668 - `BetaManagedAgentsTextBlock object { text, type }`
663 - `BetaManagedAgentsTextBlock object`
669664
670665 Regular text content.
671666
672 - `BetaManagedAgentsImageBlock object { source, type }`
667 - `BetaManagedAgentsImageBlock object`
673668
674669 Image content specified directly as base64 data or as a reference via a URL.
675670
676 - `BetaManagedAgentsDocumentBlock object { source, type, context, title }`
671 - `BetaManagedAgentsDocumentBlock object`
677672
678673 Document content, either specified directly as base64 data, as text, or as a reference via a URL.
679674
680 - `BetaManagedAgentsRedactedBlock object { type }`
675 - `BetaManagedAgentsRedactedBlock object`
681676
682677 Placeholder for content withheld by Anthropic model policy.
683678
from line 684
689684
690685 A timestamp in RFC 3339 format
691686
687 format: date-time
688
692689 - `type: "agent.thread_message_received"`
693690
694 - `"agent.thread_message_received"`
695
696691 - `from_agent_name: optional string or null`
697692
698693 Name of the callable agent this message came from. Absent when received from the primary agent.
699694
700 - `BetaManagedAgentsAgentThreadMessageSentEvent object { id, content, processed_at, 3 more }`
695 - `BetaManagedAgentsAgentThreadMessageSentEvent object`
701696
702697 Observability event emitted to the sender's output stream when an agent-to-agent message is sent.
703698
from line 704
709704
710705 Message content blocks.
711706
712 - `BetaManagedAgentsTextBlock object { text, type }`
707 - `BetaManagedAgentsTextBlock object`
713708
714709 Regular text content.
715710
716 - `BetaManagedAgentsImageBlock object { source, type }`
711 - `BetaManagedAgentsImageBlock object`
717712
718713 Image content specified directly as base64 data or as a reference via a URL.
719714
720 - `BetaManagedAgentsDocumentBlock object { source, type, context, title }`
715 - `BetaManagedAgentsDocumentBlock object`
721716
722717 Document content, either specified directly as base64 data, as text, or as a reference via a URL.
723718
724 - `BetaManagedAgentsRedactedBlock object { type }`
719 - `BetaManagedAgentsRedactedBlock object`
725720
726721 Placeholder for content withheld by Anthropic model policy.
727722
from line 724
729724
730725 A timestamp in RFC 3339 format
731726
727 format: date-time
728
732729 - `to_session_thread_id: string`
733730
734731 Public `sthr_` ID of the thread the message was sent to.
735732
736733 - `type: "agent.thread_message_sent"`
737734
738 - `"agent.thread_message_sent"`
739
740735 - `to_agent_name: optional string or null`
741736
742737 Name of the callable agent this message was sent to. Absent when sent to the primary agent.
743738
744 - `BetaManagedAgentsAgentThreadContextCompactedEvent object { id, processed_at, type }`
739 - `BetaManagedAgentsAgentThreadContextCompactedEvent object`
745740
746741 Indicates that context compaction (summarization) occurred during the session.
747742
from line 748
753748
754749 A timestamp in RFC 3339 format
755750
751 format: date-time
752
756753 - `type: "agent.thread_context_compacted"`
757754
758 - `"agent.thread_context_compacted"`
759
760 - `BetaManagedAgentsSessionErrorEvent object { id, error, processed_at, type }`
755 - `BetaManagedAgentsSessionErrorEvent object`
761756
762757 An error event indicating a problem occurred during session execution.
763758
from line 764
769764
770765 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.
771766
772 - `BetaManagedAgentsUnknownError object { message, retry_status, type }`
767 - `BetaManagedAgentsUnknownError object`
773768
774769 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.
775770
from line 776
781776
782777 What the client should do next in response to this error.
783778
784 - `BetaManagedAgentsRetryStatusRetrying object { type }`
779 - `BetaManagedAgentsRetryStatusRetrying object`
785780
786781 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.
787782
788783 - `type: "retrying"`
789784
790 - `"retrying"`
791
792 - `BetaManagedAgentsRetryStatusExhausted object { type }`
785 - `BetaManagedAgentsRetryStatusExhausted object`
793786
794787 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
795788
796789 - `type: "exhausted"`
797790
798 - `"exhausted"`
799
800 - `BetaManagedAgentsRetryStatusTerminal object { type }`
791 - `BetaManagedAgentsRetryStatusTerminal object`
801792
802793 The session encountered a terminal error and will transition to `terminated` state.
803794
804795 - `type: "terminal"`
805796
806 - `"terminal"`
807
808797 - `type: "unknown_error"`
809798
810 - `"unknown_error"`
811
812 - `BetaManagedAgentsModelOverloadedError object { message, retry_status, type }`
799 - `BetaManagedAgentsModelOverloadedError object`
813800
814801 The model is currently overloaded. Emitted after automatic retries are exhausted.
815802
from line 808
821808
822809 What the client should do next in response to this error.
823810
824 - `BetaManagedAgentsRetryStatusRetrying object { type }`
811 - `BetaManagedAgentsRetryStatusRetrying object`
825812
826813 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.
827814
828 - `BetaManagedAgentsRetryStatusExhausted object { type }`
815 - `BetaManagedAgentsRetryStatusExhausted object`
829816
830817 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
831818
832 - `BetaManagedAgentsRetryStatusTerminal object { type }`
819 - `BetaManagedAgentsRetryStatusTerminal object`
833820
834821 The session encountered a terminal error and will transition to `terminated` state.
835822
836823 - `type: "model_overloaded_error"`
837824
838 - `"model_overloaded_error"`
839
840 - `BetaManagedAgentsModelRateLimitedError object { message, retry_status, type }`
825 - `BetaManagedAgentsModelRateLimitedError object`
841826
842827 The model request was rate-limited.
843828
from line 834
849834
850835 What the client should do next in response to this error.
851836
852 - `BetaManagedAgentsRetryStatusRetrying object { type }`
837 - `BetaManagedAgentsRetryStatusRetrying object`
853838
854839 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.
855840
856 - `BetaManagedAgentsRetryStatusExhausted object { type }`
841 - `BetaManagedAgentsRetryStatusExhausted object`
857842
858843 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
859844
860 - `BetaManagedAgentsRetryStatusTerminal object { type }`
845 - `BetaManagedAgentsRetryStatusTerminal object`
861846
862847 The session encountered a terminal error and will transition to `terminated` state.
863848
864849 - `type: "model_rate_limited_error"`
865850
866 - `"model_rate_limited_error"`
867
868 - `BetaManagedAgentsModelRequestFailedError object { message, retry_status, type }`
851 - `BetaManagedAgentsModelRequestFailedError object`
869852
870853 A model request failed for a reason other than overload or rate-limiting.
871854
from line 860
877860
878861 What the client should do next in response to this error.
879862
880 - `BetaManagedAgentsRetryStatusRetrying object { type }`
863 - `BetaManagedAgentsRetryStatusRetrying object`
881864
882865 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.
883866
884 - `BetaManagedAgentsRetryStatusExhausted object { type }`
867 - `BetaManagedAgentsRetryStatusExhausted object`
885868
886869 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
887870
888 - `BetaManagedAgentsRetryStatusTerminal object { type }`
871 - `BetaManagedAgentsRetryStatusTerminal object`
889872
890873 The session encountered a terminal error and will transition to `terminated` state.
891874
892875 - `type: "model_request_failed_error"`
893876
894 - `"model_request_failed_error"`
895
896 - `BetaManagedAgentsMCPConnectionFailedError object { mcp_server_name, message, retry_status, type }`
877 - `BetaManagedAgentsMCPConnectionFailedError object`
897878
898879 Failed to connect to an MCP server.
899880
from line 890
909890
910891 What the client should do next in response to this error.
911892
912 - `BetaManagedAgentsRetryStatusRetrying object { type }`
893 - `BetaManagedAgentsRetryStatusRetrying object`
913894
914895 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.
915896
916 - `BetaManagedAgentsRetryStatusExhausted object { type }`
897 - `BetaManagedAgentsRetryStatusExhausted object`
917898
918899 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
919900
920 - `BetaManagedAgentsRetryStatusTerminal object { type }`
901 - `BetaManagedAgentsRetryStatusTerminal object`
921902
922903 The session encountered a terminal error and will transition to `terminated` state.
923904
924905 - `type: "mcp_connection_failed_error"`
925906
926 - `"mcp_connection_failed_error"`
927
928 - `BetaManagedAgentsMCPAuthenticationFailedError object { mcp_server_name, message, retry_status, type }`
907 - `BetaManagedAgentsMCPAuthenticationFailedError object`
929908
930909 Authentication to an MCP server failed.
931910
from line 920
941920
942921 What the client should do next in response to this error.
943922
944 - `BetaManagedAgentsRetryStatusRetrying object { type }`
923 - `BetaManagedAgentsRetryStatusRetrying object`
945924
946925 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.
947926
948 - `BetaManagedAgentsRetryStatusExhausted object { type }`
927 - `BetaManagedAgentsRetryStatusExhausted object`
949928
950929 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
951930
952 - `BetaManagedAgentsRetryStatusTerminal object { type }`
931 - `BetaManagedAgentsRetryStatusTerminal object`
953932
954933 The session encountered a terminal error and will transition to `terminated` state.
955934
956935 - `type: "mcp_authentication_failed_error"`
957936
958 - `"mcp_authentication_failed_error"`
959
960 - `BetaManagedAgentsBillingError object { message, retry_status, type }`
937 - `BetaManagedAgentsBillingError object`
961938
962939 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.
963940
from line 946
969946
970947 What the client should do next in response to this error.
971948
972 - `BetaManagedAgentsRetryStatusRetrying object { type }`
949 - `BetaManagedAgentsRetryStatusRetrying object`
973950
974951 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.
975952
976 - `BetaManagedAgentsRetryStatusExhausted object { type }`
953 - `BetaManagedAgentsRetryStatusExhausted object`
977954
978955 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
979956
980 - `BetaManagedAgentsRetryStatusTerminal object { type }`
957 - `BetaManagedAgentsRetryStatusTerminal object`
981958
982959 The session encountered a terminal error and will transition to `terminated` state.
983960
984961 - `type: "billing_error"`
985962
986 - `"billing_error"`
987
988 - `BetaManagedAgentsCredentialHostUnreachableError object { credential_id, message, retry_status, 2 more }`
963 - `BetaManagedAgentsCredentialHostUnreachableError object`
989964
990965 An `environment_variable` credential's `auth.networking.allowed_hosts` includes a host the environment's network policy does not permit.
991966
from line 976
1001976
1002977 What the client should do next in response to this error.
1003978
1004 - `BetaManagedAgentsRetryStatusRetrying object { type }`
979 - `BetaManagedAgentsRetryStatusRetrying object`
1005980
1006981 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.
1007982
1008 - `BetaManagedAgentsRetryStatusExhausted object { type }`
983 - `BetaManagedAgentsRetryStatusExhausted object`
1009984
1010985 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
1011986
1012 - `BetaManagedAgentsRetryStatusTerminal object { type }`
987 - `BetaManagedAgentsRetryStatusTerminal object`
1013988
1014989 The session encountered a terminal error and will transition to `terminated` state.
1015990
1016991 - `type: "credential_host_unreachable_error"`
1017992
1018 - `"credential_host_unreachable_error"`
1019
1020993 - `vault_id: string`
1021994
1022995 ID of the vault containing the affected credential.
from line 998
1025998
1026999 A timestamp in RFC 3339 format
10271000
1001 format: date-time
1002
10281003 - `type: "session.error"`
10291004
1030 - `"session.error"`
1031
1032 - `BetaManagedAgentsSessionStatusRescheduledEvent object { id, processed_at, type }`
1005 - `BetaManagedAgentsSessionStatusRescheduledEvent object`
10331006
10341007 Indicates the session is recovering from an error state and is rescheduled for execution.
10351008
from line 1014
10411014
10421015 A timestamp in RFC 3339 format
10431016
1017 format: date-time
1018
10441019 - `type: "session.status_rescheduled"`
10451020
1046 - `"session.status_rescheduled"`
1047
1048 - `BetaManagedAgentsSessionStatusRunningEvent object { id, processed_at, type }`
1021 - `BetaManagedAgentsSessionStatusRunningEvent object`
10491022
10501023 Indicates the session is actively running and the agent is working.
10511024
from line 1030
10571030
10581031 A timestamp in RFC 3339 format
10591032
1033 format: date-time
1034
10601035 - `type: "session.status_running"`
10611036
1062 - `"session.status_running"`
1063
1064 - `BetaManagedAgentsSessionStatusIdleEvent object { id, processed_at, stop_reason, type }`
1037 - `BetaManagedAgentsSessionStatusIdleEvent object`
10651038
10661039 Indicates the agent has paused and is awaiting user input.
10671040
from line 1046
10731046
10741047 A timestamp in RFC 3339 format
10751048
1049 format: date-time
1050
10761051 - `stop_reason: BetaManagedAgentsSessionEndTurn or BetaManagedAgentsSessionRequiresAction or BetaManagedAgentsSessionRetriesExhausted or BetaManagedAgentsSessionBudgetReached`
10771052
10781053 The agent completed its turn naturally and is ready for the next user message.
10791054
1080 - `BetaManagedAgentsSessionEndTurn object { type }`
1055 - `BetaManagedAgentsSessionEndTurn object`
10811056
10821057 The agent completed its turn naturally and is ready for the next user message.
10831058
10841059 - `type: "end_turn"`
10851060
1086 - `"end_turn"`
1087
1088 - `BetaManagedAgentsSessionRequiresAction object { event_ids, type }`
1061 - `BetaManagedAgentsSessionRequiresAction object`
10891062
10901063 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.
10911064
from line 1068
10951068
10961069 - `type: "requires_action"`
10971070
1098 - `"requires_action"`
1099
1100 - `BetaManagedAgentsSessionRetriesExhausted object { type }`
1071 - `BetaManagedAgentsSessionRetriesExhausted object`
11011072
11021073 The turn ended because repeated errors exhausted the retry budget or an error escalated to `retry_status: 'exhausted'`.
11031074
11041075 - `type: "retries_exhausted"`
11051076
1106 - `"retries_exhausted"`
1107
1108 - `BetaManagedAgentsSessionBudgetReached object { type }`
1077 - `BetaManagedAgentsSessionBudgetReached object`
11091078
11101079 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.
11111080
11121081 - `type: "budget_reached"`
11131082
1114 - `"budget_reached"`
1115
11161083 - `type: "session.status_idle"`
11171084
1118 - `"session.status_idle"`
1119
1120 - `BetaManagedAgentsSessionStatusTerminatedEvent object { id, processed_at, type }`
1085 - `BetaManagedAgentsSessionStatusTerminatedEvent object`
11211086
11221087 Indicates the session has terminated, either due to an error or completion.
11231088
from line 1094
11291094
11301095 A timestamp in RFC 3339 format
11311096
1097 format: date-time
1098
11321099 - `type: "session.status_terminated"`
11331100
1134 - `"session.status_terminated"`
1135
1136 - `BetaManagedAgentsSessionThreadCreatedEvent object { id, agent_name, processed_at, 2 more }`
1101 - `BetaManagedAgentsSessionThreadCreatedEvent object`
11371102
11381103 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.
11391104
from line 1114
11491114
11501115 A timestamp in RFC 3339 format
11511116
1117 format: date-time
1118
11521119 - `session_thread_id: string`
11531120
11541121 Public `sthr_` ID of the newly created thread.
11551122
11561123 - `type: "session.thread_created"`
11571124
1158 - `"session.thread_created"`
1159
1160 - `BetaManagedAgentsSpanOutcomeEvaluationStartEvent object { id, iteration, outcome_id, 2 more }`
1125 - `BetaManagedAgentsSpanOutcomeEvaluationStartEvent object`
11611126
11621127 Emitted when an outcome evaluation cycle begins.
11631128
from line 1134
11691134
11701135 0-indexed revision cycle. 0 is the first evaluation; 1 is the re-evaluation after the first revision; etc.
11711136
1137 format: int32
1138
11721139 - `outcome_id: string`
11731140
11741141 The `outc_` ID of the outcome being evaluated.
from line 1144
11771144
11781145 A timestamp in RFC 3339 format
11791146
1147 format: date-time
1148
11801149 - `type: "span.outcome_evaluation_start"`
11811150
1182 - `"span.outcome_evaluation_start"`
1183
1184 - `BetaManagedAgentsSpanOutcomeEvaluationEndEvent object { id, explanation, iteration, 6 more }`
1151 - `BetaManagedAgentsSpanOutcomeEvaluationEndEvent object`
11851152
11861153 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.
11871154
from line 1164
11971164
11981165 0-indexed revision cycle, matching the corresponding `span.outcome_evaluation_start`.
11991166
1167 format: int32
1168
12001169 - `outcome_evaluation_start_id: string`
12011170
12021171 The id of the corresponding `span.outcome_evaluation_start` event.
from line 1178
12091178
12101179 A timestamp in RFC 3339 format
12111180
1181 format: date-time
1182
12121183 - `result: string`
12131184
12141185 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.
12151186
12161187 - `type: "span.outcome_evaluation_end"`
12171188
1218 - `"span.outcome_evaluation_end"`
1219
12201189 - `usage: BetaManagedAgentsSpanModelUsage`
12211190
12221191 Token usage for a single model request.
from line 1194
12251194
12261195 Tokens used to create prompt cache in this request.
12271196
1197 format: int32
1198
12281199 - `cache_read_input_tokens: number`
12291200
12301201 Tokens read from prompt cache in this request.
12311202
1203 format: int32
1204
12321205 - `input_tokens: number`
12331206
12341207 Input tokens consumed by this request.
12351208
1209 format: int32
1210
12361211 - `output_tokens: number`
12371212
12381213 Output tokens generated by this request.
12391214
1215 format: int32
1216
12401217 - `speed: optional "standard" or "fast" or null`
12411218
12421219 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 1222
12451222
12461223 - `"fast"`
12471224
1248 - `BetaManagedAgentsSpanModelRequestStartEvent object { id, processed_at, type }`
1225 - `BetaManagedAgentsSpanModelRequestStartEvent object`
12491226
12501227 Emitted when a model request is initiated by the agent.
12511228
from line 1234
12571234
12581235 A timestamp in RFC 3339 format
12591236
1237 format: date-time
1238
12601239 - `type: "span.model_request_start"`
12611240
1262 - `"span.model_request_start"`
1263
1264 - `BetaManagedAgentsSpanModelRequestEndEvent object { id, is_error, model_request_start_id, 3 more }`
1241 - `BetaManagedAgentsSpanModelRequestEndEvent object`
12651242
12661243 Emitted when a model request completes.
12671244
from line 1262
12851262
12861263 A timestamp in RFC 3339 format
12871264
1265 format: date-time
1266
12881267 - `type: "span.model_request_end"`
12891268
1290 - `"span.model_request_end"`
1291
1292 - `BetaManagedAgentsSpanOutcomeEvaluationOngoingEvent object { id, iteration, outcome_id, 2 more }`
1269 - `BetaManagedAgentsSpanOutcomeEvaluationOngoingEvent object`
12931270
12941271 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.
12951272
from line 1278
13011278
13021279 0-indexed revision cycle, matching the corresponding `span.outcome_evaluation_start`.
13031280
1281 format: int32
1282
13041283 - `outcome_id: string`
13051284
13061285 The `outc_` ID of the outcome being evaluated.
from line 1288
13091288
13101289 A timestamp in RFC 3339 format
13111290
1291 format: date-time
1292
13121293 - `type: "span.outcome_evaluation_ongoing"`
13131294
1314 - `"span.outcome_evaluation_ongoing"`
1315
1316 - `BetaManagedAgentsUserDefineOutcomeEvent object { id, description, max_iterations, 4 more }`
1295 - `BetaManagedAgentsUserDefineOutcomeEvent object`
13171296
13181297 Echo of a `user.define_outcome` input event. Carries the server-generated `outcome_id` that subsequent `span.outcome_evaluation_*` events reference.
13191298
from line 1308
13291308
13301309 Evaluate-then-revise cycles before giving up. Default 3, max 20.
13311310
1311 format: int32
1312
13321313 - `outcome_id: string`
13331314
13341315 Server-generated `outc_` ID for this outcome. Referenced by `span.outcome_evaluation_*` events and the session's `outcome_evaluations` list.
from line 1318
13371318
13381319 A timestamp in RFC 3339 format
13391320
1321 format: date-time
1322
13401323 - `rubric: BetaManagedAgentsFileRubric or BetaManagedAgentsTextRubric`
13411324
13421325 Rubric for grading the quality of an outcome.
13431326
1344 - `BetaManagedAgentsFileRubric object { file_id, type }`
1327 - `BetaManagedAgentsFileRubric object`
13451328
13461329 Rubric referenced by a file uploaded via the Files API.
13471330
from line 1334
13511334
13521335 - `type: "file"`
13531336
1354 - `"file"`
1355
1356 - `BetaManagedAgentsTextRubric object { content, type }`
1337 - `BetaManagedAgentsTextRubric object`
13571338
13581339 Rubric content provided inline as text.
13591340
from line 1344
13631344
13641345 - `type: "text"`
13651346
1366 - `"text"`
1367
13681347 - `type: "user.define_outcome"`
13691348
1370 - `"user.define_outcome"`
1371
1372 - `BetaManagedAgentsSessionDeletedEvent object { id, processed_at, type }`
1349 - `BetaManagedAgentsSessionDeletedEvent object`
13731350
13741351 Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session.
13751352
from line 1358
13811358
13821359 A timestamp in RFC 3339 format
13831360
1361 format: date-time
1362
13841363 - `type: "session.deleted"`
13851364
1386 - `"session.deleted"`
1387
1388 - `BetaManagedAgentsSessionThreadStatusRunningEvent object { id, agent_name, processed_at, 2 more }`
1365 - `BetaManagedAgentsSessionThreadStatusRunningEvent object`
13891366
13901367 A session thread has begun executing. Emitted on the thread's own stream and cross-posted to the primary stream for child threads.
13911368
from line 1378
14011378
14021379 A timestamp in RFC 3339 format
14031380
1381 format: date-time
1382
14041383 - `session_thread_id: string`
14051384
14061385 Public sthr_ ID of the thread that started running.
14071386
14081387 - `type: "session.thread_status_running"`
14091388
1410 - `"session.thread_status_running"`
1411
1412 - `BetaManagedAgentsSessionThreadStatusIdleEvent object { id, agent_name, processed_at, 3 more }`
1389 - `BetaManagedAgentsSessionThreadStatusIdleEvent object`
14131390
14141391 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.
14151392
from line 1402
14251402
14261403 A timestamp in RFC 3339 format
14271404
1405 format: date-time
1406
14281407 - `session_thread_id: string`
14291408
14301409 Public sthr_ ID of the thread that went idle.
from line 1412
14331412
14341413 The agent completed its turn naturally and is ready for the next user message.
14351414
1436 - `BetaManagedAgentsSessionEndTurn object { type }`
1415 - `BetaManagedAgentsSessionEndTurn object`
14371416
14381417 The agent completed its turn naturally and is ready for the next user message.
14391418
1440 - `BetaManagedAgentsSessionRequiresAction object { event_ids, type }`
1419 - `BetaManagedAgentsSessionRequiresAction object`
14411420
14421421 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.
14431422
1444 - `BetaManagedAgentsSessionRetriesExhausted object { type }`
1423 - `BetaManagedAgentsSessionRetriesExhausted object`
14451424
14461425 The turn ended because repeated errors exhausted the retry budget or an error escalated to `retry_status: 'exhausted'`.
14471426
1448 - `BetaManagedAgentsSessionBudgetReached object { type }`
1427 - `BetaManagedAgentsSessionBudgetReached object`
14491428
14501429 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.
14511430
14521431 - `type: "session.thread_status_idle"`
14531432
1454 - `"session.thread_status_idle"`
1455
1456 - `BetaManagedAgentsSessionThreadStatusTerminatedEvent object { id, agent_name, processed_at, 2 more }`
1433 - `BetaManagedAgentsSessionThreadStatusTerminatedEvent object`
14571434
14581435 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.
14591436
from line 1446
14691446
14701447 A timestamp in RFC 3339 format
14711448
1449 format: date-time
1450
14721451 - `session_thread_id: string`
14731452
14741453 Public sthr_ ID of the thread that terminated.
14751454
14761455 - `type: "session.thread_status_terminated"`
14771456
1478 - `"session.thread_status_terminated"`
1479
1480 - `BetaManagedAgentsUserToolResultEvent object { id, tool_use_id, type, 4 more }`
1457 - `BetaManagedAgentsUserToolResultEvent object`
14811458
14821459 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.
14831460
from line 1468
14911468
14921469 - `type: "user.tool_result"`
14931470
1494 - `"user.tool_result"`
1495
14961471 - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock`
14971472
14981473 The result content returned by the tool.
14991474
1500 - `BetaManagedAgentsTextBlock object { text, type }`
1475 - `BetaManagedAgentsTextBlock object`
15011476
15021477 Regular text content.
15031478
1504 - `BetaManagedAgentsImageBlock object { source, type }`
1479 - `BetaManagedAgentsImageBlock object`
15051480
15061481 Image content specified directly as base64 data or as a reference via a URL.
15071482
1508 - `BetaManagedAgentsDocumentBlock object { source, type, context, title }`
1483 - `BetaManagedAgentsDocumentBlock object`
15091484
15101485 Document content, either specified directly as base64 data, as text, or as a reference via a URL.
15111486
1512 - `BetaManagedAgentsSearchResultBlock object { citations, content, source, 2 more }`
1487 - `BetaManagedAgentsSearchResultBlock object`
15131488
15141489 A block containing a web search result.
15151490
from line 1496
15211496
15221497 A timestamp in RFC 3339 format
15231498
1499 format: date-time
1500
15241501 - `session_thread_id: optional string or null`
15251502
15261503 Routes this result to a subagent thread. Copy from the `agent.tool_use` event's `session_thread_id`.
15271504
1528 - `BetaManagedAgentsSessionThreadStatusRescheduledEvent object { id, agent_name, processed_at, 2 more }`
1505 - `BetaManagedAgentsSessionThreadStatusRescheduledEvent object`
15291506
15301507 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.
15311508
from line 1518
15411518
15421519 A timestamp in RFC 3339 format
15431520
1521 format: date-time
1522
15441523 - `session_thread_id: string`
15451524
15461525 Public sthr_ ID of the thread that is retrying.
15471526
15481527 - `type: "session.thread_status_rescheduled"`
15491528
1550 - `"session.thread_status_rescheduled"`
1551
1552 - `BetaManagedAgentsSessionUpdatedEvent object { id, processed_at, type, 4 more }`
1529 - `BetaManagedAgentsSessionUpdatedEvent object`
15531530
15541531 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.
15551532
from line 1538
15611538
15621539 A timestamp in RFC 3339 format
15631540
1541 format: date-time
1542
15641543 - `type: "session.updated"`
15651544
1566 - `"session.updated"`
1567
15681545 - `agent: optional BetaManagedAgentsSessionAgent or null`
15691546
15701547 Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time.
from line 1556
15791556
15801557 - `type: "url"`
15811558
1582 - `"url"`
1583
15841559 - `url: string`
15851560
15861561 - `model: BetaManagedAgentsModelConfig`
from line 1632
16571632
16581633 How hard Claude works on each turn. Sets `output_config.effort` on every Messages call the session makes.
16591634
1660 - `BetaManagedAgentsEffortLow object { type }`
1635 - `BetaManagedAgentsEffortLow object`
16611636
16621637 Low effort. Favors latency over reasoning depth.
16631638
16641639 - `type: "low"`
16651640
1666 - `"low"`
1667
1668 - `BetaManagedAgentsEffortMedium object { type }`
1641 - `BetaManagedAgentsEffortMedium object`
16691642
16701643 Medium effort. Balances latency and reasoning depth.
16711644
16721645 - `type: "medium"`
16731646
1674 - `"medium"`
1675
1676 - `BetaManagedAgentsEffortHigh object { type }`
1647 - `BetaManagedAgentsEffortHigh object`
16771648
16781649 High effort. Favors reasoning depth.
16791650
16801651 - `type: "high"`
16811652
1682 - `"high"`
1683
1684 - `BetaManagedAgentsEffortXhigh object { type }`
1653 - `BetaManagedAgentsEffortXhigh object`
16851654
16861655 Extra-high effort. Not all models accept this level.
16871656
16881657 - `type: "xhigh"`
16891658
1690 - `"xhigh"`
1691
1692 - `BetaManagedAgentsEffortMax object { type }`
1659 - `BetaManagedAgentsEffortMax object`
16931660
16941661 Maximum effort. Favors reasoning depth over latency.
16951662
16961663 - `type: "max"`
16971664
1698 - `"max"`
1699
17001665 - `inference_geo: optional string`
17011666
17021667 Geographic region for model inference. When unset, requests fall through to the workspace's default_inference_geo.
from line 1682
17171682
17181683 Full `agent` definitions the coordinator may spawn as session threads.
17191684
1720 - `BetaManagedAgentsSessionThreadAgent object { id, description, mcp_servers, 7 more }`
1685 - `BetaManagedAgentsSessionThreadAgent object`
17211686
17221687 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`.
17231688
from line 1706
17411706
17421707 - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill`
17431708
1744 - `BetaManagedAgentsAnthropicSkill object { skill_id, type, version }`
1709 - `BetaManagedAgentsAnthropicSkill object`
17451710
17461711 A resolved Anthropic-managed skill.
17471712
from line 1714
17491714
17501715 - `type: "anthropic"`
17511716
1752 - `"anthropic"`
1753
17541717 - `version: string`
17551718
1756 - `BetaManagedAgentsCustomSkill object { skill_id, type, version }`
1719 - `BetaManagedAgentsCustomSkill object`
17571720
17581721 A resolved user-created custom skill.
17591722
from line 1724
17611724
17621725 - `type: "custom"`
17631726
1764 - `"custom"`
1765
17661727 - `version: string`
17671728
17681729 - `system: string or null`
17691730
17701731 - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool`
17711732
1772 - `BetaManagedAgentsAgentToolset20260401 object { configs, default_config, type }`
1733 - `BetaManagedAgentsAgentToolset20260401 object`
17731734
17741735 - `configs: array of BetaManagedAgentsAgentToolConfig`
17751736
1776 - `BetaManagedAgentsBashToolConfig object { enabled, name, permission_policy, type }`
1737 - `BetaManagedAgentsBashToolConfig object`
17771738
17781739 Configuration for the bash tool.
17791740
from line 1742
17811742
17821743 - `name: "bash"`
17831744
1784 - `"bash"`
1785
17861745 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
17871746
17881747 Permission policy for tool execution.
17891748
1790 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
1749 - `BetaManagedAgentsAlwaysAllowPolicy object`
17911750
17921751 Tool calls are automatically approved without user confirmation.
17931752
17941753 - `type: "always_allow"`
17951754
1796 - `"always_allow"`
1797
1798 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
1755 - `BetaManagedAgentsAlwaysAskPolicy object`
17991756
18001757 Tool calls require user confirmation before execution.
18011758
18021759 - `type: "always_ask"`
18031760
1804 - `"always_ask"`
1805
18061761 - `type: "bash"`
18071762
1808 - `"bash"`
1809
1810 - `BetaManagedAgentsEditToolConfig object { enabled, name, permission_policy, type }`
1763 - `BetaManagedAgentsEditToolConfig object`
18111764
18121765 Configuration for the edit tool.
18131766
from line 1768
18151768
18161769 - `name: "edit"`
18171770
1818 - `"edit"`
1819
18201771 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
18211772
18221773 Permission policy for tool execution.
18231774
1824 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
1775 - `BetaManagedAgentsAlwaysAllowPolicy object`
18251776
18261777 Tool calls are automatically approved without user confirmation.
18271778
1828 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
1779 - `BetaManagedAgentsAlwaysAskPolicy object`
18291780
18301781 Tool calls require user confirmation before execution.
18311782
18321783 - `type: "edit"`
18331784
1834 - `"edit"`
1835
1836 - `BetaManagedAgentsReadToolConfig object { enabled, name, permission_policy, type }`
1785 - `BetaManagedAgentsReadToolConfig object`
18371786
18381787 Configuration for the read tool.
18391788
from line 1790
18411790
18421791 - `name: "read"`
18431792
1844 - `"read"`
1845
18461793 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
18471794
18481795 Permission policy for tool execution.
18491796
1850 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
1797 - `BetaManagedAgentsAlwaysAllowPolicy object`
18511798
18521799 Tool calls are automatically approved without user confirmation.
18531800
1854 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
1801 - `BetaManagedAgentsAlwaysAskPolicy object`
18551802
18561803 Tool calls require user confirmation before execution.
18571804
18581805 - `type: "read"`
18591806
1860 - `"read"`
1861
1862 - `BetaManagedAgentsWriteToolConfig object { enabled, name, permission_policy, type }`
1807 - `BetaManagedAgentsWriteToolConfig object`
18631808
18641809 Configuration for the write tool.
18651810
from line 1812
18671812
18681813 - `name: "write"`
18691814
1870 - `"write"`
1871
18721815 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
18731816
18741817 Permission policy for tool execution.
18751818
1876 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
1819 - `BetaManagedAgentsAlwaysAllowPolicy object`
18771820
18781821 Tool calls are automatically approved without user confirmation.
18791822
1880 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
1823 - `BetaManagedAgentsAlwaysAskPolicy object`
18811824
18821825 Tool calls require user confirmation before execution.
18831826
18841827 - `type: "write"`
18851828
1886 - `"write"`
1887
1888 - `BetaManagedAgentsGlobToolConfig object { enabled, name, permission_policy, type }`
1829 - `BetaManagedAgentsGlobToolConfig object`
18891830
18901831 Configuration for the glob tool.
18911832
from line 1834
18931834
18941835 - `name: "glob"`
18951836
1896 - `"glob"`
1897
18981837 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
18991838
19001839 Permission policy for tool execution.
19011840
1902 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
1841 - `BetaManagedAgentsAlwaysAllowPolicy object`
19031842
19041843 Tool calls are automatically approved without user confirmation.
19051844
1906 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
1845 - `BetaManagedAgentsAlwaysAskPolicy object`
19071846
19081847 Tool calls require user confirmation before execution.
19091848
19101849 - `type: "glob"`
19111850
1912 - `"glob"`
1913
1914 - `BetaManagedAgentsGrepToolConfig object { enabled, name, permission_policy, type }`
1851 - `BetaManagedAgentsGrepToolConfig object`
19151852
19161853 Configuration for the grep tool.
19171854
from line 1856
19191856
19201857 - `name: "grep"`
19211858
1922 - `"grep"`
1923
19241859 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
19251860
19261861 Permission policy for tool execution.
19271862
1928 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
1863 - `BetaManagedAgentsAlwaysAllowPolicy object`
19291864
19301865 Tool calls are automatically approved without user confirmation.
19311866
1932 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
1867 - `BetaManagedAgentsAlwaysAskPolicy object`
19331868
19341869 Tool calls require user confirmation before execution.
19351870
19361871 - `type: "grep"`
19371872
1938 - `"grep"`
1939
1940 - `BetaManagedAgentsWebFetchToolConfig object { enabled, name, permission_policy, 4 more }`
1873 - `BetaManagedAgentsWebFetchToolConfig object`
19411874
19421875 Configuration for the web_fetch tool.
19431876
from line 1878
19451878
19461879 - `name: "web_fetch"`
19471880
1948 - `"web_fetch"`
1949
19501881 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
19511882
19521883 Permission policy for tool execution.
19531884
1954 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
1885 - `BetaManagedAgentsAlwaysAllowPolicy object`
19551886
19561887 Tool calls are automatically approved without user confirmation.
19571888
1958 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
1889 - `BetaManagedAgentsAlwaysAskPolicy object`
19591890
19601891 Tool calls require user confirmation before execution.
19611892
19621893 - `type: "web_fetch"`
19631894
1964 - `"web_fetch"`
1965
19661895 - `allowed_domains: optional array of string`
19671896
19681897 - `blocked_domains: optional array of string`
19691898
19701899 - `max_content_tokens: optional number or null`
19711900
1972 - `BetaManagedAgentsWebSearchToolConfig object { enabled, name, permission_policy, 4 more }`
1901 format: int32
1902
1903 - `BetaManagedAgentsWebSearchToolConfig object`
19731904
19741905 Configuration for the web_search tool.
19751906
from line 1908
19771908
19781909 - `name: "web_search"`
19791910
1980 - `"web_search"`
1981
19821911 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
19831912
19841913 Permission policy for tool execution.
19851914
1986 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
1915 - `BetaManagedAgentsAlwaysAllowPolicy object`
19871916
19881917 Tool calls are automatically approved without user confirmation.
19891918
1990 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
1919 - `BetaManagedAgentsAlwaysAskPolicy object`
19911920
19921921 Tool calls require user confirmation before execution.
19931922
19941923 - `type: "web_search"`
19951924
1996 - `"web_search"`
1997
19981925 - `allowed_domains: optional array of string`
19991926
20001927 - `blocked_domains: optional array of string`
from line 1934
20071934
20081935 Location precision. Only "approximate" is supported.
20091936
2010 - `"approximate"`
2011
20121937 - `city: optional string or null`
20131938
20141939 City name.
20151940
1941 minLength: 1, maxLength: 255
1942
20161943 - `country: optional string or null`
20171944
20181945 Two-letter ISO 3166-1 country code, uppercase.
from line 1948
20211948
20221949 Region or state name.
20231950
1951 minLength: 1, maxLength: 255
1952
20241953 - `timezone: optional string or null`
20251954
20261955 IANA timezone identifier, e.g. "America/Los_Angeles".
20271956
1957 minLength: 1, maxLength: 255
1958
20281959 - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig`
20291960
20301961 Resolved default configuration for agent tools.
from line 1966
20351966
20361967 Permission policy for tool execution.
20371968
2038 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
1969 - `BetaManagedAgentsAlwaysAllowPolicy object`
20391970
20401971 Tool calls are automatically approved without user confirmation.
20411972
2042 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
1973 - `BetaManagedAgentsAlwaysAskPolicy object`
20431974
20441975 Tool calls require user confirmation before execution.
20451976
20461977 - `type: "agent_toolset_20260401"`
20471978
2048 - `"agent_toolset_20260401"`
2049
2050 - `BetaManagedAgentsMCPToolset object { configs, default_config, mcp_server_name, type }`
1979 - `BetaManagedAgentsMCPToolset object`
20511980
20521981 - `configs: array of BetaManagedAgentsMCPToolConfig`
20531982
from line 1988
20591988
20601989 Permission policy for tool execution.
20611990
2062 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
1991 - `BetaManagedAgentsAlwaysAllowPolicy object`
20631992
20641993 Tool calls are automatically approved without user confirmation.
20651994
2066 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
1995 - `BetaManagedAgentsAlwaysAskPolicy object`
20671996
20681997 Tool calls require user confirmation before execution.
20691998
from line 2006
20772006
20782007 Permission policy for tool execution.
20792008
2080 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
2009 - `BetaManagedAgentsAlwaysAllowPolicy object`
20812010
20822011 Tool calls are automatically approved without user confirmation.
20832012
2084 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
2013 - `BetaManagedAgentsAlwaysAskPolicy object`
20852014
20862015 Tool calls require user confirmation before execution.
20872016
from line 2018
20892018
20902019 - `type: "mcp_toolset"`
20912020
2092 - `"mcp_toolset"`
2093
2094 - `BetaManagedAgentsCustomTool object { description, input_schema, name, type }`
2021 - `BetaManagedAgentsCustomTool object`
20952022
20962023 A custom tool as returned in API responses.
20972024
from line 2030
21032030
21042031 - `type: "object"`
21052032
2106 - `"object"`
2107
21082033 - `properties: optional map[unknown] or null`
21092034
21102035 - `required: optional array of string or null`
from line 2038
21132038
21142039 - `type: "custom"`
21152040
2116 - `"custom"`
2117
21182041 - `type: "agent"`
21192042
2120 - `"agent"`
2121
21222043 - `version: number`
21232044
2124 - `BetaManagedAgentsAdvisor object { model, type }`
2045 format: int32
2046
2047 - `BetaManagedAgentsAdvisor object`
21252048
21262049 Platform advisor roster entry: a model the session's primary thread may consult mid-turn.
21272050
from line 2054
21312054
21322055 - `type: "advisor"`
21332056
2134 - `"advisor"`
2135
21362057 - `type: "coordinator"`
21372058
2138 - `"coordinator"`
2139
21402059 - `name: string`
21412060
21422061 - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill`
21432062
2144 - `BetaManagedAgentsAnthropicSkill object { skill_id, type, version }`
2063 - `BetaManagedAgentsAnthropicSkill object`
21452064
21462065 A resolved Anthropic-managed skill.
21472066
2148 - `BetaManagedAgentsCustomSkill object { skill_id, type, version }`
2067 - `BetaManagedAgentsCustomSkill object`
21492068
21502069 A resolved user-created custom skill.
21512070
from line 2072
21532072
21542073 - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool`
21552074
2156 - `BetaManagedAgentsAgentToolset20260401 object { configs, default_config, type }`
2157
2158 - `BetaManagedAgentsMCPToolset object { configs, default_config, mcp_server_name, type }`
2159
2160 - `BetaManagedAgentsCustomTool object { description, input_schema, name, type }`
2075 - `BetaManagedAgentsAgentToolset20260401 object`
2076
2077 - `BetaManagedAgentsMCPToolset object`
2078
2079 - `BetaManagedAgentsCustomTool object`
21612080
21622081 A custom tool as returned in API responses.
21632082
21642083 - `type: "agent"`
21652084
2166 - `"agent"`
2167
21682085 - `version: number`
21692086
2087 format: int32
2088
21702089 - `budget: optional BetaManagedAgentsBudgetLimit or null`
21712090
21722091 A hard spend ceiling. The session stops issuing new model requests once the tracked list cost reaches `max_list_cost`.
from line 2102
21832102
21842103 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.
21852104
2186 - `"USD"`
2187
21882105 - `type: "limit"`
21892106
2190 - `"limit"`
2191
21922107 - `metadata: optional map[string]`
21932108
21942109 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 2112
21972112
21982113 The session's new title. Present only when the update changed it.
21992114
2200 - `BetaManagedAgentsStartEvent object { event, type }`
2115 - `BetaManagedAgentsStartEvent object`
22012116
22022117 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.
22032118
from line 2120
22052120
22062121 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.
22072122
2208 - `BetaManagedAgentsAgentMessagePreview object { id, type }`
2123 - `BetaManagedAgentsAgentMessagePreview object`
22092124
22102125 - `id: string`
22112126
from line 2128
22132128
22142129 - `type: "agent.message"`
22152130
2216 - `"agent.message"`
2217
2218 - `BetaManagedAgentsAgentThinkingPreview object { id, type }`
2131 - `BetaManagedAgentsAgentThinkingPreview object`
22192132
22202133 - `id: string`
22212134
from line 2136
22232136
22242137 - `type: "agent.thinking"`
22252138
2226 - `"agent.thinking"`
2227
22282139 - `type: "event_start"`
22292140
2230 - `"event_start"`
2231
2232 - `BetaManagedAgentsDeltaEvent object { delta, event_id, type }`
2141 - `BetaManagedAgentsDeltaEvent object`
22332142
22342143 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.
22352144
from line 2152
22432152
22442153 - `type: "content_delta"`
22452154
2246 - `"content_delta"`
2247
22482155 - `index: optional number`
22492156
22502157 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.
22512158
2159 format: uint32
2160
22522161 - `event_id: string`
22532162
22542163 The id of the event being previewed. Matches event.id on the corresponding event_start and the buffered event that reconciles the preview.
22552164
22562165 - `type: "event_delta"`
22572166
2258 - `"event_delta"`
2259
2260 - `BetaManagedAgentsSystemMessageEvent object { id, content, type, processed_at }`
2167 - `BetaManagedAgentsSystemMessageEvent object`
22612168
22622169 A mid-conversation system message event. Carries system-role content that is appended to the session as a `role: "system"` turn.
22632170
from line 2180
22732180
22742181 The text content.
22752182
2183 minLength: 1
2184
22762185 - `type: "text"`
22772186
2278 - `"text"`
2279
22802187 - `type: "system.message"`
22812188
2282 - `"system.message"`
2283
22842189 - `processed_at: optional string or null`
22852190
22862191 A timestamp in RFC 3339 format
22872192
2288 - `BetaManagedAgentsSessionUsageEvent object { id, processed_at, type, 2 more }`
2193 format: date-time
2194
2195 - `BetaManagedAgentsSessionUsageEvent object`
22892196
22902197 Periodic snapshot of the session's cumulative usage and tracked list cost.
22912198
from line 2204
22972204
22982205 A timestamp in RFC 3339 format
22992206
2207 format: date-time
2208
23002209 - `type: "session.usage"`
23012210
2302 - `"session.usage"`
2303
23042211 - `usage: BetaManagedAgentsSessionUsageSnapshot`
23052212
23062213 Point-in-time snapshot of a session's cumulative usage.
from line 2216
23092216
23102217 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.
23112218
2219 format: double
2220
23122221 - `cache_creation: optional BetaManagedAgentsCacheCreationUsage`
23132222
23142223 Prompt-cache creation token usage broken down by cache lifetime.
from line 2226
23172226
23182227 Tokens used to create 1-hour ephemeral cache entries.
23192228
2229 format: int32
2230
23202231 - `ephemeral_5m_input_tokens: optional number`
23212232
23222233 Tokens used to create 5-minute ephemeral cache entries.
23232234
2235 format: int32
2236
23242237 - `cache_read_input_tokens: optional number`
23252238
23262239 Total tokens read from prompt cache.
23272240
2241 format: int32
2242
23282243 - `input_tokens: optional number`
23292244
23302245 Total input tokens consumed across all turns.
23312246
2247 format: int32
2248
23322249 - `list_cost: optional BetaMonetaryAmount`
23332250
23342251 A monetary amount in a specific currency.
from line 2254
23372254
23382255 Total output tokens generated across all turns.
23392256
2257 format: int32
2258
23402259 - `server_tool_use: optional BetaManagedAgentsServerToolUsage`
23412260
23422261 Cumulative count of server-executed tool invocations, broken down by tool.
from line 2264
23452264
23462265 Number of server-executed web fetch requests.
23472266
2267 format: int32
2268
23482269 - `web_search_requests: optional number`
23492270
23502271 Number of server-executed web search requests.
23512272
2273 format: int32
2274
23522275 - `budget: optional BetaManagedAgentsBudgetLimit or null`
23532276
23542277 A hard spend ceiling. The session stops issuing new model requests once the tracked list cost reaches `max_list_cost`.
23552278
2356### Example
2357
2358```http
2279- `BetaManagedAgentsStreamSessionEvents = BetaManagedAgentsUserMessageEvent or BetaManagedAgentsUserInterruptEvent or BetaManagedAgentsUserToolConfirmationEvent or 34 more`
2280
2281 Server-sent event in the session stream.
2282
2283## Example
2284
2285```bash
23592286curl https://api.anthropic.com/v1/sessions/$SESSION_ID/events/stream \
23602287 -H 'anthropic-version: 2023-06-01' \
23612288 -H 'anthropic-beta: managed-agents-2026-04-01' \
23622289 -H "X-Api-Key: $ANTHROPIC_API_KEY"
23632290```
23642291
2365#### Response
2292### Response (200)
23662293
23672294```json
23682295{
23692296
No line in this hunk matches that.