Events changedapi/beta/sessions/threads/events
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+638added
Lines−773removed
From line
1
where the diff opens
First seen
14 Aug 2026
this site's first read of the page
Recorded edits27to this page, all time
### Path parameters ### Query parameters ### Headers #### Response (200) ### Path parameters ### Query parameters ### Headers #### Response (200) ### Path Parameters ### Query Parameters ### Header Parameters #### Response ### Path Parameters ### Query Parameters ### Header Parameters #### 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: Events
3url: https://platform.claude.com/docs/en/api/beta/sessions/threads/events
4---
5
61# Events
72
83## List Session Thread Events
94
10**get** `/v1/sessions/{session_id}/threads/{thread_id}/events`
5**GET** `/v1/sessions/{session_id}/threads/{thread_id}/events`
116
127List Session Thread Events
138
14### Path Parameters
9### Path parameters
1510
1611- `session_id: string`
1712
1813- `thread_id: string`
1914
20### Query Parameters
15### Query parameters
2116
2217- `limit: optional number`
2318
2419 Query parameter for limit
2520
21 format: int32
22
2623- `page: optional string`
2724
2825 Query parameter for page
2926
30### Header Parameters
27### Headers
3128
3229- `"anthropic-beta": optional array of AnthropicBeta`
3330
from line 108
111108
112109 Events for the thread, ordered by `processed_at`.
113110
114 - `BetaManagedAgentsUserMessageEvent object { id, content, type, processed_at }`
111 - `BetaManagedAgentsUserMessageEvent object`
115112
116113 A user message event in the session conversation.
117114
from line 120
123120
124121 Array of content blocks comprising the user message.
125122
126 - `BetaManagedAgentsTextBlock object { text, type }`
123 - `BetaManagedAgentsTextBlock object`
127124
128125 Regular text content.
129126
from line 128
131128
132129 The text content.
133130
131 minLength: 1
132
134133 - `type: "text"`
135134
136 - `"text"`
137
138 - `BetaManagedAgentsImageBlock object { source, type }`
135 - `BetaManagedAgentsImageBlock object`
139136
140137 Image content specified directly as base64 data or as a reference via a URL.
141138
from line 140
143140
144141 Union type for image source variants.
145142
146 - `BetaManagedAgentsBase64ImageSource object { data, media_type, type }`
143 - `BetaManagedAgentsBase64ImageSource object`
147144
148145 Base64-encoded image data.
149146
from line 148
151148
152149 Base64-encoded image data.
153150
151 minLength: 1
152
154153 - `media_type: string`
155154
156155 MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp").
157156
157 minLength: 1
158
158159 - `type: "base64"`
159160
160 - `"base64"`
161
162 - `BetaManagedAgentsURLImageSource object { type, url }`
161 - `BetaManagedAgentsURLImageSource object`
163162
164163 Image referenced by URL.
165164
166165 - `type: "url"`
167166
168 - `"url"`
169
170167 - `url: string`
171168
172169 URL of the image to fetch.
173170
174 - `BetaManagedAgentsFileImageSource object { file_id, type }`
171 minLength: 1
172
173 - `BetaManagedAgentsFileImageSource object`
175174
176175 Image referenced by file ID.
177176
from line 178
179178
180179 ID of a previously uploaded file.
181180
181 minLength: 1
182
182183 - `type: "file"`
183184
184 - `"file"`
185
186185 - `type: "image"`
187186
188 - `"image"`
189
190 - `BetaManagedAgentsDocumentBlock object { source, type, context, title }`
187 - `BetaManagedAgentsDocumentBlock object`
191188
192189 Document content, either specified directly as base64 data, as text, or as a reference via a URL.
193190
from line 192
195192
196193 Union type for document source variants.
197194
198 - `BetaManagedAgentsBase64DocumentSource object { data, media_type, type }`
195 - `BetaManagedAgentsBase64DocumentSource object`
199196
200197 Base64-encoded document data.
201198
from line 200
203200
204201 Base64-encoded document data.
205202
203 minLength: 1
204
206205 - `media_type: string`
207206
208207 MIME type of the document (e.g., "application/pdf").
209208
209 minLength: 1
210
210211 - `type: "base64"`
211212
212 - `"base64"`
213
214 - `BetaManagedAgentsPlainTextDocumentSource object { data, media_type, type }`
213 - `BetaManagedAgentsPlainTextDocumentSource object`
215214
216215 Plain text document content.
217216
from line 218
219218
220219 The plain text content.
221220
221 minLength: 1
222
222223 - `media_type: "text/plain"`
223224
224225 MIME type of the text content. Must be "text/plain".
225226
226 - `"text/plain"`
227
228227 - `type: "text"`
229228
230 - `"text"`
231
232 - `BetaManagedAgentsURLDocumentSource object { type, url }`
229 - `BetaManagedAgentsURLDocumentSource object`
233230
234231 Document referenced by URL.
235232
236233 - `type: "url"`
237234
238 - `"url"`
239
240235 - `url: string`
241236
242237 URL of the document to fetch.
243238
244 - `BetaManagedAgentsFileDocumentSource object { file_id, type }`
239 minLength: 1
240
241 - `BetaManagedAgentsFileDocumentSource object`
245242
246243 Document referenced by file ID.
247244
from line 246
249246
250247 ID of a previously uploaded file.
251248
249 minLength: 1
250
252251 - `type: "file"`
253252
254 - `"file"`
255
256253 - `type: "document"`
257254
258 - `"document"`
259
260255 - `context: optional string or null`
261256
262257 Additional context about the document for the model.
from line 260
265260
266261 The title of the document.
267262
268 - `BetaManagedAgentsRedactedBlock object { type }`
263 - `BetaManagedAgentsRedactedBlock object`
269264
270265 Placeholder for content withheld by Anthropic model policy.
271266
272267 - `type: "redacted"`
273268
274 - `"redacted"`
275
276269 - `type: "user.message"`
277270
278 - `"user.message"`
279
280271 - `processed_at: optional string or null`
281272
282273 A timestamp in RFC 3339 format
283274
284 - `BetaManagedAgentsUserInterruptEvent object { id, type, processed_at, session_thread_id }`
275 format: date-time
276
277 - `BetaManagedAgentsUserInterruptEvent object`
285278
286279 An interrupt event that pauses agent execution and returns control to the user.
287280
from line 284
291284
292285 - `type: "user.interrupt"`
293286
294 - `"user.interrupt"`
295
296287 - `processed_at: optional string or null`
297288
298289 A timestamp in RFC 3339 format
299290
291 format: date-time
292
300293 - `session_thread_id: optional string or null`
301294
302295 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.
303296
304 - `BetaManagedAgentsUserToolConfirmationEvent object { id, result, tool_use_id, 4 more }`
297 - `BetaManagedAgentsUserToolConfirmationEvent object`
305298
306299 A tool confirmation event that approves or denies a pending tool execution.
307300
from line 316
323316
324317 - `type: "user.tool_confirmation"`
325318
326 - `"user.tool_confirmation"`
327
328319 - `deny_message: optional string or null`
329320
330321 Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'.
331322
323 maxLength: 10000
324
332325 - `processed_at: optional string or null`
333326
334327 A timestamp in RFC 3339 format
335328
329 format: date-time
330
336331 - `session_thread_id: optional string or null`
337332
338333 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.
339334
340 - `BetaManagedAgentsUserCustomToolResultEvent object { id, custom_tool_use_id, type, 4 more }`
335 - `BetaManagedAgentsUserCustomToolResultEvent object`
341336
342337 Event sent by the client providing the result of a custom tool execution.
343338
from line 346
351346
352347 - `type: "user.custom_tool_result"`
353348
354 - `"user.custom_tool_result"`
355
356349 - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock`
357350
358351 The result content returned by the tool.
359352
360 - `BetaManagedAgentsTextBlock object { text, type }`
353 - `BetaManagedAgentsTextBlock object`
361354
362355 Regular text content.
363356
364 - `BetaManagedAgentsImageBlock object { source, type }`
357 - `BetaManagedAgentsImageBlock object`
365358
366359 Image content specified directly as base64 data or as a reference via a URL.
367360
368 - `BetaManagedAgentsDocumentBlock object { source, type, context, title }`
361 - `BetaManagedAgentsDocumentBlock object`
369362
370363 Document content, either specified directly as base64 data, as text, or as a reference via a URL.
371364
372 - `BetaManagedAgentsSearchResultBlock object { citations, content, source, 2 more }`
365 - `BetaManagedAgentsSearchResultBlock object`
373366
374367 A block containing a web search result.
375368
from line 382
389382
390383 The text content.
391384
385 minLength: 1
386
392387 - `type: "text"`
393388
394 - `"text"`
395
396389 - `source: string`
397390
398391 The URL source of the search result.
399392
393 minLength: 1
394
400395 - `title: string`
401396
402397 The title of the search result.
403398
399 minLength: 1
400
404401 - `type: "search_result"`
405402
406 - `"search_result"`
407
408403 - `is_error: optional boolean or null`
409404
410405 Whether the tool execution resulted in an error.
from line 408
413408
414409 A timestamp in RFC 3339 format
415410
411 format: date-time
412
416413 - `session_thread_id: optional string or null`
417414
418415 Routes this result to a subagent thread. Copy from the `agent.custom_tool_use` event's `session_thread_id`.
419416
420 - `BetaManagedAgentsAgentCustomToolUseEvent object { id, input, name, 3 more }`
417 - `BetaManagedAgentsAgentCustomToolUseEvent object`
421418
422419 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.
423420
from line 434
437434
438435 A timestamp in RFC 3339 format
439436
437 format: date-time
438
440439 - `type: "agent.custom_tool_use"`
441440
442 - `"agent.custom_tool_use"`
443
444441 - `session_thread_id: optional string or null`
445442
446443 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.
447444
448 - `BetaManagedAgentsAgentMessageEvent object { id, content, processed_at, type }`
445 - `BetaManagedAgentsAgentMessageEvent object`
449446
450447 An agent response event in the session conversation.
451448
from line 454
457454
458455 Array of text blocks comprising the agent response.
459456
460 - `BetaManagedAgentsTextBlock object { text, type }`
457 - `BetaManagedAgentsTextBlock object`
461458
462459 Regular text content.
463460
464 - `BetaManagedAgentsRedactedBlock object { type }`
461 - `BetaManagedAgentsRedactedBlock object`
465462
466463 Placeholder for content withheld by Anthropic model policy.
467464
from line 466
469466
470467 A timestamp in RFC 3339 format
471468
469 format: date-time
470
472471 - `type: "agent.message"`
473472
474 - `"agent.message"`
475
476 - `BetaManagedAgentsAgentThinkingEvent object { id, processed_at, type }`
473 - `BetaManagedAgentsAgentThinkingEvent object`
477474
478475 Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier.
479476
from line 482
485482
486483 A timestamp in RFC 3339 format
487484
485 format: date-time
486
488487 - `type: "agent.thinking"`
489488
490 - `"agent.thinking"`
491
492 - `BetaManagedAgentsAgentMCPToolUseEvent object { id, input, mcp_server_name, 5 more }`
489 - `BetaManagedAgentsAgentMCPToolUseEvent object`
493490
494491 Event emitted when the agent invokes a tool provided by an MCP server.
495492
from line 510
513510
514511 A timestamp in RFC 3339 format
515512
513 format: date-time
514
516515 - `type: "agent.mcp_tool_use"`
517516
518 - `"agent.mcp_tool_use"`
519
520517 - `evaluated_permission: optional "allow" or "ask" or "deny"`
521518
522519 AgentEvaluatedPermission enum
from line 528
531528
532529 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.
533530
534 - `BetaManagedAgentsAgentMCPToolResultEvent object { id, mcp_tool_use_id, processed_at, 3 more }`
531 - `BetaManagedAgentsAgentMCPToolResultEvent object`
535532
536533 Event representing the result of an MCP tool execution.
537534
from line 544
547544
548545 A timestamp in RFC 3339 format
549546
547 format: date-time
548
550549 - `type: "agent.mcp_tool_result"`
551550
552 - `"agent.mcp_tool_result"`
553
554551 - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock`
555552
556553 The result content returned by the tool.
557554
558 - `BetaManagedAgentsTextBlock object { text, type }`
555 - `BetaManagedAgentsTextBlock object`
559556
560557 Regular text content.
561558
562 - `BetaManagedAgentsImageBlock object { source, type }`
559 - `BetaManagedAgentsImageBlock object`
563560
564561 Image content specified directly as base64 data or as a reference via a URL.
565562
566 - `BetaManagedAgentsDocumentBlock object { source, type, context, title }`
563 - `BetaManagedAgentsDocumentBlock object`
567564
568565 Document content, either specified directly as base64 data, as text, or as a reference via a URL.
569566
570 - `BetaManagedAgentsSearchResultBlock object { citations, content, source, 2 more }`
567 - `BetaManagedAgentsSearchResultBlock object`
571568
572569 A block containing a web search result.
573570
from line 572
575572
576573 Whether the tool execution resulted in an error.
577574
578 - `BetaManagedAgentsAgentToolUseEvent object { id, input, name, 4 more }`
575 - `BetaManagedAgentsAgentToolUseEvent object`
579576
580577 Event emitted when the agent invokes a built-in agent tool.
581578
from line 592
595592
596593 A timestamp in RFC 3339 format
597594
595 format: date-time
596
598597 - `type: "agent.tool_use"`
599598
600 - `"agent.tool_use"`
601
602599 - `evaluated_permission: optional "allow" or "ask" or "deny"`
603600
604601 AgentEvaluatedPermission enum
from line 610
613610
614611 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.
615612
616 - `BetaManagedAgentsAgentToolResultEvent object { id, processed_at, tool_use_id, 3 more }`
613 - `BetaManagedAgentsAgentToolResultEvent object`
617614
618615 Event representing the result of an agent tool execution.
619616
from line 622
625622
626623 A timestamp in RFC 3339 format
627624
625 format: date-time
626
628627 - `tool_use_id: string`
629628
630629 The id of the `agent.tool_use` event this result corresponds to.
631630
632631 - `type: "agent.tool_result"`
633632
634 - `"agent.tool_result"`
635
636633 - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock`
637634
638635 The result content returned by the tool.
639636
640 - `BetaManagedAgentsTextBlock object { text, type }`
637 - `BetaManagedAgentsTextBlock object`
641638
642639 Regular text content.
643640
644 - `BetaManagedAgentsImageBlock object { source, type }`
641 - `BetaManagedAgentsImageBlock object`
645642
646643 Image content specified directly as base64 data or as a reference via a URL.
647644
648 - `BetaManagedAgentsDocumentBlock object { source, type, context, title }`
645 - `BetaManagedAgentsDocumentBlock object`
649646
650647 Document content, either specified directly as base64 data, as text, or as a reference via a URL.
651648
652 - `BetaManagedAgentsSearchResultBlock object { citations, content, source, 2 more }`
649 - `BetaManagedAgentsSearchResultBlock object`
653650
654651 A block containing a web search result.
655652
from line 654
657654
658655 Whether the tool execution resulted in an error.
659656
660 - `BetaManagedAgentsAgentThreadMessageReceivedEvent object { id, content, from_session_thread_id, 3 more }`
657 - `BetaManagedAgentsAgentThreadMessageReceivedEvent object`
661658
662659 Delivery event written to the target thread's input stream when an agent-to-agent message arrives.
663660
from line 666
669666
670667 Message content blocks.
671668
672 - `BetaManagedAgentsTextBlock object { text, type }`
669 - `BetaManagedAgentsTextBlock object`
673670
674671 Regular text content.
675672
676 - `BetaManagedAgentsImageBlock object { source, type }`
673 - `BetaManagedAgentsImageBlock object`
677674
678675 Image content specified directly as base64 data or as a reference via a URL.
679676
680 - `BetaManagedAgentsDocumentBlock object { source, type, context, title }`
677 - `BetaManagedAgentsDocumentBlock object`
681678
682679 Document content, either specified directly as base64 data, as text, or as a reference via a URL.
683680
684 - `BetaManagedAgentsRedactedBlock object { type }`
681 - `BetaManagedAgentsRedactedBlock object`
685682
686683 Placeholder for content withheld by Anthropic model policy.
687684
from line 690
693690
694691 A timestamp in RFC 3339 format
695692
693 format: date-time
694
696695 - `type: "agent.thread_message_received"`
697696
698 - `"agent.thread_message_received"`
699
700697 - `from_agent_name: optional string or null`
701698
702699 Name of the callable agent this message came from. Absent when received from the primary agent.
703700
704 - `BetaManagedAgentsAgentThreadMessageSentEvent object { id, content, processed_at, 3 more }`
701 - `BetaManagedAgentsAgentThreadMessageSentEvent object`
705702
706703 Observability event emitted to the sender's output stream when an agent-to-agent message is sent.
707704
from line 710
713710
714711 Message content blocks.
715712
716 - `BetaManagedAgentsTextBlock object { text, type }`
713 - `BetaManagedAgentsTextBlock object`
717714
718715 Regular text content.
719716
720 - `BetaManagedAgentsImageBlock object { source, type }`
717 - `BetaManagedAgentsImageBlock object`
721718
722719 Image content specified directly as base64 data or as a reference via a URL.
723720
724 - `BetaManagedAgentsDocumentBlock object { source, type, context, title }`
721 - `BetaManagedAgentsDocumentBlock object`
725722
726723 Document content, either specified directly as base64 data, as text, or as a reference via a URL.
727724
728 - `BetaManagedAgentsRedactedBlock object { type }`
725 - `BetaManagedAgentsRedactedBlock object`
729726
730727 Placeholder for content withheld by Anthropic model policy.
731728
from line 730
733730
734731 A timestamp in RFC 3339 format
735732
733 format: date-time
734
736735 - `to_session_thread_id: string`
737736
738737 Public `sthr_` ID of the thread the message was sent to.
739738
740739 - `type: "agent.thread_message_sent"`
741740
742 - `"agent.thread_message_sent"`
743
744741 - `to_agent_name: optional string or null`
745742
746743 Name of the callable agent this message was sent to. Absent when sent to the primary agent.
747744
748 - `BetaManagedAgentsAgentThreadContextCompactedEvent object { id, processed_at, type }`
745 - `BetaManagedAgentsAgentThreadContextCompactedEvent object`
749746
750747 Indicates that context compaction (summarization) occurred during the session.
751748
from line 754
757754
758755 A timestamp in RFC 3339 format
759756
757 format: date-time
758
760759 - `type: "agent.thread_context_compacted"`
761760
762 - `"agent.thread_context_compacted"`
763
764 - `BetaManagedAgentsSessionErrorEvent object { id, error, processed_at, type }`
761 - `BetaManagedAgentsSessionErrorEvent object`
765762
766763 An error event indicating a problem occurred during session execution.
767764
from line 770
773770
774771 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.
775772
776 - `BetaManagedAgentsUnknownError object { message, retry_status, type }`
773 - `BetaManagedAgentsUnknownError object`
777774
778775 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.
779776
from line 782
785782
786783 What the client should do next in response to this error.
787784
788 - `BetaManagedAgentsRetryStatusRetrying object { type }`
785 - `BetaManagedAgentsRetryStatusRetrying object`
789786
790787 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.
791788
792789 - `type: "retrying"`
793790
794 - `"retrying"`
795
796 - `BetaManagedAgentsRetryStatusExhausted object { type }`
791 - `BetaManagedAgentsRetryStatusExhausted object`
797792
798793 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
799794
800795 - `type: "exhausted"`
801796
802 - `"exhausted"`
803
804 - `BetaManagedAgentsRetryStatusTerminal object { type }`
797 - `BetaManagedAgentsRetryStatusTerminal object`
805798
806799 The session encountered a terminal error and will transition to `terminated` state.
807800
808801 - `type: "terminal"`
809802
810 - `"terminal"`
811
812803 - `type: "unknown_error"`
813804
814 - `"unknown_error"`
815
816 - `BetaManagedAgentsModelOverloadedError object { message, retry_status, type }`
805 - `BetaManagedAgentsModelOverloadedError object`
817806
818807 The model is currently overloaded. Emitted after automatic retries are exhausted.
819808
from line 814
825814
826815 What the client should do next in response to this error.
827816
828 - `BetaManagedAgentsRetryStatusRetrying object { type }`
817 - `BetaManagedAgentsRetryStatusRetrying object`
829818
830819 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.
831820
832 - `BetaManagedAgentsRetryStatusExhausted object { type }`
821 - `BetaManagedAgentsRetryStatusExhausted object`
833822
834823 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
835824
836 - `BetaManagedAgentsRetryStatusTerminal object { type }`
825 - `BetaManagedAgentsRetryStatusTerminal object`
837826
838827 The session encountered a terminal error and will transition to `terminated` state.
839828
840829 - `type: "model_overloaded_error"`
841830
842 - `"model_overloaded_error"`
843
844 - `BetaManagedAgentsModelRateLimitedError object { message, retry_status, type }`
831 - `BetaManagedAgentsModelRateLimitedError object`
845832
846833 The model request was rate-limited.
847834
from line 840
853840
854841 What the client should do next in response to this error.
855842
856 - `BetaManagedAgentsRetryStatusRetrying object { type }`
843 - `BetaManagedAgentsRetryStatusRetrying object`
857844
858845 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.
859846
860 - `BetaManagedAgentsRetryStatusExhausted object { type }`
847 - `BetaManagedAgentsRetryStatusExhausted object`
861848
862849 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
863850
864 - `BetaManagedAgentsRetryStatusTerminal object { type }`
851 - `BetaManagedAgentsRetryStatusTerminal object`
865852
866853 The session encountered a terminal error and will transition to `terminated` state.
867854
868855 - `type: "model_rate_limited_error"`
869856
870 - `"model_rate_limited_error"`
871
872 - `BetaManagedAgentsModelRequestFailedError object { message, retry_status, type }`
857 - `BetaManagedAgentsModelRequestFailedError object`
873858
874859 A model request failed for a reason other than overload or rate-limiting.
875860
from line 866
881866
882867 What the client should do next in response to this error.
883868
884 - `BetaManagedAgentsRetryStatusRetrying object { type }`
869 - `BetaManagedAgentsRetryStatusRetrying object`
885870
886871 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.
887872
888 - `BetaManagedAgentsRetryStatusExhausted object { type }`
873 - `BetaManagedAgentsRetryStatusExhausted object`
889874
890875 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
891876
892 - `BetaManagedAgentsRetryStatusTerminal object { type }`
877 - `BetaManagedAgentsRetryStatusTerminal object`
893878
894879 The session encountered a terminal error and will transition to `terminated` state.
895880
896881 - `type: "model_request_failed_error"`
897882
898 - `"model_request_failed_error"`
899
900 - `BetaManagedAgentsMCPConnectionFailedError object { mcp_server_name, message, retry_status, type }`
883 - `BetaManagedAgentsMCPConnectionFailedError object`
901884
902885 Failed to connect to an MCP server.
903886
from line 896
913896
914897 What the client should do next in response to this error.
915898
916 - `BetaManagedAgentsRetryStatusRetrying object { type }`
899 - `BetaManagedAgentsRetryStatusRetrying object`
917900
918901 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.
919902
920 - `BetaManagedAgentsRetryStatusExhausted object { type }`
903 - `BetaManagedAgentsRetryStatusExhausted object`
921904
922905 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
923906
924 - `BetaManagedAgentsRetryStatusTerminal object { type }`
907 - `BetaManagedAgentsRetryStatusTerminal object`
925908
926909 The session encountered a terminal error and will transition to `terminated` state.
927910
928911 - `type: "mcp_connection_failed_error"`
929912
930 - `"mcp_connection_failed_error"`
931
932 - `BetaManagedAgentsMCPAuthenticationFailedError object { mcp_server_name, message, retry_status, type }`
913 - `BetaManagedAgentsMCPAuthenticationFailedError object`
933914
934915 Authentication to an MCP server failed.
935916
from line 926
945926
946927 What the client should do next in response to this error.
947928
948 - `BetaManagedAgentsRetryStatusRetrying object { type }`
929 - `BetaManagedAgentsRetryStatusRetrying object`
949930
950931 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.
951932
952 - `BetaManagedAgentsRetryStatusExhausted object { type }`
933 - `BetaManagedAgentsRetryStatusExhausted object`
953934
954935 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
955936
956 - `BetaManagedAgentsRetryStatusTerminal object { type }`
937 - `BetaManagedAgentsRetryStatusTerminal object`
957938
958939 The session encountered a terminal error and will transition to `terminated` state.
959940
960941 - `type: "mcp_authentication_failed_error"`
961942
962 - `"mcp_authentication_failed_error"`
963
964 - `BetaManagedAgentsBillingError object { message, retry_status, type }`
943 - `BetaManagedAgentsBillingError object`
965944
966945 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.
967946
from line 952
973952
974953 What the client should do next in response to this error.
975954
976 - `BetaManagedAgentsRetryStatusRetrying object { type }`
955 - `BetaManagedAgentsRetryStatusRetrying object`
977956
978957 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.
979958
980 - `BetaManagedAgentsRetryStatusExhausted object { type }`
959 - `BetaManagedAgentsRetryStatusExhausted object`
981960
982961 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
983962
984 - `BetaManagedAgentsRetryStatusTerminal object { type }`
963 - `BetaManagedAgentsRetryStatusTerminal object`
985964
986965 The session encountered a terminal error and will transition to `terminated` state.
987966
988967 - `type: "billing_error"`
989968
990 - `"billing_error"`
991
992 - `BetaManagedAgentsCredentialHostUnreachableError object { credential_id, message, retry_status, 2 more }`
969 - `BetaManagedAgentsCredentialHostUnreachableError object`
993970
994971 An `environment_variable` credential's `auth.networking.allowed_hosts` includes a host the environment's network policy does not permit.
995972
from line 982
1005982
1006983 What the client should do next in response to this error.
1007984
1008 - `BetaManagedAgentsRetryStatusRetrying object { type }`
985 - `BetaManagedAgentsRetryStatusRetrying object`
1009986
1010987 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.
1011988
1012 - `BetaManagedAgentsRetryStatusExhausted object { type }`
989 - `BetaManagedAgentsRetryStatusExhausted object`
1013990
1014991 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
1015992
1016 - `BetaManagedAgentsRetryStatusTerminal object { type }`
993 - `BetaManagedAgentsRetryStatusTerminal object`
1017994
1018995 The session encountered a terminal error and will transition to `terminated` state.
1019996
1020997 - `type: "credential_host_unreachable_error"`
1021998
1022 - `"credential_host_unreachable_error"`
1023
1024999 - `vault_id: string`
10251000
10261001 ID of the vault containing the affected credential.
from line 1004
10291004
10301005 A timestamp in RFC 3339 format
10311006
1007 format: date-time
1008
10321009 - `type: "session.error"`
10331010
1034 - `"session.error"`
1035
1036 - `BetaManagedAgentsSessionStatusRescheduledEvent object { id, processed_at, type }`
1011 - `BetaManagedAgentsSessionStatusRescheduledEvent object`
10371012
10381013 Indicates the session is recovering from an error state and is rescheduled for execution.
10391014
from line 1020
10451020
10461021 A timestamp in RFC 3339 format
10471022
1023 format: date-time
1024
10481025 - `type: "session.status_rescheduled"`
10491026
1050 - `"session.status_rescheduled"`
1051
1052 - `BetaManagedAgentsSessionStatusRunningEvent object { id, processed_at, type }`
1027 - `BetaManagedAgentsSessionStatusRunningEvent object`
10531028
10541029 Indicates the session is actively running and the agent is working.
10551030
from line 1036
10611036
10621037 A timestamp in RFC 3339 format
10631038
1039 format: date-time
1040
10641041 - `type: "session.status_running"`
10651042
1066 - `"session.status_running"`
1067
1068 - `BetaManagedAgentsSessionStatusIdleEvent object { id, processed_at, stop_reason, type }`
1043 - `BetaManagedAgentsSessionStatusIdleEvent object`
10691044
10701045 Indicates the agent has paused and is awaiting user input.
10711046
from line 1052
10771052
10781053 A timestamp in RFC 3339 format
10791054
1055 format: date-time
1056
10801057 - `stop_reason: BetaManagedAgentsSessionEndTurn or BetaManagedAgentsSessionRequiresAction or BetaManagedAgentsSessionRetriesExhausted or BetaManagedAgentsSessionBudgetReached`
10811058
10821059 The agent completed its turn naturally and is ready for the next user message.
10831060
1084 - `BetaManagedAgentsSessionEndTurn object { type }`
1061 - `BetaManagedAgentsSessionEndTurn object`
10851062
10861063 The agent completed its turn naturally and is ready for the next user message.
10871064
10881065 - `type: "end_turn"`
10891066
1090 - `"end_turn"`
1091
1092 - `BetaManagedAgentsSessionRequiresAction object { event_ids, type }`
1067 - `BetaManagedAgentsSessionRequiresAction object`
10931068
10941069 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.
10951070
from line 1074
10991074
11001075 - `type: "requires_action"`
11011076
1102 - `"requires_action"`
1103
1104 - `BetaManagedAgentsSessionRetriesExhausted object { type }`
1077 - `BetaManagedAgentsSessionRetriesExhausted object`
11051078
11061079 The turn ended because repeated errors exhausted the retry budget or an error escalated to `retry_status: 'exhausted'`.
11071080
11081081 - `type: "retries_exhausted"`
11091082
1110 - `"retries_exhausted"`
1111
1112 - `BetaManagedAgentsSessionBudgetReached object { type }`
1083 - `BetaManagedAgentsSessionBudgetReached object`
11131084
11141085 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.
11151086
11161087 - `type: "budget_reached"`
11171088
1118 - `"budget_reached"`
1119
11201089 - `type: "session.status_idle"`
11211090
1122 - `"session.status_idle"`
1123
1124 - `BetaManagedAgentsSessionStatusTerminatedEvent object { id, processed_at, type }`
1091 - `BetaManagedAgentsSessionStatusTerminatedEvent object`
11251092
11261093 Indicates the session has terminated, either due to an error or completion.
11271094
from line 1100
11331100
11341101 A timestamp in RFC 3339 format
11351102
1103 format: date-time
1104
11361105 - `type: "session.status_terminated"`
11371106
1138 - `"session.status_terminated"`
1139
1140 - `BetaManagedAgentsSessionThreadCreatedEvent object { id, agent_name, processed_at, 2 more }`
1107 - `BetaManagedAgentsSessionThreadCreatedEvent object`
11411108
11421109 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.
11431110
from line 1120
11531120
11541121 A timestamp in RFC 3339 format
11551122
1123 format: date-time
1124
11561125 - `session_thread_id: string`
11571126
11581127 Public `sthr_` ID of the newly created thread.
11591128
11601129 - `type: "session.thread_created"`
11611130
1162 - `"session.thread_created"`
1163
1164 - `BetaManagedAgentsSpanOutcomeEvaluationStartEvent object { id, iteration, outcome_id, 2 more }`
1131 - `BetaManagedAgentsSpanOutcomeEvaluationStartEvent object`
11651132
11661133 Emitted when an outcome evaluation cycle begins.
11671134
from line 1140
11731140
11741141 0-indexed revision cycle. 0 is the first evaluation; 1 is the re-evaluation after the first revision; etc.
11751142
1143 format: int32
1144
11761145 - `outcome_id: string`
11771146
11781147 The `outc_` ID of the outcome being evaluated.
from line 1150
11811150
11821151 A timestamp in RFC 3339 format
11831152
1153 format: date-time
1154
11841155 - `type: "span.outcome_evaluation_start"`
11851156
1186 - `"span.outcome_evaluation_start"`
1187
1188 - `BetaManagedAgentsSpanOutcomeEvaluationEndEvent object { id, explanation, iteration, 6 more }`
1157 - `BetaManagedAgentsSpanOutcomeEvaluationEndEvent object`
11891158
11901159 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.
11911160
from line 1170
12011170
12021171 0-indexed revision cycle, matching the corresponding `span.outcome_evaluation_start`.
12031172
1173 format: int32
1174
12041175 - `outcome_evaluation_start_id: string`
12051176
12061177 The id of the corresponding `span.outcome_evaluation_start` event.
from line 1184
12131184
12141185 A timestamp in RFC 3339 format
12151186
1187 format: date-time
1188
12161189 - `result: string`
12171190
12181191 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.
12191192
12201193 - `type: "span.outcome_evaluation_end"`
12211194
1222 - `"span.outcome_evaluation_end"`
1223
12241195 - `usage: BetaManagedAgentsSpanModelUsage`
12251196
12261197 Token usage for a single model request.
from line 1200
12291200
12301201 Tokens used to create prompt cache in this request.
12311202
1203 format: int32
1204
12321205 - `cache_read_input_tokens: number`
12331206
12341207 Tokens read from prompt cache in this request.
12351208
1209 format: int32
1210
12361211 - `input_tokens: number`
12371212
12381213 Input tokens consumed by this request.
12391214
1215 format: int32
1216
12401217 - `output_tokens: number`
12411218
12421219 Output tokens generated by this request.
12431220
1221 format: int32
1222
12441223 - `speed: optional "standard" or "fast" or null`
12451224
12461225 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 1228
12491228
12501229 - `"fast"`
12511230
1252 - `BetaManagedAgentsSpanModelRequestStartEvent object { id, processed_at, type }`
1231 - `BetaManagedAgentsSpanModelRequestStartEvent object`
12531232
12541233 Emitted when a model request is initiated by the agent.
12551234
from line 1240
12611240
12621241 A timestamp in RFC 3339 format
12631242
1243 format: date-time
1244
12641245 - `type: "span.model_request_start"`
12651246
1266 - `"span.model_request_start"`
1267
1268 - `BetaManagedAgentsSpanModelRequestEndEvent object { id, is_error, model_request_start_id, 3 more }`
1247 - `BetaManagedAgentsSpanModelRequestEndEvent object`
12691248
12701249 Emitted when a model request completes.
12711250
from line 1268
12891268
12901269 A timestamp in RFC 3339 format
12911270
1271 format: date-time
1272
12921273 - `type: "span.model_request_end"`
12931274
1294 - `"span.model_request_end"`
1295
1296 - `BetaManagedAgentsSpanOutcomeEvaluationOngoingEvent object { id, iteration, outcome_id, 2 more }`
1275 - `BetaManagedAgentsSpanOutcomeEvaluationOngoingEvent object`
12971276
12981277 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.
12991278
from line 1284
13051284
13061285 0-indexed revision cycle, matching the corresponding `span.outcome_evaluation_start`.
13071286
1287 format: int32
1288
13081289 - `outcome_id: string`
13091290
13101291 The `outc_` ID of the outcome being evaluated.
from line 1294
13131294
13141295 A timestamp in RFC 3339 format
13151296
1297 format: date-time
1298
13161299 - `type: "span.outcome_evaluation_ongoing"`
13171300
1318 - `"span.outcome_evaluation_ongoing"`
1319
1320 - `BetaManagedAgentsUserDefineOutcomeEvent object { id, description, max_iterations, 4 more }`
1301 - `BetaManagedAgentsUserDefineOutcomeEvent object`
13211302
13221303 Echo of a `user.define_outcome` input event. Carries the server-generated `outcome_id` that subsequent `span.outcome_evaluation_*` events reference.
13231304
from line 1314
13331314
13341315 Evaluate-then-revise cycles before giving up. Default 3, max 20.
13351316
1317 format: int32
1318
13361319 - `outcome_id: string`
13371320
13381321 Server-generated `outc_` ID for this outcome. Referenced by `span.outcome_evaluation_*` events and the session's `outcome_evaluations` list.
from line 1324
13411324
13421325 A timestamp in RFC 3339 format
13431326
1327 format: date-time
1328
13441329 - `rubric: BetaManagedAgentsFileRubric or BetaManagedAgentsTextRubric`
13451330
13461331 Rubric for grading the quality of an outcome.
13471332
1348 - `BetaManagedAgentsFileRubric object { file_id, type }`
1333 - `BetaManagedAgentsFileRubric object`
13491334
13501335 Rubric referenced by a file uploaded via the Files API.
13511336
from line 1340
13551340
13561341 - `type: "file"`
13571342
1358 - `"file"`
1359
1360 - `BetaManagedAgentsTextRubric object { content, type }`
1343 - `BetaManagedAgentsTextRubric object`
13611344
13621345 Rubric content provided inline as text.
13631346
from line 1350
13671350
13681351 - `type: "text"`
13691352
1370 - `"text"`
1371
13721353 - `type: "user.define_outcome"`
13731354
1374 - `"user.define_outcome"`
1375
1376 - `BetaManagedAgentsSessionDeletedEvent object { id, processed_at, type }`
1355 - `BetaManagedAgentsSessionDeletedEvent object`
13771356
13781357 Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session.
13791358
from line 1364
13851364
13861365 A timestamp in RFC 3339 format
13871366
1367 format: date-time
1368
13881369 - `type: "session.deleted"`
13891370
1390 - `"session.deleted"`
1391
1392 - `BetaManagedAgentsSessionThreadStatusRunningEvent object { id, agent_name, processed_at, 2 more }`
1371 - `BetaManagedAgentsSessionThreadStatusRunningEvent object`
13931372
13941373 A session thread has begun executing. Emitted on the thread's own stream and cross-posted to the primary stream for child threads.
13951374
from line 1384
14051384
14061385 A timestamp in RFC 3339 format
14071386
1387 format: date-time
1388
14081389 - `session_thread_id: string`
14091390
14101391 Public sthr_ ID of the thread that started running.
14111392
14121393 - `type: "session.thread_status_running"`
14131394
1414 - `"session.thread_status_running"`
1415
1416 - `BetaManagedAgentsSessionThreadStatusIdleEvent object { id, agent_name, processed_at, 3 more }`
1395 - `BetaManagedAgentsSessionThreadStatusIdleEvent object`
14171396
14181397 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.
14191398
from line 1408
14291408
14301409 A timestamp in RFC 3339 format
14311410
1411 format: date-time
1412
14321413 - `session_thread_id: string`
14331414
14341415 Public sthr_ ID of the thread that went idle.
from line 1418
14371418
14381419 The agent completed its turn naturally and is ready for the next user message.
14391420
1440 - `BetaManagedAgentsSessionEndTurn object { type }`
1421 - `BetaManagedAgentsSessionEndTurn object`
14411422
14421423 The agent completed its turn naturally and is ready for the next user message.
14431424
1444 - `BetaManagedAgentsSessionRequiresAction object { event_ids, type }`
1425 - `BetaManagedAgentsSessionRequiresAction object`
14451426
14461427 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.
14471428
1448 - `BetaManagedAgentsSessionRetriesExhausted object { type }`
1429 - `BetaManagedAgentsSessionRetriesExhausted object`
14491430
14501431 The turn ended because repeated errors exhausted the retry budget or an error escalated to `retry_status: 'exhausted'`.
14511432
1452 - `BetaManagedAgentsSessionBudgetReached object { type }`
1433 - `BetaManagedAgentsSessionBudgetReached object`
14531434
14541435 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.
14551436
14561437 - `type: "session.thread_status_idle"`
14571438
1458 - `"session.thread_status_idle"`
1459
1460 - `BetaManagedAgentsSessionThreadStatusTerminatedEvent object { id, agent_name, processed_at, 2 more }`
1439 - `BetaManagedAgentsSessionThreadStatusTerminatedEvent object`
14611440
14621441 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.
14631442
from line 1452
14731452
14741453 A timestamp in RFC 3339 format
14751454
1455 format: date-time
1456
14761457 - `session_thread_id: string`
14771458
14781459 Public sthr_ ID of the thread that terminated.
14791460
14801461 - `type: "session.thread_status_terminated"`
14811462
1482 - `"session.thread_status_terminated"`
1483
1484 - `BetaManagedAgentsUserToolResultEvent object { id, tool_use_id, type, 4 more }`
1463 - `BetaManagedAgentsUserToolResultEvent object`
14851464
14861465 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.
14871466
from line 1474
14951474
14961475 - `type: "user.tool_result"`
14971476
1498 - `"user.tool_result"`
1499
15001477 - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock`
15011478
15021479 The result content returned by the tool.
15031480
1504 - `BetaManagedAgentsTextBlock object { text, type }`
1481 - `BetaManagedAgentsTextBlock object`
15051482
15061483 Regular text content.
15071484
1508 - `BetaManagedAgentsImageBlock object { source, type }`
1485 - `BetaManagedAgentsImageBlock object`
15091486
15101487 Image content specified directly as base64 data or as a reference via a URL.
15111488
1512 - `BetaManagedAgentsDocumentBlock object { source, type, context, title }`
1489 - `BetaManagedAgentsDocumentBlock object`
15131490
15141491 Document content, either specified directly as base64 data, as text, or as a reference via a URL.
15151492
1516 - `BetaManagedAgentsSearchResultBlock object { citations, content, source, 2 more }`
1493 - `BetaManagedAgentsSearchResultBlock object`
15171494
15181495 A block containing a web search result.
15191496
from line 1502
15251502
15261503 A timestamp in RFC 3339 format
15271504
1505 format: date-time
1506
15281507 - `session_thread_id: optional string or null`
15291508
15301509 Routes this result to a subagent thread. Copy from the `agent.tool_use` event's `session_thread_id`.
15311510
1532 - `BetaManagedAgentsSessionThreadStatusRescheduledEvent object { id, agent_name, processed_at, 2 more }`
1511 - `BetaManagedAgentsSessionThreadStatusRescheduledEvent object`
15331512
15341513 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.
15351514
from line 1524
15451524
15461525 A timestamp in RFC 3339 format
15471526
1527 format: date-time
1528
15481529 - `session_thread_id: string`
15491530
15501531 Public sthr_ ID of the thread that is retrying.
15511532
15521533 - `type: "session.thread_status_rescheduled"`
15531534
1554 - `"session.thread_status_rescheduled"`
1555
1556 - `BetaManagedAgentsSessionUpdatedEvent object { id, processed_at, type, 4 more }`
1535 - `BetaManagedAgentsSessionUpdatedEvent object`
15571536
15581537 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.
15591538
from line 1544
15651544
15661545 A timestamp in RFC 3339 format
15671546
1547 format: date-time
1548
15681549 - `type: "session.updated"`
15691550
1570 - `"session.updated"`
1571
15721551 - `agent: optional BetaManagedAgentsSessionAgent or null`
15731552
15741553 Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time.
from line 1562
15831562
15841563 - `type: "url"`
15851564
1586 - `"url"`
1587
15881565 - `url: string`
15891566
15901567 - `model: BetaManagedAgentsModelConfig`
from line 1638
16611638
16621639 How hard Claude works on each turn. Sets `output_config.effort` on every Messages call the session makes.
16631640
1664 - `BetaManagedAgentsEffortLow object { type }`
1641 - `BetaManagedAgentsEffortLow object`
16651642
16661643 Low effort. Favors latency over reasoning depth.
16671644
16681645 - `type: "low"`
16691646
1670 - `"low"`
1671
1672 - `BetaManagedAgentsEffortMedium object { type }`
1647 - `BetaManagedAgentsEffortMedium object`
16731648
16741649 Medium effort. Balances latency and reasoning depth.
16751650
16761651 - `type: "medium"`
16771652
1678 - `"medium"`
1679
1680 - `BetaManagedAgentsEffortHigh object { type }`
1653 - `BetaManagedAgentsEffortHigh object`
16811654
16821655 High effort. Favors reasoning depth.
16831656
16841657 - `type: "high"`
16851658
1686 - `"high"`
1687
1688 - `BetaManagedAgentsEffortXhigh object { type }`
1659 - `BetaManagedAgentsEffortXhigh object`
16891660
16901661 Extra-high effort. Not all models accept this level.
16911662
16921663 - `type: "xhigh"`
16931664
1694 - `"xhigh"`
1695
1696 - `BetaManagedAgentsEffortMax object { type }`
1665 - `BetaManagedAgentsEffortMax object`
16971666
16981667 Maximum effort. Favors reasoning depth over latency.
16991668
17001669 - `type: "max"`
17011670
1702 - `"max"`
1703
17041671 - `inference_geo: optional string`
17051672
17061673 Geographic region for model inference. When unset, requests fall through to the workspace's default_inference_geo.
from line 1688
17211688
17221689 Full `agent` definitions the coordinator may spawn as session threads.
17231690
1724 - `BetaManagedAgentsSessionThreadAgent object { id, description, mcp_servers, 7 more }`
1691 - `BetaManagedAgentsSessionThreadAgent object`
17251692
17261693 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`.
17271694
from line 1712
17451712
17461713 - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill`
17471714
1748 - `BetaManagedAgentsAnthropicSkill object { skill_id, type, version }`
1715 - `BetaManagedAgentsAnthropicSkill object`
17491716
17501717 A resolved Anthropic-managed skill.
17511718
from line 1720
17531720
17541721 - `type: "anthropic"`
17551722
1756 - `"anthropic"`
1757
17581723 - `version: string`
17591724
1760 - `BetaManagedAgentsCustomSkill object { skill_id, type, version }`
1725 - `BetaManagedAgentsCustomSkill object`
17611726
17621727 A resolved user-created custom skill.
17631728
from line 1730
17651730
17661731 - `type: "custom"`
17671732
1768 - `"custom"`
1769
17701733 - `version: string`
17711734
17721735 - `system: string or null`
17731736
17741737 - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool`
17751738
1776 - `BetaManagedAgentsAgentToolset20260401 object { configs, default_config, type }`
1739 - `BetaManagedAgentsAgentToolset20260401 object`
17771740
17781741 - `configs: array of BetaManagedAgentsAgentToolConfig`
17791742
1780 - `BetaManagedAgentsBashToolConfig object { enabled, name, permission_policy, type }`
1743 - `BetaManagedAgentsBashToolConfig object`
17811744
17821745 Configuration for the bash tool.
17831746
from line 1748
17851748
17861749 - `name: "bash"`
17871750
1788 - `"bash"`
1789
17901751 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
17911752
17921753 Permission policy for tool execution.
17931754
1794 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
1755 - `BetaManagedAgentsAlwaysAllowPolicy object`
17951756
17961757 Tool calls are automatically approved without user confirmation.
17971758
17981759 - `type: "always_allow"`
17991760
1800 - `"always_allow"`
1801
1802 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
1761 - `BetaManagedAgentsAlwaysAskPolicy object`
18031762
18041763 Tool calls require user confirmation before execution.
18051764
18061765 - `type: "always_ask"`
18071766
1808 - `"always_ask"`
1809
18101767 - `type: "bash"`
18111768
1812 - `"bash"`
1813
1814 - `BetaManagedAgentsEditToolConfig object { enabled, name, permission_policy, type }`
1769 - `BetaManagedAgentsEditToolConfig object`
18151770
18161771 Configuration for the edit tool.
18171772
from line 1774
18191774
18201775 - `name: "edit"`
18211776
1822 - `"edit"`
1823
18241777 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
18251778
18261779 Permission policy for tool execution.
18271780
1828 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
1781 - `BetaManagedAgentsAlwaysAllowPolicy object`
18291782
18301783 Tool calls are automatically approved without user confirmation.
18311784
1832 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
1785 - `BetaManagedAgentsAlwaysAskPolicy object`
18331786
18341787 Tool calls require user confirmation before execution.
18351788
18361789 - `type: "edit"`
18371790
1838 - `"edit"`
1839
1840 - `BetaManagedAgentsReadToolConfig object { enabled, name, permission_policy, type }`
1791 - `BetaManagedAgentsReadToolConfig object`
18411792
18421793 Configuration for the read tool.
18431794
from line 1796
18451796
18461797 - `name: "read"`
18471798
1848 - `"read"`
1849
18501799 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
18511800
18521801 Permission policy for tool execution.
18531802
1854 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
1803 - `BetaManagedAgentsAlwaysAllowPolicy object`
18551804
18561805 Tool calls are automatically approved without user confirmation.
18571806
1858 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
1807 - `BetaManagedAgentsAlwaysAskPolicy object`
18591808
18601809 Tool calls require user confirmation before execution.
18611810
18621811 - `type: "read"`
18631812
1864 - `"read"`
1865
1866 - `BetaManagedAgentsWriteToolConfig object { enabled, name, permission_policy, type }`
1813 - `BetaManagedAgentsWriteToolConfig object`
18671814
18681815 Configuration for the write tool.
18691816
from line 1818
18711818
18721819 - `name: "write"`
18731820
1874 - `"write"`
1875
18761821 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
18771822
18781823 Permission policy for tool execution.
18791824
1880 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
1825 - `BetaManagedAgentsAlwaysAllowPolicy object`
18811826
18821827 Tool calls are automatically approved without user confirmation.
18831828
1884 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
1829 - `BetaManagedAgentsAlwaysAskPolicy object`
18851830
18861831 Tool calls require user confirmation before execution.
18871832
18881833 - `type: "write"`
18891834
1890 - `"write"`
1891
1892 - `BetaManagedAgentsGlobToolConfig object { enabled, name, permission_policy, type }`
1835 - `BetaManagedAgentsGlobToolConfig object`
18931836
18941837 Configuration for the glob tool.
18951838
from line 1840
18971840
18981841 - `name: "glob"`
18991842
1900 - `"glob"`
1901
19021843 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
19031844
19041845 Permission policy for tool execution.
19051846
1906 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
1847 - `BetaManagedAgentsAlwaysAllowPolicy object`
19071848
19081849 Tool calls are automatically approved without user confirmation.
19091850
1910 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
1851 - `BetaManagedAgentsAlwaysAskPolicy object`
19111852
19121853 Tool calls require user confirmation before execution.
19131854
19141855 - `type: "glob"`
19151856
1916 - `"glob"`
1917
1918 - `BetaManagedAgentsGrepToolConfig object { enabled, name, permission_policy, type }`
1857 - `BetaManagedAgentsGrepToolConfig object`
19191858
19201859 Configuration for the grep tool.
19211860
from line 1862
19231862
19241863 - `name: "grep"`
19251864
1926 - `"grep"`
1927
19281865 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
19291866
19301867 Permission policy for tool execution.
19311868
1932 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
1869 - `BetaManagedAgentsAlwaysAllowPolicy object`
19331870
19341871 Tool calls are automatically approved without user confirmation.
19351872
1936 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
1873 - `BetaManagedAgentsAlwaysAskPolicy object`
19371874
19381875 Tool calls require user confirmation before execution.
19391876
19401877 - `type: "grep"`
19411878
1942 - `"grep"`
1943
1944 - `BetaManagedAgentsWebFetchToolConfig object { enabled, name, permission_policy, 4 more }`
1879 - `BetaManagedAgentsWebFetchToolConfig object`
19451880
19461881 Configuration for the web_fetch tool.
19471882
from line 1884
19491884
19501885 - `name: "web_fetch"`
19511886
1952 - `"web_fetch"`
1953
19541887 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
19551888
19561889 Permission policy for tool execution.
19571890
1958 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
1891 - `BetaManagedAgentsAlwaysAllowPolicy object`
19591892
19601893 Tool calls are automatically approved without user confirmation.
19611894
1962 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
1895 - `BetaManagedAgentsAlwaysAskPolicy object`
19631896
19641897 Tool calls require user confirmation before execution.
19651898
19661899 - `type: "web_fetch"`
19671900
1968 - `"web_fetch"`
1969
19701901 - `allowed_domains: optional array of string`
19711902
19721903 - `blocked_domains: optional array of string`
19731904
19741905 - `max_content_tokens: optional number or null`
19751906
1976 - `BetaManagedAgentsWebSearchToolConfig object { enabled, name, permission_policy, 4 more }`
1907 format: int32
1908
1909 - `BetaManagedAgentsWebSearchToolConfig object`
19771910
19781911 Configuration for the web_search tool.
19791912
from line 1914
19811914
19821915 - `name: "web_search"`
19831916
1984 - `"web_search"`
1985
19861917 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
19871918
19881919 Permission policy for tool execution.
19891920
1990 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
1921 - `BetaManagedAgentsAlwaysAllowPolicy object`
19911922
19921923 Tool calls are automatically approved without user confirmation.
19931924
1994 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
1925 - `BetaManagedAgentsAlwaysAskPolicy object`
19951926
19961927 Tool calls require user confirmation before execution.
19971928
19981929 - `type: "web_search"`
19991930
2000 - `"web_search"`
2001
20021931 - `allowed_domains: optional array of string`
20031932
20041933 - `blocked_domains: optional array of string`
from line 1940
20111940
20121941 Location precision. Only "approximate" is supported.
20131942
2014 - `"approximate"`
2015
20161943 - `city: optional string or null`
20171944
20181945 City name.
20191946
1947 minLength: 1, maxLength: 255
1948
20201949 - `country: optional string or null`
20211950
20221951 Two-letter ISO 3166-1 country code, uppercase.
from line 1954
20251954
20261955 Region or state name.
20271956
1957 minLength: 1, maxLength: 255
1958
20281959 - `timezone: optional string or null`
20291960
20301961 IANA timezone identifier, e.g. "America/Los_Angeles".
20311962
1963 minLength: 1, maxLength: 255
1964
20321965 - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig`
20331966
20341967 Resolved default configuration for agent tools.
from line 1972
20391972
20401973 Permission policy for tool execution.
20411974
2042 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
1975 - `BetaManagedAgentsAlwaysAllowPolicy object`
20431976
20441977 Tool calls are automatically approved without user confirmation.
20451978
2046 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
1979 - `BetaManagedAgentsAlwaysAskPolicy object`
20471980
20481981 Tool calls require user confirmation before execution.
20491982
20501983 - `type: "agent_toolset_20260401"`
20511984
2052 - `"agent_toolset_20260401"`
2053
2054 - `BetaManagedAgentsMCPToolset object { configs, default_config, mcp_server_name, type }`
1985 - `BetaManagedAgentsMCPToolset object`
20551986
20561987 - `configs: array of BetaManagedAgentsMCPToolConfig`
20571988
from line 1994
20631994
20641995 Permission policy for tool execution.
20651996
2066 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
1997 - `BetaManagedAgentsAlwaysAllowPolicy object`
20671998
20681999 Tool calls are automatically approved without user confirmation.
20692000
2070 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
2001 - `BetaManagedAgentsAlwaysAskPolicy object`
20712002
20722003 Tool calls require user confirmation before execution.
20732004
from line 2012
20812012
20822013 Permission policy for tool execution.
20832014
2084 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
2015 - `BetaManagedAgentsAlwaysAllowPolicy object`
20852016
20862017 Tool calls are automatically approved without user confirmation.
20872018
2088 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
2019 - `BetaManagedAgentsAlwaysAskPolicy object`
20892020
20902021 Tool calls require user confirmation before execution.
20912022
from line 2024
20932024
20942025 - `type: "mcp_toolset"`
20952026
2096 - `"mcp_toolset"`
2097
2098 - `BetaManagedAgentsCustomTool object { description, input_schema, name, type }`
2027 - `BetaManagedAgentsCustomTool object`
20992028
21002029 A custom tool as returned in API responses.
21012030
from line 2036
21072036
21082037 - `type: "object"`
21092038
2110 - `"object"`
2111
21122039 - `properties: optional map[unknown] or null`
21132040
21142041 - `required: optional array of string or null`
from line 2044
21172044
21182045 - `type: "custom"`
21192046
2120 - `"custom"`
2121
21222047 - `type: "agent"`
21232048
2124 - `"agent"`
2125
21262049 - `version: number`
21272050
2128 - `BetaManagedAgentsAdvisor object { model, type }`
2051 format: int32
2052
2053 - `BetaManagedAgentsAdvisor object`
21292054
21302055 Platform advisor roster entry: a model the session's primary thread may consult mid-turn.
21312056
from line 2060
21352060
21362061 - `type: "advisor"`
21372062
2138 - `"advisor"`
2139
21402063 - `type: "coordinator"`
21412064
2142 - `"coordinator"`
2143
21442065 - `name: string`
21452066
21462067 - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill`
21472068
2148 - `BetaManagedAgentsAnthropicSkill object { skill_id, type, version }`
2069 - `BetaManagedAgentsAnthropicSkill object`
21492070
21502071 A resolved Anthropic-managed skill.
21512072
2152 - `BetaManagedAgentsCustomSkill object { skill_id, type, version }`
2073 - `BetaManagedAgentsCustomSkill object`
21532074
21542075 A resolved user-created custom skill.
21552076
from line 2078
21572078
21582079 - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool`
21592080
2160 - `BetaManagedAgentsAgentToolset20260401 object { configs, default_config, type }`
2161
2162 - `BetaManagedAgentsMCPToolset object { configs, default_config, mcp_server_name, type }`
2163
2164 - `BetaManagedAgentsCustomTool object { description, input_schema, name, type }`
2081 - `BetaManagedAgentsAgentToolset20260401 object`
2082
2083 - `BetaManagedAgentsMCPToolset object`
2084
2085 - `BetaManagedAgentsCustomTool object`
21652086
21662087 A custom tool as returned in API responses.
21672088
21682089 - `type: "agent"`
21692090
2170 - `"agent"`
2171
21722091 - `version: number`
21732092
2093 format: int32
2094
21742095 - `budget: optional BetaManagedAgentsBudgetLimit or null`
21752096
21762097 A hard spend ceiling. The session stops issuing new model requests once the tracked list cost reaches `max_list_cost`.
from line 2108
21872108
21882109 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.
21892110
2190 - `"USD"`
2191
21922111 - `type: "limit"`
21932112
2194 - `"limit"`
2195
21962113 - `metadata: optional map[string]`
21972114
21982115 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 2118
22012118
22022119 The session's new title. Present only when the update changed it.
22032120
2204 - `BetaManagedAgentsSystemMessageEvent object { id, content, type, processed_at }`
2121 - `BetaManagedAgentsSystemMessageEvent object`
22052122
22062123 A mid-conversation system message event. Carries system-role content that is appended to the session as a `role: "system"` turn.
22072124
from line 2134
22172134
22182135 The text content.
22192136
2137 minLength: 1
2138
22202139 - `type: "text"`
22212140
2222 - `"text"`
2223
22242141 - `type: "system.message"`
22252142
2226 - `"system.message"`
2227
22282143 - `processed_at: optional string or null`
22292144
22302145 A timestamp in RFC 3339 format
22312146
2232 - `BetaManagedAgentsSessionUsageEvent object { id, processed_at, type, 2 more }`
2147 format: date-time
2148
2149 - `BetaManagedAgentsSessionUsageEvent object`
22332150
22342151 Periodic snapshot of the session's cumulative usage and tracked list cost.
22352152
from line 2158
22412158
22422159 A timestamp in RFC 3339 format
22432160
2161 format: date-time
2162
22442163 - `type: "session.usage"`
22452164
2246 - `"session.usage"`
2247
22482165 - `usage: BetaManagedAgentsSessionUsageSnapshot`
22492166
22502167 Point-in-time snapshot of a session's cumulative usage.
from line 2170
22532170
22542171 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.
22552172
2173 format: double
2174
22562175 - `cache_creation: optional BetaManagedAgentsCacheCreationUsage`
22572176
22582177 Prompt-cache creation token usage broken down by cache lifetime.
from line 2180
22612180
22622181 Tokens used to create 1-hour ephemeral cache entries.
22632182
2183 format: int32
2184
22642185 - `ephemeral_5m_input_tokens: optional number`
22652186
22662187 Tokens used to create 5-minute ephemeral cache entries.
22672188
2189 format: int32
2190
22682191 - `cache_read_input_tokens: optional number`
22692192
22702193 Total tokens read from prompt cache.
22712194
2195 format: int32
2196
22722197 - `input_tokens: optional number`
22732198
22742199 Total input tokens consumed across all turns.
22752200
2201 format: int32
2202
22762203 - `list_cost: optional BetaMonetaryAmount`
22772204
22782205 A monetary amount in a specific currency.
from line 2208
22812208
22822209 Total output tokens generated across all turns.
22832210
2211 format: int32
2212
22842213 - `server_tool_use: optional BetaManagedAgentsServerToolUsage`
22852214
22862215 Cumulative count of server-executed tool invocations, broken down by tool.
from line 2218
22892218
22902219 Number of server-executed web fetch requests.
22912220
2221 format: int32
2222
22922223 - `web_search_requests: optional number`
22932224
22942225 Number of server-executed web search requests.
22952226
2227 format: int32
2228
22962229 - `budget: optional BetaManagedAgentsBudgetLimit or null`
22972230
22982231 A hard spend ceiling. The session stops issuing new model requests once the tracked list cost reaches `max_list_cost`.
from line 2236
23032236
23042237### Example
23052238
2306```http
2239```bash
23072240curl https://api.anthropic.com/v1/sessions/$SESSION_ID/threads/$THREAD_ID/events \
23082241 -H 'anthropic-version: 2023-06-01' \
23092242 -H 'anthropic-beta: managed-agents-2026-04-01' \
23102243 -H "X-Api-Key: $ANTHROPIC_API_KEY"
23112244```
23122245
2313#### Response
2246#### Response (200)
23142247
23152248```json
23162249{
from line 2266
23332266
23342267## Stream Session Thread Events
23352268
2336**get** `/v1/sessions/{session_id}/threads/{thread_id}/stream`
2269**GET** `/v1/sessions/{session_id}/threads/{thread_id}/stream`
23372270
23382271Stream Session Thread Events
23392272
2340### Path Parameters
2273### Path parameters
23412274
23422275- `session_id: string`
23432276
23442277- `thread_id: string`
23452278
2346### Query Parameters
2279### Query parameters
23472280
23482281- `event_deltas: optional array of BetaManagedAgentsDeltaType`
23492282
from line 2286
23532286
23542287 - `"agent.thinking"`
23552288
2356### Header Parameters
2289### Headers
23572290
23582291- `"anthropic-beta": optional array of AnthropicBeta`
23592292
from line 2370
24372370
24382371 Server-sent event in a single thread's stream.
24392372
2440 - `BetaManagedAgentsUserMessageEvent object { id, content, type, processed_at }`
2373 - `BetaManagedAgentsUserMessageEvent object`
24412374
24422375 A user message event in the session conversation.
24432376
from line 2382
24492382
24502383 Array of content blocks comprising the user message.
24512384
2452 - `BetaManagedAgentsTextBlock object { text, type }`
2385 - `BetaManagedAgentsTextBlock object`
24532386
24542387 Regular text content.
24552388
from line 2390
24572390
24582391 The text content.
24592392
2393 minLength: 1
2394
24602395 - `type: "text"`
24612396
2462 - `"text"`
2463
2464 - `BetaManagedAgentsImageBlock object { source, type }`
2397 - `BetaManagedAgentsImageBlock object`
24652398
24662399 Image content specified directly as base64 data or as a reference via a URL.
24672400
from line 2402
24692402
24702403 Union type for image source variants.
24712404
2472 - `BetaManagedAgentsBase64ImageSource object { data, media_type, type }`
2405 - `BetaManagedAgentsBase64ImageSource object`
24732406
24742407 Base64-encoded image data.
24752408
from line 2410
24772410
24782411 Base64-encoded image data.
24792412
2413 minLength: 1
2414
24802415 - `media_type: string`
24812416
24822417 MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp").
24832418
2419 minLength: 1
2420
24842421 - `type: "base64"`
24852422
2486 - `"base64"`
2487
2488 - `BetaManagedAgentsURLImageSource object { type, url }`
2423 - `BetaManagedAgentsURLImageSource object`
24892424
24902425 Image referenced by URL.
24912426
24922427 - `type: "url"`
24932428
2494 - `"url"`
2495
24962429 - `url: string`
24972430
24982431 URL of the image to fetch.
24992432
2500 - `BetaManagedAgentsFileImageSource object { file_id, type }`
2433 minLength: 1
2434
2435 - `BetaManagedAgentsFileImageSource object`
25012436
25022437 Image referenced by file ID.
25032438
from line 2440
25052440
25062441 ID of a previously uploaded file.
25072442
2443 minLength: 1
2444
25082445 - `type: "file"`
25092446
2510 - `"file"`
2511
25122447 - `type: "image"`
25132448
2514 - `"image"`
2515
2516 - `BetaManagedAgentsDocumentBlock object { source, type, context, title }`
2449 - `BetaManagedAgentsDocumentBlock object`
25172450
25182451 Document content, either specified directly as base64 data, as text, or as a reference via a URL.
25192452
from line 2454
25212454
25222455 Union type for document source variants.
25232456
2524 - `BetaManagedAgentsBase64DocumentSource object { data, media_type, type }`
2457 - `BetaManagedAgentsBase64DocumentSource object`
25252458
25262459 Base64-encoded document data.
25272460
from line 2462
25292462
25302463 Base64-encoded document data.
25312464
2465 minLength: 1
2466
25322467 - `media_type: string`
25332468
25342469 MIME type of the document (e.g., "application/pdf").
25352470
2471 minLength: 1
2472
25362473 - `type: "base64"`
25372474
2538 - `"base64"`
2539
2540 - `BetaManagedAgentsPlainTextDocumentSource object { data, media_type, type }`
2475 - `BetaManagedAgentsPlainTextDocumentSource object`
25412476
25422477 Plain text document content.
25432478
from line 2480
25452480
25462481 The plain text content.
25472482
2483 minLength: 1
2484
25482485 - `media_type: "text/plain"`
25492486
25502487 MIME type of the text content. Must be "text/plain".
25512488
2552 - `"text/plain"`
2553
25542489 - `type: "text"`
25552490
2556 - `"text"`
2557
2558 - `BetaManagedAgentsURLDocumentSource object { type, url }`
2491 - `BetaManagedAgentsURLDocumentSource object`
25592492
25602493 Document referenced by URL.
25612494
25622495 - `type: "url"`
25632496
2564 - `"url"`
2565
25662497 - `url: string`
25672498
25682499 URL of the document to fetch.
25692500
2570 - `BetaManagedAgentsFileDocumentSource object { file_id, type }`
2501 minLength: 1
2502
2503 - `BetaManagedAgentsFileDocumentSource object`
25712504
25722505 Document referenced by file ID.
25732506
from line 2508
25752508
25762509 ID of a previously uploaded file.
25772510
2511 minLength: 1
2512
25782513 - `type: "file"`
25792514
2580 - `"file"`
2581
25822515 - `type: "document"`
25832516
2584 - `"document"`
2585
25862517 - `context: optional string or null`
25872518
25882519 Additional context about the document for the model.
from line 2522
25912522
25922523 The title of the document.
25932524
2594 - `BetaManagedAgentsRedactedBlock object { type }`
2525 - `BetaManagedAgentsRedactedBlock object`
25952526
25962527 Placeholder for content withheld by Anthropic model policy.
25972528
25982529 - `type: "redacted"`
25992530
2600 - `"redacted"`
2601
26022531 - `type: "user.message"`
26032532
2604 - `"user.message"`
2605
26062533 - `processed_at: optional string or null`
26072534
26082535 A timestamp in RFC 3339 format
26092536
2610 - `BetaManagedAgentsUserInterruptEvent object { id, type, processed_at, session_thread_id }`
2537 format: date-time
2538
2539 - `BetaManagedAgentsUserInterruptEvent object`
26112540
26122541 An interrupt event that pauses agent execution and returns control to the user.
26132542
from line 2546
26172546
26182547 - `type: "user.interrupt"`
26192548
2620 - `"user.interrupt"`
2621
26222549 - `processed_at: optional string or null`
26232550
26242551 A timestamp in RFC 3339 format
26252552
2553 format: date-time
2554
26262555 - `session_thread_id: optional string or null`
26272556
26282557 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.
26292558
2630 - `BetaManagedAgentsUserToolConfirmationEvent object { id, result, tool_use_id, 4 more }`
2559 - `BetaManagedAgentsUserToolConfirmationEvent object`
26312560
26322561 A tool confirmation event that approves or denies a pending tool execution.
26332562
from line 2578
26492578
26502579 - `type: "user.tool_confirmation"`
26512580
2652 - `"user.tool_confirmation"`
2653
26542581 - `deny_message: optional string or null`
26552582
26562583 Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'.
26572584
2585 maxLength: 10000
2586
26582587 - `processed_at: optional string or null`
26592588
26602589 A timestamp in RFC 3339 format
26612590
2591 format: date-time
2592
26622593 - `session_thread_id: optional string or null`
26632594
26642595 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.
26652596
2666 - `BetaManagedAgentsUserCustomToolResultEvent object { id, custom_tool_use_id, type, 4 more }`
2597 - `BetaManagedAgentsUserCustomToolResultEvent object`
26672598
26682599 Event sent by the client providing the result of a custom tool execution.
26692600
from line 2608
26772608
26782609 - `type: "user.custom_tool_result"`
26792610
2680 - `"user.custom_tool_result"`
2681
26822611 - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock`
26832612
26842613 The result content returned by the tool.
26852614
2686 - `BetaManagedAgentsTextBlock object { text, type }`
2615 - `BetaManagedAgentsTextBlock object`
26872616
26882617 Regular text content.
26892618
2690 - `BetaManagedAgentsImageBlock object { source, type }`
2619 - `BetaManagedAgentsImageBlock object`
26912620
26922621 Image content specified directly as base64 data or as a reference via a URL.
26932622
2694 - `BetaManagedAgentsDocumentBlock object { source, type, context, title }`
2623 - `BetaManagedAgentsDocumentBlock object`
26952624
26962625 Document content, either specified directly as base64 data, as text, or as a reference via a URL.
26972626
2698 - `BetaManagedAgentsSearchResultBlock object { citations, content, source, 2 more }`
2627 - `BetaManagedAgentsSearchResultBlock object`
26992628
27002629 A block containing a web search result.
27012630
from line 2644
27152644
27162645 The text content.
27172646
2647 minLength: 1
2648
27182649 - `type: "text"`
27192650
2720 - `"text"`
2721
27222651 - `source: string`
27232652
27242653 The URL source of the search result.
27252654
2655 minLength: 1
2656
27262657 - `title: string`
27272658
27282659 The title of the search result.
27292660
2661 minLength: 1
2662
27302663 - `type: "search_result"`
27312664
2732 - `"search_result"`
2733
27342665 - `is_error: optional boolean or null`
27352666
27362667 Whether the tool execution resulted in an error.
from line 2670
27392670
27402671 A timestamp in RFC 3339 format
27412672
2673 format: date-time
2674
27422675 - `session_thread_id: optional string or null`
27432676
27442677 Routes this result to a subagent thread. Copy from the `agent.custom_tool_use` event's `session_thread_id`.
27452678
2746 - `BetaManagedAgentsAgentCustomToolUseEvent object { id, input, name, 3 more }`
2679 - `BetaManagedAgentsAgentCustomToolUseEvent object`
27472680
27482681 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.
27492682
from line 2696
27632696
27642697 A timestamp in RFC 3339 format
27652698
2699 format: date-time
2700
27662701 - `type: "agent.custom_tool_use"`
27672702
2768 - `"agent.custom_tool_use"`
2769
27702703 - `session_thread_id: optional string or null`
27712704
27722705 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.
27732706
2774 - `BetaManagedAgentsAgentMessageEvent object { id, content, processed_at, type }`
2707 - `BetaManagedAgentsAgentMessageEvent object`
27752708
27762709 An agent response event in the session conversation.
27772710
from line 2716
27832716
27842717 Array of text blocks comprising the agent response.
27852718
2786 - `BetaManagedAgentsTextBlock object { text, type }`
2719 - `BetaManagedAgentsTextBlock object`
27872720
27882721 Regular text content.
27892722
2790 - `BetaManagedAgentsRedactedBlock object { type }`
2723 - `BetaManagedAgentsRedactedBlock object`
27912724
27922725 Placeholder for content withheld by Anthropic model policy.
27932726
from line 2728
27952728
27962729 A timestamp in RFC 3339 format
27972730
2731 format: date-time
2732
27982733 - `type: "agent.message"`
27992734
2800 - `"agent.message"`
2801
2802 - `BetaManagedAgentsAgentThinkingEvent object { id, processed_at, type }`
2735 - `BetaManagedAgentsAgentThinkingEvent object`
28032736
28042737 Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier.
28052738
from line 2744
28112744
28122745 A timestamp in RFC 3339 format
28132746
2747 format: date-time
2748
28142749 - `type: "agent.thinking"`
28152750
2816 - `"agent.thinking"`
2817
2818 - `BetaManagedAgentsAgentMCPToolUseEvent object { id, input, mcp_server_name, 5 more }`
2751 - `BetaManagedAgentsAgentMCPToolUseEvent object`
28192752
28202753 Event emitted when the agent invokes a tool provided by an MCP server.
28212754
from line 2772
28392772
28402773 A timestamp in RFC 3339 format
28412774
2775 format: date-time
2776
28422777 - `type: "agent.mcp_tool_use"`
28432778
2844 - `"agent.mcp_tool_use"`
2845
28462779 - `evaluated_permission: optional "allow" or "ask" or "deny"`
28472780
28482781 AgentEvaluatedPermission enum
from line 2790
28572790
28582791 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.
28592792
2860 - `BetaManagedAgentsAgentMCPToolResultEvent object { id, mcp_tool_use_id, processed_at, 3 more }`
2793 - `BetaManagedAgentsAgentMCPToolResultEvent object`
28612794
28622795 Event representing the result of an MCP tool execution.
28632796
from line 2806
28732806
28742807 A timestamp in RFC 3339 format
28752808
2809 format: date-time
2810
28762811 - `type: "agent.mcp_tool_result"`
28772812
2878 - `"agent.mcp_tool_result"`
2879
28802813 - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock`
28812814
28822815 The result content returned by the tool.
28832816
2884 - `BetaManagedAgentsTextBlock object { text, type }`
2817 - `BetaManagedAgentsTextBlock object`
28852818
28862819 Regular text content.
28872820
2888 - `BetaManagedAgentsImageBlock object { source, type }`
2821 - `BetaManagedAgentsImageBlock object`
28892822
28902823 Image content specified directly as base64 data or as a reference via a URL.
28912824
2892 - `BetaManagedAgentsDocumentBlock object { source, type, context, title }`
2825 - `BetaManagedAgentsDocumentBlock object`
28932826
28942827 Document content, either specified directly as base64 data, as text, or as a reference via a URL.
28952828
2896 - `BetaManagedAgentsSearchResultBlock object { citations, content, source, 2 more }`
2829 - `BetaManagedAgentsSearchResultBlock object`
28972830
28982831 A block containing a web search result.
28992832
from line 2834
29012834
29022835 Whether the tool execution resulted in an error.
29032836
2904 - `BetaManagedAgentsAgentToolUseEvent object { id, input, name, 4 more }`
2837 - `BetaManagedAgentsAgentToolUseEvent object`
29052838
29062839 Event emitted when the agent invokes a built-in agent tool.
29072840
from line 2854
29212854
29222855 A timestamp in RFC 3339 format
29232856
2857 format: date-time
2858
29242859 - `type: "agent.tool_use"`
29252860
2926 - `"agent.tool_use"`
2927
29282861 - `evaluated_permission: optional "allow" or "ask" or "deny"`
29292862
29302863 AgentEvaluatedPermission enum
from line 2872
29392872
29402873 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.
29412874
2942 - `BetaManagedAgentsAgentToolResultEvent object { id, processed_at, tool_use_id, 3 more }`
2875 - `BetaManagedAgentsAgentToolResultEvent object`
29432876
29442877 Event representing the result of an agent tool execution.
29452878
from line 2884
29512884
29522885 A timestamp in RFC 3339 format
29532886
2887 format: date-time
2888
29542889 - `tool_use_id: string`
29552890
29562891 The id of the `agent.tool_use` event this result corresponds to.
29572892
29582893 - `type: "agent.tool_result"`
29592894
2960 - `"agent.tool_result"`
2961
29622895 - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock`
29632896
29642897 The result content returned by the tool.
29652898
2966 - `BetaManagedAgentsTextBlock object { text, type }`
2899 - `BetaManagedAgentsTextBlock object`
29672900
29682901 Regular text content.
29692902
2970 - `BetaManagedAgentsImageBlock object { source, type }`
2903 - `BetaManagedAgentsImageBlock object`
29712904
29722905 Image content specified directly as base64 data or as a reference via a URL.
29732906
2974 - `BetaManagedAgentsDocumentBlock object { source, type, context, title }`
2907 - `BetaManagedAgentsDocumentBlock object`
29752908
29762909 Document content, either specified directly as base64 data, as text, or as a reference via a URL.
29772910
2978 - `BetaManagedAgentsSearchResultBlock object { citations, content, source, 2 more }`
2911 - `BetaManagedAgentsSearchResultBlock object`
29792912
29802913 A block containing a web search result.
29812914
from line 2916
29832916
29842917 Whether the tool execution resulted in an error.
29852918
2986 - `BetaManagedAgentsAgentThreadMessageReceivedEvent object { id, content, from_session_thread_id, 3 more }`
2919 - `BetaManagedAgentsAgentThreadMessageReceivedEvent object`
29872920
29882921 Delivery event written to the target thread's input stream when an agent-to-agent message arrives.
29892922
from line 2928
29952928
29962929 Message content blocks.
29972930
2998 - `BetaManagedAgentsTextBlock object { text, type }`
2931 - `BetaManagedAgentsTextBlock object`
29992932
30002933 Regular text content.
30012934
3002 - `BetaManagedAgentsImageBlock object { source, type }`
2935 - `BetaManagedAgentsImageBlock object`
30032936
30042937 Image content specified directly as base64 data or as a reference via a URL.
30052938
3006 - `BetaManagedAgentsDocumentBlock object { source, type, context, title }`
2939 - `BetaManagedAgentsDocumentBlock object`
30072940
30082941 Document content, either specified directly as base64 data, as text, or as a reference via a URL.
30092942
3010 - `BetaManagedAgentsRedactedBlock object { type }`
2943 - `BetaManagedAgentsRedactedBlock object`
30112944
30122945 Placeholder for content withheld by Anthropic model policy.
30132946
from line 2952
30192952
30202953 A timestamp in RFC 3339 format
30212954
2955 format: date-time
2956
30222957 - `type: "agent.thread_message_received"`
30232958
3024 - `"agent.thread_message_received"`
3025
30262959 - `from_agent_name: optional string or null`
30272960
30282961 Name of the callable agent this message came from. Absent when received from the primary agent.
30292962
3030 - `BetaManagedAgentsAgentThreadMessageSentEvent object { id, content, processed_at, 3 more }`
2963 - `BetaManagedAgentsAgentThreadMessageSentEvent object`
30312964
30322965 Observability event emitted to the sender's output stream when an agent-to-agent message is sent.
30332966
from line 2972
30392972
30402973 Message content blocks.
30412974
3042 - `BetaManagedAgentsTextBlock object { text, type }`
2975 - `BetaManagedAgentsTextBlock object`
30432976
30442977 Regular text content.
30452978
3046 - `BetaManagedAgentsImageBlock object { source, type }`
2979 - `BetaManagedAgentsImageBlock object`
30472980
30482981 Image content specified directly as base64 data or as a reference via a URL.
30492982
3050 - `BetaManagedAgentsDocumentBlock object { source, type, context, title }`
2983 - `BetaManagedAgentsDocumentBlock object`
30512984
30522985 Document content, either specified directly as base64 data, as text, or as a reference via a URL.
30532986
3054 - `BetaManagedAgentsRedactedBlock object { type }`
2987 - `BetaManagedAgentsRedactedBlock object`
30552988
30562989 Placeholder for content withheld by Anthropic model policy.
30572990
from line 2992
30592992
30602993 A timestamp in RFC 3339 format
30612994
2995 format: date-time
2996
30622997 - `to_session_thread_id: string`
30632998
30642999 Public `sthr_` ID of the thread the message was sent to.
30653000
30663001 - `type: "agent.thread_message_sent"`
30673002
3068 - `"agent.thread_message_sent"`
3069
30703003 - `to_agent_name: optional string or null`
30713004
30723005 Name of the callable agent this message was sent to. Absent when sent to the primary agent.
30733006
3074 - `BetaManagedAgentsAgentThreadContextCompactedEvent object { id, processed_at, type }`
3007 - `BetaManagedAgentsAgentThreadContextCompactedEvent object`
30753008
30763009 Indicates that context compaction (summarization) occurred during the session.
30773010
from line 3016
30833016
30843017 A timestamp in RFC 3339 format
30853018
3019 format: date-time
3020
30863021 - `type: "agent.thread_context_compacted"`
30873022
3088 - `"agent.thread_context_compacted"`
3089
3090 - `BetaManagedAgentsSessionErrorEvent object { id, error, processed_at, type }`
3023 - `BetaManagedAgentsSessionErrorEvent object`
30913024
30923025 An error event indicating a problem occurred during session execution.
30933026
from line 3032
30993032
31003033 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.
31013034
3102 - `BetaManagedAgentsUnknownError object { message, retry_status, type }`
3035 - `BetaManagedAgentsUnknownError object`
31033036
31043037 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.
31053038
from line 3044
31113044
31123045 What the client should do next in response to this error.
31133046
3114 - `BetaManagedAgentsRetryStatusRetrying object { type }`
3047 - `BetaManagedAgentsRetryStatusRetrying object`
31153048
31163049 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.
31173050
31183051 - `type: "retrying"`
31193052
3120 - `"retrying"`
3121
3122 - `BetaManagedAgentsRetryStatusExhausted object { type }`
3053 - `BetaManagedAgentsRetryStatusExhausted object`
31233054
31243055 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
31253056
31263057 - `type: "exhausted"`
31273058
3128 - `"exhausted"`
3129
3130 - `BetaManagedAgentsRetryStatusTerminal object { type }`
3059 - `BetaManagedAgentsRetryStatusTerminal object`
31313060
31323061 The session encountered a terminal error and will transition to `terminated` state.
31333062
31343063 - `type: "terminal"`
31353064
3136 - `"terminal"`
3137
31383065 - `type: "unknown_error"`
31393066
3140 - `"unknown_error"`
3141
3142 - `BetaManagedAgentsModelOverloadedError object { message, retry_status, type }`
3067 - `BetaManagedAgentsModelOverloadedError object`
31433068
31443069 The model is currently overloaded. Emitted after automatic retries are exhausted.
31453070
from line 3076
31513076
31523077 What the client should do next in response to this error.
31533078
3154 - `BetaManagedAgentsRetryStatusRetrying object { type }`
3079 - `BetaManagedAgentsRetryStatusRetrying object`
31553080
31563081 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.
31573082
3158 - `BetaManagedAgentsRetryStatusExhausted object { type }`
3083 - `BetaManagedAgentsRetryStatusExhausted object`
31593084
31603085 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
31613086
3162 - `BetaManagedAgentsRetryStatusTerminal object { type }`
3087 - `BetaManagedAgentsRetryStatusTerminal object`
31633088
31643089 The session encountered a terminal error and will transition to `terminated` state.
31653090
31663091 - `type: "model_overloaded_error"`
31673092
3168 - `"model_overloaded_error"`
3169
3170 - `BetaManagedAgentsModelRateLimitedError object { message, retry_status, type }`
3093 - `BetaManagedAgentsModelRateLimitedError object`
31713094
31723095 The model request was rate-limited.
31733096
from line 3102
31793102
31803103 What the client should do next in response to this error.
31813104
3182 - `BetaManagedAgentsRetryStatusRetrying object { type }`
3105 - `BetaManagedAgentsRetryStatusRetrying object`
31833106
31843107 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.
31853108
3186 - `BetaManagedAgentsRetryStatusExhausted object { type }`
3109 - `BetaManagedAgentsRetryStatusExhausted object`
31873110
31883111 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
31893112
3190 - `BetaManagedAgentsRetryStatusTerminal object { type }`
3113 - `BetaManagedAgentsRetryStatusTerminal object`
31913114
31923115 The session encountered a terminal error and will transition to `terminated` state.
31933116
31943117 - `type: "model_rate_limited_error"`
31953118
3196 - `"model_rate_limited_error"`
3197
3198 - `BetaManagedAgentsModelRequestFailedError object { message, retry_status, type }`
3119 - `BetaManagedAgentsModelRequestFailedError object`
31993120
32003121 A model request failed for a reason other than overload or rate-limiting.
32013122
from line 3128
32073128
32083129 What the client should do next in response to this error.
32093130
3210 - `BetaManagedAgentsRetryStatusRetrying object { type }`
3131 - `BetaManagedAgentsRetryStatusRetrying object`
32113132
32123133 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.
32133134
3214 - `BetaManagedAgentsRetryStatusExhausted object { type }`
3135 - `BetaManagedAgentsRetryStatusExhausted object`
32153136
32163137 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
32173138
3218 - `BetaManagedAgentsRetryStatusTerminal object { type }`
3139 - `BetaManagedAgentsRetryStatusTerminal object`
32193140
32203141 The session encountered a terminal error and will transition to `terminated` state.
32213142
32223143 - `type: "model_request_failed_error"`
32233144
3224 - `"model_request_failed_error"`
3225
3226 - `BetaManagedAgentsMCPConnectionFailedError object { mcp_server_name, message, retry_status, type }`
3145 - `BetaManagedAgentsMCPConnectionFailedError object`
32273146
32283147 Failed to connect to an MCP server.
32293148
from line 3158
32393158
32403159 What the client should do next in response to this error.
32413160
3242 - `BetaManagedAgentsRetryStatusRetrying object { type }`
3161 - `BetaManagedAgentsRetryStatusRetrying object`
32433162
32443163 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.
32453164
3246 - `BetaManagedAgentsRetryStatusExhausted object { type }`
3165 - `BetaManagedAgentsRetryStatusExhausted object`
32473166
32483167 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
32493168
3250 - `BetaManagedAgentsRetryStatusTerminal object { type }`
3169 - `BetaManagedAgentsRetryStatusTerminal object`
32513170
32523171 The session encountered a terminal error and will transition to `terminated` state.
32533172
32543173 - `type: "mcp_connection_failed_error"`
32553174
3256 - `"mcp_connection_failed_error"`
3257
3258 - `BetaManagedAgentsMCPAuthenticationFailedError object { mcp_server_name, message, retry_status, type }`
3175 - `BetaManagedAgentsMCPAuthenticationFailedError object`
32593176
32603177 Authentication to an MCP server failed.
32613178
from line 3188
32713188
32723189 What the client should do next in response to this error.
32733190
3274 - `BetaManagedAgentsRetryStatusRetrying object { type }`
3191 - `BetaManagedAgentsRetryStatusRetrying object`
32753192
32763193 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.
32773194
3278 - `BetaManagedAgentsRetryStatusExhausted object { type }`
3195 - `BetaManagedAgentsRetryStatusExhausted object`
32793196
32803197 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
32813198
3282 - `BetaManagedAgentsRetryStatusTerminal object { type }`
3199 - `BetaManagedAgentsRetryStatusTerminal object`
32833200
32843201 The session encountered a terminal error and will transition to `terminated` state.
32853202
32863203 - `type: "mcp_authentication_failed_error"`
32873204
3288 - `"mcp_authentication_failed_error"`
3289
3290 - `BetaManagedAgentsBillingError object { message, retry_status, type }`
3205 - `BetaManagedAgentsBillingError object`
32913206
32923207 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.
32933208
from line 3214
32993214
33003215 What the client should do next in response to this error.
33013216
3302 - `BetaManagedAgentsRetryStatusRetrying object { type }`
3217 - `BetaManagedAgentsRetryStatusRetrying object`
33033218
33043219 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.
33053220
3306 - `BetaManagedAgentsRetryStatusExhausted object { type }`
3221 - `BetaManagedAgentsRetryStatusExhausted object`
33073222
33083223 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
33093224
3310 - `BetaManagedAgentsRetryStatusTerminal object { type }`
3225 - `BetaManagedAgentsRetryStatusTerminal object`
33113226
33123227 The session encountered a terminal error and will transition to `terminated` state.
33133228
33143229 - `type: "billing_error"`
33153230
3316 - `"billing_error"`
3317
3318 - `BetaManagedAgentsCredentialHostUnreachableError object { credential_id, message, retry_status, 2 more }`
3231 - `BetaManagedAgentsCredentialHostUnreachableError object`
33193232
33203233 An `environment_variable` credential's `auth.networking.allowed_hosts` includes a host the environment's network policy does not permit.
33213234
from line 3244
33313244
33323245 What the client should do next in response to this error.
33333246
3334 - `BetaManagedAgentsRetryStatusRetrying object { type }`
3247 - `BetaManagedAgentsRetryStatusRetrying object`
33353248
33363249 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.
33373250
3338 - `BetaManagedAgentsRetryStatusExhausted object { type }`
3251 - `BetaManagedAgentsRetryStatusExhausted object`
33393252
33403253 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
33413254
3342 - `BetaManagedAgentsRetryStatusTerminal object { type }`
3255 - `BetaManagedAgentsRetryStatusTerminal object`
33433256
33443257 The session encountered a terminal error and will transition to `terminated` state.
33453258
33463259 - `type: "credential_host_unreachable_error"`
33473260
3348 - `"credential_host_unreachable_error"`
3349
33503261 - `vault_id: string`
33513262
33523263 ID of the vault containing the affected credential.
from line 3266
33553266
33563267 A timestamp in RFC 3339 format
33573268
3269 format: date-time
3270
33583271 - `type: "session.error"`
33593272
3360 - `"session.error"`
3361
3362 - `BetaManagedAgentsSessionStatusRescheduledEvent object { id, processed_at, type }`
3273 - `BetaManagedAgentsSessionStatusRescheduledEvent object`
33633274
33643275 Indicates the session is recovering from an error state and is rescheduled for execution.
33653276
from line 3282
33713282
33723283 A timestamp in RFC 3339 format
33733284
3285 format: date-time
3286
33743287 - `type: "session.status_rescheduled"`
33753288
3376 - `"session.status_rescheduled"`
3377
3378 - `BetaManagedAgentsSessionStatusRunningEvent object { id, processed_at, type }`
3289 - `BetaManagedAgentsSessionStatusRunningEvent object`
33793290
33803291 Indicates the session is actively running and the agent is working.
33813292
from line 3298
33873298
33883299 A timestamp in RFC 3339 format
33893300
3301 format: date-time
3302
33903303 - `type: "session.status_running"`
33913304
3392 - `"session.status_running"`
3393
3394 - `BetaManagedAgentsSessionStatusIdleEvent object { id, processed_at, stop_reason, type }`
3305 - `BetaManagedAgentsSessionStatusIdleEvent object`
33953306
33963307 Indicates the agent has paused and is awaiting user input.
33973308
from line 3314
34033314
34043315 A timestamp in RFC 3339 format
34053316
3317 format: date-time
3318
34063319 - `stop_reason: BetaManagedAgentsSessionEndTurn or BetaManagedAgentsSessionRequiresAction or BetaManagedAgentsSessionRetriesExhausted or BetaManagedAgentsSessionBudgetReached`
34073320
34083321 The agent completed its turn naturally and is ready for the next user message.
34093322
3410 - `BetaManagedAgentsSessionEndTurn object { type }`
3323 - `BetaManagedAgentsSessionEndTurn object`
34113324
34123325 The agent completed its turn naturally and is ready for the next user message.
34133326
34143327 - `type: "end_turn"`
34153328
3416 - `"end_turn"`
3417
3418 - `BetaManagedAgentsSessionRequiresAction object { event_ids, type }`
3329 - `BetaManagedAgentsSessionRequiresAction object`
34193330
34203331 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.
34213332
from line 3336
34253336
34263337 - `type: "requires_action"`
34273338
3428 - `"requires_action"`
3429
3430 - `BetaManagedAgentsSessionRetriesExhausted object { type }`
3339 - `BetaManagedAgentsSessionRetriesExhausted object`
34313340
34323341 The turn ended because repeated errors exhausted the retry budget or an error escalated to `retry_status: 'exhausted'`.
34333342
34343343 - `type: "retries_exhausted"`
34353344
3436 - `"retries_exhausted"`
3437
3438 - `BetaManagedAgentsSessionBudgetReached object { type }`
3345 - `BetaManagedAgentsSessionBudgetReached object`
34393346
34403347 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.
34413348
34423349 - `type: "budget_reached"`
34433350
3444 - `"budget_reached"`
3445
34463351 - `type: "session.status_idle"`
34473352
3448 - `"session.status_idle"`
3449
3450 - `BetaManagedAgentsSessionStatusTerminatedEvent object { id, processed_at, type }`
3353 - `BetaManagedAgentsSessionStatusTerminatedEvent object`
34513354
34523355 Indicates the session has terminated, either due to an error or completion.
34533356
from line 3362
34593362
34603363 A timestamp in RFC 3339 format
34613364
3365 format: date-time
3366
34623367 - `type: "session.status_terminated"`
34633368
3464 - `"session.status_terminated"`
3465
3466 - `BetaManagedAgentsSessionThreadCreatedEvent object { id, agent_name, processed_at, 2 more }`
3369 - `BetaManagedAgentsSessionThreadCreatedEvent object`
34673370
34683371 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.
34693372
from line 3382
34793382
34803383 A timestamp in RFC 3339 format
34813384
3385 format: date-time
3386
34823387 - `session_thread_id: string`
34833388
34843389 Public `sthr_` ID of the newly created thread.
34853390
34863391 - `type: "session.thread_created"`
34873392
3488 - `"session.thread_created"`
3489
3490 - `BetaManagedAgentsSpanOutcomeEvaluationStartEvent object { id, iteration, outcome_id, 2 more }`
3393 - `BetaManagedAgentsSpanOutcomeEvaluationStartEvent object`
34913394
34923395 Emitted when an outcome evaluation cycle begins.
34933396
from line 3402
34993402
35003403 0-indexed revision cycle. 0 is the first evaluation; 1 is the re-evaluation after the first revision; etc.
35013404
3405 format: int32
3406
35023407 - `outcome_id: string`
35033408
35043409 The `outc_` ID of the outcome being evaluated.
from line 3412
35073412
35083413 A timestamp in RFC 3339 format
35093414
3415 format: date-time
3416
35103417 - `type: "span.outcome_evaluation_start"`
35113418
3512 - `"span.outcome_evaluation_start"`
3513
3514 - `BetaManagedAgentsSpanOutcomeEvaluationEndEvent object { id, explanation, iteration, 6 more }`
3419 - `BetaManagedAgentsSpanOutcomeEvaluationEndEvent object`
35153420
35163421 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.
35173422
from line 3432
35273432
35283433 0-indexed revision cycle, matching the corresponding `span.outcome_evaluation_start`.
35293434
3435 format: int32
3436
35303437 - `outcome_evaluation_start_id: string`
35313438
35323439 The id of the corresponding `span.outcome_evaluation_start` event.
from line 3446
35393446
35403447 A timestamp in RFC 3339 format
35413448
3449 format: date-time
3450
35423451 - `result: string`
35433452
35443453 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.
35453454
35463455 - `type: "span.outcome_evaluation_end"`
35473456
3548 - `"span.outcome_evaluation_end"`
3549
35503457 - `usage: BetaManagedAgentsSpanModelUsage`
35513458
35523459 Token usage for a single model request.
from line 3462
35553462
35563463 Tokens used to create prompt cache in this request.
35573464
3465 format: int32
3466
35583467 - `cache_read_input_tokens: number`
35593468
35603469 Tokens read from prompt cache in this request.
35613470
3471 format: int32
3472
35623473 - `input_tokens: number`
35633474
35643475 Input tokens consumed by this request.
35653476
3477 format: int32
3478
35663479 - `output_tokens: number`
35673480
35683481 Output tokens generated by this request.
35693482
3483 format: int32
3484
35703485 - `speed: optional "standard" or "fast" or null`
35713486
35723487 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 3490
35753490
35763491 - `"fast"`
35773492
3578 - `BetaManagedAgentsSpanModelRequestStartEvent object { id, processed_at, type }`
3493 - `BetaManagedAgentsSpanModelRequestStartEvent object`
35793494
35803495 Emitted when a model request is initiated by the agent.
35813496
from line 3502
35873502
35883503 A timestamp in RFC 3339 format
35893504
3505 format: date-time
3506
35903507 - `type: "span.model_request_start"`
35913508
3592 - `"span.model_request_start"`
3593
3594 - `BetaManagedAgentsSpanModelRequestEndEvent object { id, is_error, model_request_start_id, 3 more }`
3509 - `BetaManagedAgentsSpanModelRequestEndEvent object`
35953510
35963511 Emitted when a model request completes.
35973512
from line 3530
36153530
36163531 A timestamp in RFC 3339 format
36173532
3533 format: date-time
3534
36183535 - `type: "span.model_request_end"`
36193536
3620 - `"span.model_request_end"`
3621
3622 - `BetaManagedAgentsSpanOutcomeEvaluationOngoingEvent object { id, iteration, outcome_id, 2 more }`
3537 - `BetaManagedAgentsSpanOutcomeEvaluationOngoingEvent object`
36233538
36243539 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.
36253540
from line 3546
36313546
36323547 0-indexed revision cycle, matching the corresponding `span.outcome_evaluation_start`.
36333548
3549 format: int32
3550
36343551 - `outcome_id: string`
36353552
36363553 The `outc_` ID of the outcome being evaluated.
from line 3556
36393556
36403557 A timestamp in RFC 3339 format
36413558
3559 format: date-time
3560
36423561 - `type: "span.outcome_evaluation_ongoing"`
36433562
3644 - `"span.outcome_evaluation_ongoing"`
3645
3646 - `BetaManagedAgentsUserDefineOutcomeEvent object { id, description, max_iterations, 4 more }`
3563 - `BetaManagedAgentsUserDefineOutcomeEvent object`
36473564
36483565 Echo of a `user.define_outcome` input event. Carries the server-generated `outcome_id` that subsequent `span.outcome_evaluation_*` events reference.
36493566
from line 3576
36593576
36603577 Evaluate-then-revise cycles before giving up. Default 3, max 20.
36613578
3579 format: int32
3580
36623581 - `outcome_id: string`
36633582
36643583 Server-generated `outc_` ID for this outcome. Referenced by `span.outcome_evaluation_*` events and the session's `outcome_evaluations` list.
from line 3586
36673586
36683587 A timestamp in RFC 3339 format
36693588
3589 format: date-time
3590
36703591 - `rubric: BetaManagedAgentsFileRubric or BetaManagedAgentsTextRubric`
36713592
36723593 Rubric for grading the quality of an outcome.
36733594
3674 - `BetaManagedAgentsFileRubric object { file_id, type }`
3595 - `BetaManagedAgentsFileRubric object`
36753596
36763597 Rubric referenced by a file uploaded via the Files API.
36773598
from line 3602
36813602
36823603 - `type: "file"`
36833604
3684 - `"file"`
3685
3686 - `BetaManagedAgentsTextRubric object { content, type }`
3605 - `BetaManagedAgentsTextRubric object`
36873606
36883607 Rubric content provided inline as text.
36893608
from line 3612
36933612
36943613 - `type: "text"`
36953614
3696 - `"text"`
3697
36983615 - `type: "user.define_outcome"`
36993616
3700 - `"user.define_outcome"`
3701
3702 - `BetaManagedAgentsSessionDeletedEvent object { id, processed_at, type }`
3617 - `BetaManagedAgentsSessionDeletedEvent object`
37033618
37043619 Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session.
37053620
from line 3626
37113626
37123627 A timestamp in RFC 3339 format
37133628
3629 format: date-time
3630
37143631 - `type: "session.deleted"`
37153632
3716 - `"session.deleted"`
3717
3718 - `BetaManagedAgentsSessionThreadStatusRunningEvent object { id, agent_name, processed_at, 2 more }`
3633 - `BetaManagedAgentsSessionThreadStatusRunningEvent object`
37193634
37203635 A session thread has begun executing. Emitted on the thread's own stream and cross-posted to the primary stream for child threads.
37213636
from line 3646
37313646
37323647 A timestamp in RFC 3339 format
37333648
3649 format: date-time
3650
37343651 - `session_thread_id: string`
37353652
37363653 Public sthr_ ID of the thread that started running.
37373654
37383655 - `type: "session.thread_status_running"`
37393656
3740 - `"session.thread_status_running"`
3741
3742 - `BetaManagedAgentsSessionThreadStatusIdleEvent object { id, agent_name, processed_at, 3 more }`
3657 - `BetaManagedAgentsSessionThreadStatusIdleEvent object`
37433658
37443659 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.
37453660
from line 3670
37553670
37563671 A timestamp in RFC 3339 format
37573672
3673 format: date-time
3674
37583675 - `session_thread_id: string`
37593676
37603677 Public sthr_ ID of the thread that went idle.
from line 3680
37633680
37643681 The agent completed its turn naturally and is ready for the next user message.
37653682
3766 - `BetaManagedAgentsSessionEndTurn object { type }`
3683 - `BetaManagedAgentsSessionEndTurn object`
37673684
37683685 The agent completed its turn naturally and is ready for the next user message.
37693686
3770 - `BetaManagedAgentsSessionRequiresAction object { event_ids, type }`
3687 - `BetaManagedAgentsSessionRequiresAction object`
37713688
37723689 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.
37733690
3774 - `BetaManagedAgentsSessionRetriesExhausted object { type }`
3691 - `BetaManagedAgentsSessionRetriesExhausted object`
37753692
37763693 The turn ended because repeated errors exhausted the retry budget or an error escalated to `retry_status: 'exhausted'`.
37773694
3778 - `BetaManagedAgentsSessionBudgetReached object { type }`
3695 - `BetaManagedAgentsSessionBudgetReached object`
37793696
37803697 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.
37813698
37823699 - `type: "session.thread_status_idle"`
37833700
3784 - `"session.thread_status_idle"`
3785
3786 - `BetaManagedAgentsSessionThreadStatusTerminatedEvent object { id, agent_name, processed_at, 2 more }`
3701 - `BetaManagedAgentsSessionThreadStatusTerminatedEvent object`
37873702
37883703 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.
37893704
from line 3714
37993714
38003715 A timestamp in RFC 3339 format
38013716
3717 format: date-time
3718
38023719 - `session_thread_id: string`
38033720
38043721 Public sthr_ ID of the thread that terminated.
38053722
38063723 - `type: "session.thread_status_terminated"`
38073724
3808 - `"session.thread_status_terminated"`
3809
3810 - `BetaManagedAgentsUserToolResultEvent object { id, tool_use_id, type, 4 more }`
3725 - `BetaManagedAgentsUserToolResultEvent object`
38113726
38123727 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.
38133728
from line 3736
38213736
38223737 - `type: "user.tool_result"`
38233738
3824 - `"user.tool_result"`
3825
38263739 - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock`
38273740
38283741 The result content returned by the tool.
38293742
3830 - `BetaManagedAgentsTextBlock object { text, type }`
3743 - `BetaManagedAgentsTextBlock object`
38313744
38323745 Regular text content.
38333746
3834 - `BetaManagedAgentsImageBlock object { source, type }`
3747 - `BetaManagedAgentsImageBlock object`
38353748
38363749 Image content specified directly as base64 data or as a reference via a URL.
38373750
3838 - `BetaManagedAgentsDocumentBlock object { source, type, context, title }`
3751 - `BetaManagedAgentsDocumentBlock object`
38393752
38403753 Document content, either specified directly as base64 data, as text, or as a reference via a URL.
38413754
3842 - `BetaManagedAgentsSearchResultBlock object { citations, content, source, 2 more }`
3755 - `BetaManagedAgentsSearchResultBlock object`
38433756
38443757 A block containing a web search result.
38453758
from line 3764
38513764
38523765 A timestamp in RFC 3339 format
38533766
3767 format: date-time
3768
38543769 - `session_thread_id: optional string or null`
38553770
38563771 Routes this result to a subagent thread. Copy from the `agent.tool_use` event's `session_thread_id`.
38573772
3858 - `BetaManagedAgentsSessionThreadStatusRescheduledEvent object { id, agent_name, processed_at, 2 more }`
3773 - `BetaManagedAgentsSessionThreadStatusRescheduledEvent object`
38593774
38603775 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.
38613776
from line 3786
38713786
38723787 A timestamp in RFC 3339 format
38733788
3789 format: date-time
3790
38743791 - `session_thread_id: string`
38753792
38763793 Public sthr_ ID of the thread that is retrying.
38773794
38783795 - `type: "session.thread_status_rescheduled"`
38793796
3880 - `"session.thread_status_rescheduled"`
3881
3882 - `BetaManagedAgentsSessionUpdatedEvent object { id, processed_at, type, 4 more }`
3797 - `BetaManagedAgentsSessionUpdatedEvent object`
38833798
38843799 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.
38853800
from line 3806
38913806
38923807 A timestamp in RFC 3339 format
38933808
3809 format: date-time
3810
38943811 - `type: "session.updated"`
38953812
3896 - `"session.updated"`
3897
38983813 - `agent: optional BetaManagedAgentsSessionAgent or null`
38993814
39003815 Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time.
from line 3824
39093824
39103825 - `type: "url"`
39113826
3912 - `"url"`
3913
39143827 - `url: string`
39153828
39163829 - `model: BetaManagedAgentsModelConfig`
from line 3900
39873900
39883901 How hard Claude works on each turn. Sets `output_config.effort` on every Messages call the session makes.
39893902
3990 - `BetaManagedAgentsEffortLow object { type }`
3903 - `BetaManagedAgentsEffortLow object`
39913904
39923905 Low effort. Favors latency over reasoning depth.
39933906
39943907 - `type: "low"`
39953908
3996 - `"low"`
3997
3998 - `BetaManagedAgentsEffortMedium object { type }`
3909 - `BetaManagedAgentsEffortMedium object`
39993910
40003911 Medium effort. Balances latency and reasoning depth.
40013912
40023913 - `type: "medium"`
40033914
4004 - `"medium"`
4005
4006 - `BetaManagedAgentsEffortHigh object { type }`
3915 - `BetaManagedAgentsEffortHigh object`
40073916
40083917 High effort. Favors reasoning depth.
40093918
40103919 - `type: "high"`
40113920
4012 - `"high"`
4013
4014 - `BetaManagedAgentsEffortXhigh object { type }`
3921 - `BetaManagedAgentsEffortXhigh object`
40153922
40163923 Extra-high effort. Not all models accept this level.
40173924
40183925 - `type: "xhigh"`
40193926
4020 - `"xhigh"`
4021
4022 - `BetaManagedAgentsEffortMax object { type }`
3927 - `BetaManagedAgentsEffortMax object`
40233928
40243929 Maximum effort. Favors reasoning depth over latency.
40253930
40263931 - `type: "max"`
40273932
4028 - `"max"`
4029
40303933 - `inference_geo: optional string`
40313934
40323935 Geographic region for model inference. When unset, requests fall through to the workspace's default_inference_geo.
from line 3950
40473950
40483951 Full `agent` definitions the coordinator may spawn as session threads.
40493952
4050 - `BetaManagedAgentsSessionThreadAgent object { id, description, mcp_servers, 7 more }`
3953 - `BetaManagedAgentsSessionThreadAgent object`
40513954
40523955 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`.
40533956
from line 3974
40713974
40723975 - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill`
40733976
4074 - `BetaManagedAgentsAnthropicSkill object { skill_id, type, version }`
3977 - `BetaManagedAgentsAnthropicSkill object`
40753978
40763979 A resolved Anthropic-managed skill.
40773980
from line 3982
40793982
40803983 - `type: "anthropic"`
40813984
4082 - `"anthropic"`
4083
40843985 - `version: string`
40853986
4086 - `BetaManagedAgentsCustomSkill object { skill_id, type, version }`
3987 - `BetaManagedAgentsCustomSkill object`
40873988
40883989 A resolved user-created custom skill.
40893990
from line 3992
40913992
40923993 - `type: "custom"`
40933994
4094 - `"custom"`
4095
40963995 - `version: string`
40973996
40983997 - `system: string or null`
40993998
41003999 - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool`
41014000
4102 - `BetaManagedAgentsAgentToolset20260401 object { configs, default_config, type }`
4001 - `BetaManagedAgentsAgentToolset20260401 object`
41034002
41044003 - `configs: array of BetaManagedAgentsAgentToolConfig`
41054004
4106 - `BetaManagedAgentsBashToolConfig object { enabled, name, permission_policy, type }`
4005 - `BetaManagedAgentsBashToolConfig object`
41074006
41084007 Configuration for the bash tool.
41094008
from line 4010
41114010
41124011 - `name: "bash"`
41134012
4114 - `"bash"`
4115
41164013 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
41174014
41184015 Permission policy for tool execution.
41194016
4120 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
4017 - `BetaManagedAgentsAlwaysAllowPolicy object`
41214018
41224019 Tool calls are automatically approved without user confirmation.
41234020
41244021 - `type: "always_allow"`
41254022
4126 - `"always_allow"`
4127
4128 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
4023 - `BetaManagedAgentsAlwaysAskPolicy object`
41294024
41304025 Tool calls require user confirmation before execution.
41314026
41324027 - `type: "always_ask"`
41334028
4134 - `"always_ask"`
4135
41364029 - `type: "bash"`
41374030
4138 - `"bash"`
4139
4140 - `BetaManagedAgentsEditToolConfig object { enabled, name, permission_policy, type }`
4031 - `BetaManagedAgentsEditToolConfig object`
41414032
41424033 Configuration for the edit tool.
41434034
from line 4036
41454036
41464037 - `name: "edit"`
41474038
4148 - `"edit"`
4149
41504039 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
41514040
41524041 Permission policy for tool execution.
41534042
4154 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
4043 - `BetaManagedAgentsAlwaysAllowPolicy object`
41554044
41564045 Tool calls are automatically approved without user confirmation.
41574046
4158 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
4047 - `BetaManagedAgentsAlwaysAskPolicy object`
41594048
41604049 Tool calls require user confirmation before execution.
41614050
41624051 - `type: "edit"`
41634052
4164 - `"edit"`
4165
4166 - `BetaManagedAgentsReadToolConfig object { enabled, name, permission_policy, type }`
4053 - `BetaManagedAgentsReadToolConfig object`
41674054
41684055 Configuration for the read tool.
41694056
from line 4058
41714058
41724059 - `name: "read"`
41734060
4174 - `"read"`
4175
41764061 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
41774062
41784063 Permission policy for tool execution.
41794064
4180 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
4065 - `BetaManagedAgentsAlwaysAllowPolicy object`
41814066
41824067 Tool calls are automatically approved without user confirmation.
41834068
4184 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
4069 - `BetaManagedAgentsAlwaysAskPolicy object`
41854070
41864071 Tool calls require user confirmation before execution.
41874072
41884073 - `type: "read"`
41894074
4190 - `"read"`
4191
4192 - `BetaManagedAgentsWriteToolConfig object { enabled, name, permission_policy, type }`
4075 - `BetaManagedAgentsWriteToolConfig object`
41934076
41944077 Configuration for the write tool.
41954078
from line 4080
41974080
41984081 - `name: "write"`
41994082
4200 - `"write"`
4201
42024083 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
42034084
42044085 Permission policy for tool execution.
42054086
4206 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
4087 - `BetaManagedAgentsAlwaysAllowPolicy object`
42074088
42084089 Tool calls are automatically approved without user confirmation.
42094090
4210 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
4091 - `BetaManagedAgentsAlwaysAskPolicy object`
42114092
42124093 Tool calls require user confirmation before execution.
42134094
42144095 - `type: "write"`
42154096
4216 - `"write"`
4217
4218 - `BetaManagedAgentsGlobToolConfig object { enabled, name, permission_policy, type }`
4097 - `BetaManagedAgentsGlobToolConfig object`
42194098
42204099 Configuration for the glob tool.
42214100
from line 4102
42234102
42244103 - `name: "glob"`
42254104
4226 - `"glob"`
4227
42284105 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
42294106
42304107 Permission policy for tool execution.
42314108
4232 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
4109 - `BetaManagedAgentsAlwaysAllowPolicy object`
42334110
42344111 Tool calls are automatically approved without user confirmation.
42354112
4236 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
4113 - `BetaManagedAgentsAlwaysAskPolicy object`
42374114
42384115 Tool calls require user confirmation before execution.
42394116
42404117 - `type: "glob"`
42414118
4242 - `"glob"`
4243
4244 - `BetaManagedAgentsGrepToolConfig object { enabled, name, permission_policy, type }`
4119 - `BetaManagedAgentsGrepToolConfig object`
42454120
42464121 Configuration for the grep tool.
42474122
from line 4124
42494124
42504125 - `name: "grep"`
42514126
4252 - `"grep"`
4253
42544127 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
42554128
42564129 Permission policy for tool execution.
42574130
4258 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
4131 - `BetaManagedAgentsAlwaysAllowPolicy object`
42594132
42604133 Tool calls are automatically approved without user confirmation.
42614134
4262 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
4135 - `BetaManagedAgentsAlwaysAskPolicy object`
42634136
42644137 Tool calls require user confirmation before execution.
42654138
42664139 - `type: "grep"`
42674140
4268 - `"grep"`
4269
4270 - `BetaManagedAgentsWebFetchToolConfig object { enabled, name, permission_policy, 4 more }`
4141 - `BetaManagedAgentsWebFetchToolConfig object`
42714142
42724143 Configuration for the web_fetch tool.
42734144
from line 4146
42754146
42764147 - `name: "web_fetch"`
42774148
4278 - `"web_fetch"`
4279
42804149 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
42814150
42824151 Permission policy for tool execution.
42834152
4284 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
4153 - `BetaManagedAgentsAlwaysAllowPolicy object`
42854154
42864155 Tool calls are automatically approved without user confirmation.
42874156
4288 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
4157 - `BetaManagedAgentsAlwaysAskPolicy object`
42894158
42904159 Tool calls require user confirmation before execution.
42914160
42924161 - `type: "web_fetch"`
42934162
4294 - `"web_fetch"`
4295
42964163 - `allowed_domains: optional array of string`
42974164
42984165 - `blocked_domains: optional array of string`
42994166
43004167 - `max_content_tokens: optional number or null`
43014168
4302 - `BetaManagedAgentsWebSearchToolConfig object { enabled, name, permission_policy, 4 more }`
4169 format: int32
4170
4171 - `BetaManagedAgentsWebSearchToolConfig object`
43034172
43044173 Configuration for the web_search tool.
43054174
from line 4176
43074176
43084177 - `name: "web_search"`
43094178
4310 - `"web_search"`
4311
43124179 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
43134180
43144181 Permission policy for tool execution.
43154182
4316 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
4183 - `BetaManagedAgentsAlwaysAllowPolicy object`
43174184
43184185 Tool calls are automatically approved without user confirmation.
43194186
4320 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
4187 - `BetaManagedAgentsAlwaysAskPolicy object`
43214188
43224189 Tool calls require user confirmation before execution.
43234190
43244191 - `type: "web_search"`
43254192
4326 - `"web_search"`
4327
43284193 - `allowed_domains: optional array of string`
43294194
43304195 - `blocked_domains: optional array of string`
from line 4202
43374202
43384203 Location precision. Only "approximate" is supported.
43394204
4340 - `"approximate"`
4341
43424205 - `city: optional string or null`
43434206
43444207 City name.
43454208
4209 minLength: 1, maxLength: 255
4210
43464211 - `country: optional string or null`
43474212
43484213 Two-letter ISO 3166-1 country code, uppercase.
from line 4216
43514216
43524217 Region or state name.
43534218
4219 minLength: 1, maxLength: 255
4220
43544221 - `timezone: optional string or null`
43554222
43564223 IANA timezone identifier, e.g. "America/Los_Angeles".
43574224
4225 minLength: 1, maxLength: 255
4226
43584227 - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig`
43594228
43604229 Resolved default configuration for agent tools.
from line 4234
43654234
43664235 Permission policy for tool execution.
43674236
4368 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
4237 - `BetaManagedAgentsAlwaysAllowPolicy object`
43694238
43704239 Tool calls are automatically approved without user confirmation.
43714240
4372 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
4241 - `BetaManagedAgentsAlwaysAskPolicy object`
43734242
43744243 Tool calls require user confirmation before execution.
43754244
43764245 - `type: "agent_toolset_20260401"`
43774246
4378 - `"agent_toolset_20260401"`
4379
4380 - `BetaManagedAgentsMCPToolset object { configs, default_config, mcp_server_name, type }`
4247 - `BetaManagedAgentsMCPToolset object`
43814248
43824249 - `configs: array of BetaManagedAgentsMCPToolConfig`
43834250
from line 4256
43894256
43904257 Permission policy for tool execution.
43914258
4392 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
4259 - `BetaManagedAgentsAlwaysAllowPolicy object`
43934260
43944261 Tool calls are automatically approved without user confirmation.
43954262
4396 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
4263 - `BetaManagedAgentsAlwaysAskPolicy object`
43974264
43984265 Tool calls require user confirmation before execution.
43994266
from line 4274
44074274
44084275 Permission policy for tool execution.
44094276
4410 - `BetaManagedAgentsAlwaysAllowPolicy object { type }`
4277 - `BetaManagedAgentsAlwaysAllowPolicy object`
44114278
44124279 Tool calls are automatically approved without user confirmation.
44134280
4414 - `BetaManagedAgentsAlwaysAskPolicy object { type }`
4281 - `BetaManagedAgentsAlwaysAskPolicy object`
44154282
44164283 Tool calls require user confirmation before execution.
44174284
from line 4286
44194286
44204287 - `type: "mcp_toolset"`
44214288
4422 - `"mcp_toolset"`
4423
4424 - `BetaManagedAgentsCustomTool object { description, input_schema, name, type }`
4289 - `BetaManagedAgentsCustomTool object`
44254290
44264291 A custom tool as returned in API responses.
44274292
from line 4298
44334298
44344299 - `type: "object"`
44354300
4436 - `"object"`
4437
44384301 - `properties: optional map[unknown] or null`
44394302
44404303 - `required: optional array of string or null`
from line 4306
44434306
44444307 - `type: "custom"`
44454308
4446 - `"custom"`
4447
44484309 - `type: "agent"`
44494310
4450 - `"agent"`
4451
44524311 - `version: number`
44534312
4454 - `BetaManagedAgentsAdvisor object { model, type }`
4313 format: int32
4314
4315 - `BetaManagedAgentsAdvisor object`
44554316
44564317 Platform advisor roster entry: a model the session's primary thread may consult mid-turn.
44574318
from line 4322
44614322
44624323 - `type: "advisor"`
44634324
4464 - `"advisor"`
4465
44664325 - `type: "coordinator"`
44674326
4468 - `"coordinator"`
4469
44704327 - `name: string`
44714328
44724329 - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill`
44734330
4474 - `BetaManagedAgentsAnthropicSkill object { skill_id, type, version }`
4331 - `BetaManagedAgentsAnthropicSkill object`
44754332
44764333 A resolved Anthropic-managed skill.
44774334
4478 - `BetaManagedAgentsCustomSkill object { skill_id, type, version }`
4335 - `BetaManagedAgentsCustomSkill object`
44794336
44804337 A resolved user-created custom skill.
44814338
from line 4340
44834340
44844341 - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool`
44854342
4486 - `BetaManagedAgentsAgentToolset20260401 object { configs, default_config, type }`
4487
4488 - `BetaManagedAgentsMCPToolset object { configs, default_config, mcp_server_name, type }`
4489
4490 - `BetaManagedAgentsCustomTool object { description, input_schema, name, type }`
4343 - `BetaManagedAgentsAgentToolset20260401 object`
4344
4345 - `BetaManagedAgentsMCPToolset object`
4346
4347 - `BetaManagedAgentsCustomTool object`
44914348
44924349 A custom tool as returned in API responses.
44934350
44944351 - `type: "agent"`
44954352
4496 - `"agent"`
4497
44984353 - `version: number`
44994354
4355 format: int32
4356
45004357 - `budget: optional BetaManagedAgentsBudgetLimit or null`
45014358
45024359 A hard spend ceiling. The session stops issuing new model requests once the tracked list cost reaches `max_list_cost`.
from line 4370
45134370
45144371 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.
45154372
4516 - `"USD"`
4517
45184373 - `type: "limit"`
45194374
4520 - `"limit"`
4521
45224375 - `metadata: optional map[string]`
45234376
45244377 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 4380
45274380
45284381 The session's new title. Present only when the update changed it.
45294382
4530 - `BetaManagedAgentsStartEvent object { event, type }`
4383 - `BetaManagedAgentsStartEvent object`
45314384
45324385 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.
45334386
from line 4388
45354388
45364389 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.
45374390
4538 - `BetaManagedAgentsAgentMessagePreview object { id, type }`
4391 - `BetaManagedAgentsAgentMessagePreview object`
45394392
45404393 - `id: string`
45414394
from line 4396
45434396
45444397 - `type: "agent.message"`
45454398
4546 - `"agent.message"`
4547
4548 - `BetaManagedAgentsAgentThinkingPreview object { id, type }`
4399 - `BetaManagedAgentsAgentThinkingPreview object`
45494400
45504401 - `id: string`
45514402
from line 4404
45534404
45544405 - `type: "agent.thinking"`
45554406
4556 - `"agent.thinking"`
4557
45584407 - `type: "event_start"`
45594408
4560 - `"event_start"`
4561
4562 - `BetaManagedAgentsDeltaEvent object { delta, event_id, type }`
4409 - `BetaManagedAgentsDeltaEvent object`
45634410
45644411 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.
45654412
from line 4420
45734420
45744421 - `type: "content_delta"`
45754422
4576 - `"content_delta"`
4577
45784423 - `index: optional number`
45794424
45804425 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.
45814426
4427 format: uint32
4428
45824429 - `event_id: string`
45834430
45844431 The id of the event being previewed. Matches event.id on the corresponding event_start and the buffered event that reconciles the preview.
45854432
45864433 - `type: "event_delta"`
45874434
4588 - `"event_delta"`
4589
4590 - `BetaManagedAgentsSystemMessageEvent object { id, content, type, processed_at }`
4435 - `BetaManagedAgentsSystemMessageEvent object`
45914436
45924437 A mid-conversation system message event. Carries system-role content that is appended to the session as a `role: "system"` turn.
45934438
from line 4448
46034448
46044449 The text content.
46054450
4451 minLength: 1
4452
46064453 - `type: "text"`
46074454
4608 - `"text"`
4609
46104455 - `type: "system.message"`
46114456
4612 - `"system.message"`
4613
46144457 - `processed_at: optional string or null`
46154458
46164459 A timestamp in RFC 3339 format
46174460
4618 - `BetaManagedAgentsSessionUsageEvent object { id, processed_at, type, 2 more }`
4461 format: date-time
4462
4463 - `BetaManagedAgentsSessionUsageEvent object`
46194464
46204465 Periodic snapshot of the session's cumulative usage and tracked list cost.
46214466
from line 4472
46274472
46284473 A timestamp in RFC 3339 format
46294474
4475 format: date-time
4476
46304477 - `type: "session.usage"`
46314478
4632 - `"session.usage"`
4633
46344479 - `usage: BetaManagedAgentsSessionUsageSnapshot`
46354480
46364481 Point-in-time snapshot of a session's cumulative usage.
from line 4484
46394484
46404485 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.
46414486
4487 format: double
4488
46424489 - `cache_creation: optional BetaManagedAgentsCacheCreationUsage`
46434490
46444491 Prompt-cache creation token usage broken down by cache lifetime.
from line 4494
46474494
46484495 Tokens used to create 1-hour ephemeral cache entries.
46494496
4497 format: int32
4498
46504499 - `ephemeral_5m_input_tokens: optional number`
46514500
46524501 Tokens used to create 5-minute ephemeral cache entries.
46534502
4503 format: int32
4504
46544505 - `cache_read_input_tokens: optional number`
46554506
46564507 Total tokens read from prompt cache.
46574508
4509 format: int32
4510
46584511 - `input_tokens: optional number`
46594512
46604513 Total input tokens consumed across all turns.
46614514
4515 format: int32
4516
46624517 - `list_cost: optional BetaMonetaryAmount`
46634518
46644519 A monetary amount in a specific currency.
from line 4522
46674522
46684523 Total output tokens generated across all turns.
46694524
4525 format: int32
4526
46704527 - `server_tool_use: optional BetaManagedAgentsServerToolUsage`
46714528
46724529 Cumulative count of server-executed tool invocations, broken down by tool.
from line 4532
46754532
46764533 Number of server-executed web fetch requests.
46774534
4535 format: int32
4536
46784537 - `web_search_requests: optional number`
46794538
46804539 Number of server-executed web search requests.
46814540
4541 format: int32
4542
46824543 - `budget: optional BetaManagedAgentsBudgetLimit or null`
46834544
46844545 A hard spend ceiling. The session stops issuing new model requests once the tracked list cost reaches `max_list_cost`.
46854546
4547- `BetaManagedAgentsStreamSessionThreadEvents = BetaManagedAgentsUserMessageEvent or BetaManagedAgentsUserInterruptEvent or BetaManagedAgentsUserToolConfirmationEvent or 34 more`
4548
4549 Server-sent event in a single thread's stream.
4550
46864551### Example
46874552
4688```http
4553```bash
46894554curl https://api.anthropic.com/v1/sessions/$SESSION_ID/threads/$THREAD_ID/stream \
46904555 -H 'anthropic-version: 2023-06-01' \
46914556 -H 'anthropic-beta: managed-agents-2026-04-01' \
46924557 -H "X-Api-Key: $ANTHROPIC_API_KEY"
46934558```
46944559
4695#### Response
4560#### Response (200)
46964561
46974562```json
46984563{
46994564
No line in this hunk matches that.