What this read moved
351–375 of 519This capture is too large to show at once. Changes 351-375 of 519 are below, significant first; the rest are on the following screens.
api/beta/sessions/create Changed · +1722 / -1621 lines
from line 1
1---
2title: Create Session
3url: https://platform.claude.com/docs/en/api/beta/sessions/create
4---
5
16# Create Session
27
38**POST** `/v1/sessions`
from line 17
1217
1318 - `string`
1419
15 - `"message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 41 more`
20 - `"message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 42 more`
1621
1722 - `"message-batches-2024-09-24"`
1823
from line 65
6065
6166 - `"user-profiles-2026-08-18"`
6267
68 - `"user-profiles-2026-09-04"`
69
6370 - `"advisor-tool-2026-03-01"`
6471
6572 - `"managed-agents-2026-04-01"`
from line 109
102109
103110 - `"mid-conversation-system-clear-at-2026-08-21"`
104111
112- `"anthropic-workspace-id": optional string`
113
105114## Body parameters
106115
107116- `agent: string or BetaManagedAgentsAgentParams or BetaManagedAgentsAgentWithOverridesParams`
from line 123
114123
115124 Specification for an Agent. Provide a specific `version` or use the short-form `agent="agent_id"` for the most recent version
116125
126 - `type: "agent"`
127
117128 - `id: string`
118129
119130 The `agent` ID.
from line 131
120131
121132 minLength: 1, maxLength: 128
122133
123 - `type: "agent"`
124
125134 - `version: optional number`
126135
127136 The specific `agent` version to use. Omit to use the latest version. Must be at least 1 if specified.
from line 141
132141
133142 Reference to an `agent` plus optional configuration overrides. Each provided field replaces the agent's value for the caller's use; the agent resource is unchanged.
134143
144 - `type: "agent_with_overrides"`
145
135146 - `id: string`
136147
137148 The `agent` ID.
from line 149
138149
139150 minLength: 1, maxLength: 128
140151
141 - `type: "agent_with_overrides"`
142
143152 - `mcp_servers: optional array of BetaManagedAgentsURLMCPServerParams`
144153
145154 Replacement MCP server list. Full replacement: the provided array becomes the MCP servers. Send an empty array to clear; omit to preserve the agent's servers.
146155
156 - `type: "url"`
157
147158 - `name: string`
148159
149160 Unique name for this server, referenced by mcp_toolset configurations. 1-255 characters.
from line 161
150161
151162 minLength: 1, maxLength: 255
152163
153 - `type: "url"`
154
155164 - `url: string`
156165
157166 Endpoint URL for the MCP server.
from line 319
310319
311320 An Anthropic-managed skill.
312321
322 - `type: "anthropic"`
323
313324 - `skill_id: string`
314325
315326 Identifier of the Anthropic skill (e.g., "xlsx").
from line 327
316327
317328 minLength: 1, maxLength: 64
318329
319 - `type: "anthropic"`
320
321330 - `version: optional string or null`
322331
323332 Version to pin. Defaults to latest if omitted.
from line 337
328337
329338 A user-created custom skill.
330339
340 - `type: "custom"`
341
331342 - `skill_id: string`
332343
333344 Tagged ID of the custom skill (e.g., "skill_01XJ5...").
from line 345
334345
335346 minLength: 1, maxLength: 64
336347
337 - `type: "custom"`
338
339348 - `version: optional string or null`
340349
341350 Version to pin. Defaults to latest if omitted.
from line 375
366375
367376 Configuration override for the bash tool.
368377
378 - `type: optional "bash"`
379
369380 - `name: "bash"`
370381
371382 Must be "bash".
from line 385
374385
375386 Whether this tool is enabled and available to Claude. Overrides the default_config setting.
376387
377 - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or null`
388 - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null`
378389
379390 Permission policy for tool execution.
380391
from line 401
390401
391402 - `type: "always_ask"`
392403
393 - `type: optional "bash"`
404 - `BetaManagedAgentsAutoPolicy object`
394405
406 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
407
408 - `type: "auto"`
409
395410 - `BetaManagedAgentsEditToolConfigParams object`
396411
397412 Configuration override for the edit tool.
398413
414 - `type: optional "edit"`
415
399416 - `name: "edit"`
400417
401418 Must be "edit".
from line 421
404421
405422 Whether this tool is enabled and available to Claude. Overrides the default_config setting.
406423
407 - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or null`
424 - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null`
408425
409426 Permission policy for tool execution.
410427
from line 433
416433
417434 Tool calls require user confirmation before execution.
418435
419 - `type: optional "edit"`
436 - `BetaManagedAgentsAutoPolicy object`
420437
438 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
439
421440 - `BetaManagedAgentsReadToolConfigParams object`
422441
423442 Configuration override for the read tool.
424443
444 - `type: optional "read"`
445
425446 - `name: "read"`
426447
427448 Must be "read".
from line 451
430451
431452 Whether this tool is enabled and available to Claude. Overrides the default_config setting.
432453
433 - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or null`
454 - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null`
434455
435456 Permission policy for tool execution.
436457
from line 463
442463
443464 Tool calls require user confirmation before execution.
444465
445 - `type: optional "read"`
466 - `BetaManagedAgentsAutoPolicy object`
446467
468 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
469
447470 - `BetaManagedAgentsWriteToolConfigParams object`
448471
449472 Configuration override for the write tool.
450473
474 - `type: optional "write"`
475
451476 - `name: "write"`
452477
453478 Must be "write".
from line 481
456481
457482 Whether this tool is enabled and available to Claude. Overrides the default_config setting.
458483
459 - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or null`
484 - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null`
460485
461486 Permission policy for tool execution.
462487
from line 493
468493
469494 Tool calls require user confirmation before execution.
470495
471 - `type: optional "write"`
496 - `BetaManagedAgentsAutoPolicy object`
472497
498 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
499
473500 - `BetaManagedAgentsGlobToolConfigParams object`
474501
475502 Configuration override for the glob tool.
476503
504 - `type: optional "glob"`
505
477506 - `name: "glob"`
478507
479508 Must be "glob".
from line 511
482511
483512 Whether this tool is enabled and available to Claude. Overrides the default_config setting.
484513
485 - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or null`
514 - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null`
486515
487516 Permission policy for tool execution.
488517
from line 523
494523
495524 Tool calls require user confirmation before execution.
496525
497 - `type: optional "glob"`
526 - `BetaManagedAgentsAutoPolicy object`
498527
528 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
529
499530 - `BetaManagedAgentsGrepToolConfigParams object`
500531
501532 Configuration override for the grep tool.
502533
534 - `type: optional "grep"`
535
503536 - `name: "grep"`
504537
505538 Must be "grep".
from line 541
508541
509542 Whether this tool is enabled and available to Claude. Overrides the default_config setting.
510543
511 - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or null`
544 - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null`
512545
513546 Permission policy for tool execution.
514547
from line 553
520553
521554 Tool calls require user confirmation before execution.
522555
523 - `type: optional "grep"`
556 - `BetaManagedAgentsAutoPolicy object`
524557
558 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
559
525560 - `BetaManagedAgentsWebFetchToolConfigParams object`
526561
527562 Configuration override for the web_fetch tool.
528563
564 - `type: optional "web_fetch"`
565
529566 - `name: "web_fetch"`
530567
531568 Must be "web_fetch".
from line 585
548585
549586 format: int32
550587
551 - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or null`
588 - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null`
552589
553590 Permission policy for tool execution.
554591
from line 597
560597
561598 Tool calls require user confirmation before execution.
562599
563 - `type: optional "web_fetch"`
600 - `BetaManagedAgentsAutoPolicy object`
564601
602 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
603
565604 - `BetaManagedAgentsWebSearchToolConfigParams object`
566605
567606 Configuration override for the web_search tool.
568607
608 - `type: optional "web_search"`
609
569610 - `name: "web_search"`
570611
571612 Must be "web_search".
from line 623
582623
583624 Whether this tool is enabled and available to Claude. Overrides the default_config setting.
584625
585 - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or null`
626 - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null`
586627
587628 Permission policy for tool execution.
588629
from line 635
594635
595636 Tool calls require user confirmation before execution.
596637
597 - `type: optional "web_search"`
638 - `BetaManagedAgentsAutoPolicy object`
598639
640 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
641
599642 - `user_location: optional BetaManagedAgentsUserLocation or null`
600643
601644 Approximate user location for search result localization.
from line 677
634677
635678 Whether tools are enabled and available to Claude by default. Defaults to true if not specified.
636679
637 - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or null`
680 - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null`
638681
639682 Permission policy for tool execution.
640683
from line 689
646689
647690 Tool calls require user confirmation before execution.
648691
692 - `BetaManagedAgentsAutoPolicy object`
693
694 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
695
649696 - `BetaManagedAgentsMCPToolsetParams object`
650697
651698 Configuration for tools from an MCP server defined in `mcp_servers`.
652699
700 - `type: "mcp_toolset"`
701
653702 - `mcp_server_name: string`
654703
655704 Name of the MCP server. Must match a server name from the mcp_servers array. 1-255 characters.
from line 705
656705
657706 minLength: 1, maxLength: 255
658707
659 - `type: "mcp_toolset"`
660
661708 - `configs: optional array of BetaManagedAgentsMCPToolConfigParams`
662709
663710 Per-tool configuration overrides.
from line 719
672719
673720 Whether this tool is enabled. Overrides the `default_config` setting.
674721
675 - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or null`
722 - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null`
676723
677724 Permission policy for tool execution.
678725
from line 731
684731
685732 Tool calls require user confirmation before execution.
686733
734 - `BetaManagedAgentsAutoPolicy object`
735
736 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
737
687738 - `default_config: optional BetaManagedAgentsMCPToolsetDefaultConfigParams or null`
688739
689740 Default configuration for all tools from an MCP server.
from line 743
692743
693744 Whether tools are enabled by default. Defaults to true if not specified.
694745
695 - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or null`
746 - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null`
696747
697748 Permission policy for tool execution.
698749
from line 755
704755
705756 Tool calls require user confirmation before execution.
706757
758 - `BetaManagedAgentsAutoPolicy object`
759
760 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
761
707762 - `BetaManagedAgentsCustomToolParams object`
708763
709764 A custom tool that is executed by the API client rather than the agent. When the agent calls this tool, an `agent.custom_tool_use` event is emitted and the session goes idle, waiting for the client to provide the result via a `user.custom_tool_result` event.
710765
766 - `type: "custom"`
767
711768 - `description: string`
712769
713770 Description of what the tool does, shown to the agent to help it decide when to use the tool.
from line 787
730787
731788 minLength: 1, maxLength: 128
732789
733 - `type: "custom"`
734
735790 - `version: optional number`
736791
737792 The specific `agent` version to use. Omit to use the latest version.
from line 803
748803
749804 A hard spend ceiling. The session stops issuing new model requests once the tracked list cost reaches `max_list_cost`.
750805
806 - `type: "limit"`
807
751808 - `max_list_cost: BetaMonetaryAmount`
752809
753810 A monetary amount in a specific currency.
from line 817
760817
761818 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.
762819
763 - `type: "limit"`
764
765820- `initial_events: optional array of BetaManagedAgentsUserMessageEventParams or BetaManagedAgentsUserDefineOutcomeEventParams`
766821
767822 Initial events to send to the `session` at creation, processed in order. Supports `user.message` and `user.define_outcome` events. Maximum 50 events.
from line 825
770825
771826 Parameters for sending a user message to the session.
772827
828 - `type: "user.message"`
829
773830 - `content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsRedactedBlock`
774831
775832 Array of content blocks for the user message.
from line 835
778835
779836 Regular text content.
780837
838 - `type: "text"`
839
781840 - `text: string`
782841
783842 The text content.
from line 843
784843
785844 minLength: 1
786845
787 - `type: "text"`
788
789846 - `BetaManagedAgentsImageBlock object`
790847
791848 Image content specified directly as base64 data or as a reference via a URL.
792849
850 - `type: "image"`
851
793852 - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource`
794853
795854 Union type for image source variants.
from line 857
798857
799858 Base64-encoded image data.
800859
860 - `type: "base64"`
861
801862 - `data: string`
802863
803864 Base64-encoded image data.
from line 871
810871
811872 minLength: 1
812873
813 - `type: "base64"`
814
815874 - `BetaManagedAgentsURLImageSource object`
816875
817876 Image referenced by URL.
from line 887
828887
829888 Image referenced by file ID.
830889
890 - `type: "file"`
891
831892 - `file_id: string`
832893
833894 ID of a previously uploaded file.
from line 895
834895
835896 minLength: 1
836897
837 - `type: "file"`
838
839 - `type: "image"`
840
841898 - `BetaManagedAgentsDocumentBlock object`
842899
843900 Document content, either specified directly as base64 data, as text, or as a reference via a URL.
844901
902 - `type: "document"`
903
845904 - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource`
846905
847906 Union type for document source variants.
from line 909
850909
851910 Base64-encoded document data.
852911
912 - `type: "base64"`
913
853914 - `data: string`
854915
855916 Base64-encoded document data.
from line 923
862923
863924 minLength: 1
864925
865 - `type: "base64"`
866
867926 - `BetaManagedAgentsPlainTextDocumentSource object`
868927
869928 Plain text document content.
870929
930 - `type: "text"`
931
871932 - `data: string`
872933
873934 The plain text content.
from line 939
878939
879940 MIME type of the text content. Must be "text/plain".
880941
881 - `type: "text"`
882
883942 - `BetaManagedAgentsURLDocumentSource object`
884943
885944 Document referenced by URL.
from line 955
896955
897956 Document referenced by file ID.
898957
958 - `type: "file"`
959
899960 - `file_id: string`
900961
901962 ID of a previously uploaded file.
from line 963
902963
903964 minLength: 1
904965
905 - `type: "file"`
906
907 - `type: "document"`
908
909966 - `context: optional string or null`
910967
911968 Additional context about the document for the model.
from line 977
920977
921978 - `type: "redacted"`
922979
923 - `type: "user.message"`
924
925980 - `BetaManagedAgentsUserDefineOutcomeEventParams object`
926981
927982 Parameters for defining an outcome the agent should work toward. The agent begins work on receipt.
928983
984 - `type: "user.define_outcome"`
985
929986 - `description: string`
930987
931988 What the agent should produce. This is the task specification.
from line 995
938995
939996 Rubric referenced by a file uploaded via the Files API.
940997
998 - `type: "file"`
999
9411000 - `file_id: string`
9421001
9431002 ID of the rubric file.
9441003
945 - `type: "file"`
946
9471004 - `BetaManagedAgentsTextRubricParams object`
9481005
9491006 Rubric content provided inline as text.
9501007
1008 - `type: "text"`
1009
9511010 - `content: string`
9521011
9531012 Rubric content. Plain text or markdown — the grader treats it as freeform text. Maximum 262144 characters.
from line 1013
9541013
9551014 maxLength: 262144
9561015
957 - `type: "text"`
958
959 - `type: "user.define_outcome"`
960
9611016 - `max_iterations: optional number or null`
9621017
9631018 Eval→revision cycles before giving up. Default 3, max 20.
from line 1031
9761031
9771032 Mount a GitHub repository into the session's container.
9781033
979 - `authorization_token: string`
980
981 GitHub authorization token used to clone the repository.
982
983 minLength: 1, maxLength: 4096
984
9851034 - `type: "github_repository"`
9861035
9871036 - `url: string`
from line 1039
9901039
9911040 minLength: 1, maxLength: 2048
9921041
1042 - `authorization_token: optional string`
1043
1044 GitHub authorization token used to clone the repository. Required for private repositories; optional for public ones.
1045
1046 minLength: 1, maxLength: 4096
1047
9931048 - `checkout: optional BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout or null`
9941049
9951050 Branch or commit to check out. Defaults to the repository's default branch.
from line 1051
9961051
9971052 - `BetaManagedAgentsBranchCheckout object`
9981053
1054 - `type: "branch"`
1055
9991056 - `name: string`
10001057
10011058 Branch name to check out.
from line 1059
10021059
10031060 minLength: 1, maxLength: 255
10041061
1005 - `type: "branch"`
1006
10071062 - `BetaManagedAgentsCommitCheckout object`
10081063
1064 - `type: "commit"`
1065
10091066 - `sha: string`
10101067
10111068 Full commit SHA to check out.
from line 1069
10121069
10131070 minLength: 7, maxLength: 64
10141071
1015 - `type: "commit"`
1016
10171072 - `mount_path: optional string or null`
10181073
10191074 Mount path in the container. Defaults to `/workspace/<repo-name>`.
from line 1079
10241079
10251080 Mount a file uploaded via the Files API into the session.
10261081
1082 - `type: "file"`
1083
10271084 - `file_id: string`
10281085
10291086 ID of a previously uploaded file.
from line 1087
10301087
10311088 minLength: 1, maxLength: 128
10321089
1033 - `type: "file"`
1034
10351090 - `mount_path: optional string or null`
10361091
10371092 Mount path in the container. Defaults to `/mnt/session/uploads/<file_id>`.
from line 1097
10421097
10431098 Parameters for attaching a memory store to an agent session.
10441099
1100 - `type: "memory_store"`
1101
10451102 - `memory_store_id: string`
10461103
10471104 The memory store ID (memstore_...). Must belong to the caller's organization and workspace.
10481105
1049 - `type: "memory_store"`
1050
10511106 - `access: optional "read_write" or "read_only" or null`
10521107
10531108 Access mode for an attached memory store.
from line 1133
10781133
10791134 A Managed Agents `session`.
10801135
1136 - `type: "session"`
1137
10811138 - `id: string`
10821139
10831140 - `agent: BetaManagedAgentsSessionAgent`
from line 1141
10841141
10851142 Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time.
10861143
1144 - `type: "agent"`
1145
10871146 - `id: string`
10881147
10891148 - `description: string or null`
from line 1149
10901149
10911150 - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition`
10921151
1093 - `name: string`
1094
10951152 - `type: "url"`
10961153
1154 - `name: string`
1155
10971156 - `url: string`
10981157
10991158 - `model: BetaManagedAgentsModelConfig`
from line 1279
12201279
12211280 Resolved coordinator topology with full agent definitions for each roster member.
12221281
1282 - `type: "coordinator"`
1283
12231284 - `agents: array of BetaManagedAgentsSessionThreadAgent or BetaManagedAgentsAdvisor`
12241285
12251286 Full `agent` definitions the coordinator may spawn as session threads.
from line 1289
12281289
12291290 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`.
12301291
1292 - `type: "agent"`
1293
12311294 - `id: string`
12321295
12331296 - `description: string or null`
from line 1297
12341297
12351298 - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition`
12361299
1237 - `name: string`
1238
12391300 - `type: "url"`
12401301
1302 - `name: string`
1303
12411304 - `url: string`
12421305
12431306 - `model: BetaManagedAgentsModelConfig`
from line 1315
12521315
12531316 A resolved Anthropic-managed skill.
12541317
1255 - `skill_id: string`
1256
12571318 - `type: "anthropic"`
12581319
1320 - `skill_id: string`
1321
12591322 - `version: string`
12601323
12611324 - `BetaManagedAgentsCustomSkill object`
from line 1325
12621325
12631326 A resolved user-created custom skill.
12641327
1265 - `skill_id: string`
1266
12671328 - `type: "custom"`
12681329
1330 - `skill_id: string`
1331
12691332 - `version: string`
12701333
12711334 - `system: string or null`
from line 1337
12741337
12751338 - `BetaManagedAgentsAgentToolset20260401 object`
12761339
1340 - `type: "agent_toolset_20260401"`
1341
12771342 - `configs: array of BetaManagedAgentsAgentToolConfig`
12781343
12791344 - `BetaManagedAgentsBashToolConfig object`
from line 1345
12801345
12811346 Configuration for the bash tool.
12821347
1348 - `type: "bash"`
1349
12831350 - `enabled: boolean`
12841351
12851352 - `name: "bash"`
12861353
1287 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
1354 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
12881355
12891356 Permission policy for tool execution.
12901357
from line 1367
13001367
13011368 - `type: "always_ask"`
13021369
1303 - `type: "bash"`
1370 - `BetaManagedAgentsAutoPolicy object`
13041371
1372 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
1373
1374 - `type: "auto"`
1375
13051376 - `BetaManagedAgentsEditToolConfig object`
13061377
13071378 Configuration for the edit tool.
13081379
1380 - `type: "edit"`
1381
13091382 - `enabled: boolean`
13101383
13111384 - `name: "edit"`
13121385
1313 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
1386 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
13141387
13151388 Permission policy for tool execution.
13161389
from line 1395
13221395
13231396 Tool calls require user confirmation before execution.
13241397
1325 - `type: "edit"`
1398 - `BetaManagedAgentsAutoPolicy object`
13261399
1400 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
1401
13271402 - `BetaManagedAgentsReadToolConfig object`
13281403
13291404 Configuration for the read tool.
13301405
1406 - `type: "read"`
1407
13311408 - `enabled: boolean`
13321409
13331410 - `name: "read"`
13341411
1335 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
1412 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
13361413
13371414 Permission policy for tool execution.
13381415
from line 1421
13441421
13451422 Tool calls require user confirmation before execution.
13461423
1347 - `type: "read"`
1424 - `BetaManagedAgentsAutoPolicy object`
13481425
1426 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
1427
13491428 - `BetaManagedAgentsWriteToolConfig object`
13501429
13511430 Configuration for the write tool.
13521431
1432 - `type: "write"`
1433
13531434 - `enabled: boolean`
13541435
13551436 - `name: "write"`
13561437
1357 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
1438 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
13581439
13591440 Permission policy for tool execution.
13601441
from line 1447
13661447
13671448 Tool calls require user confirmation before execution.
13681449
1369 - `type: "write"`
1450 - `BetaManagedAgentsAutoPolicy object`
13701451
1452 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
1453
13711454 - `BetaManagedAgentsGlobToolConfig object`
13721455
13731456 Configuration for the glob tool.
13741457
1458 - `type: "glob"`
1459
13751460 - `enabled: boolean`
13761461
13771462 - `name: "glob"`
13781463
1379 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
1464 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
13801465
13811466 Permission policy for tool execution.
13821467
from line 1473
13881473
13891474 Tool calls require user confirmation before execution.
13901475
1391 - `type: "glob"`
1476 - `BetaManagedAgentsAutoPolicy object`
13921477
1478 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
1479
13931480 - `BetaManagedAgentsGrepToolConfig object`
13941481
13951482 Configuration for the grep tool.
13961483
1484 - `type: "grep"`
1485
13971486 - `enabled: boolean`
13981487
13991488 - `name: "grep"`
14001489
1401 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
1490 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
14021491
14031492 Permission policy for tool execution.
14041493
from line 1499
14101499
14111500 Tool calls require user confirmation before execution.
14121501
1413 - `type: "grep"`
1502 - `BetaManagedAgentsAutoPolicy object`
14141503
1504 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
1505
14151506 - `BetaManagedAgentsWebFetchToolConfig object`
14161507
14171508 Configuration for the web_fetch tool.
14181509
1510 - `type: "web_fetch"`
1511
14191512 - `enabled: boolean`
14201513
14211514 - `name: "web_fetch"`
14221515
1423 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
1516 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
14241517
14251518 Permission policy for tool execution.
14261519
from line 1525
14321525
14331526 Tool calls require user confirmation before execution.
14341527
1435 - `type: "web_fetch"`
1528 - `BetaManagedAgentsAutoPolicy object`
14361529
1530 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
1531
14371532 - `allowed_domains: optional array of string`
14381533
14391534 - `blocked_domains: optional array of string`
from line 1541
14461541
14471542 Configuration for the web_search tool.
14481543
1544 - `type: "web_search"`
1545
14491546 - `enabled: boolean`
14501547
14511548 - `name: "web_search"`
14521549
1453 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
1550 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
14541551
14551552 Permission policy for tool execution.
14561553
from line 1559
14621559
14631560 Tool calls require user confirmation before execution.
14641561
1465 - `type: "web_search"`
1562 - `BetaManagedAgentsAutoPolicy object`
14661563
1564 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
1565
14671566 - `allowed_domains: optional array of string`
14681567
14691568 - `blocked_domains: optional array of string`
from line 1603
15041603
15051604 - `enabled: boolean`
15061605
1507 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
1606 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
15081607
15091608 Permission policy for tool execution.
15101609
from line 1615
15161615
15171616 Tool calls require user confirmation before execution.
15181617
1519 - `type: "agent_toolset_20260401"`
1618 - `BetaManagedAgentsAutoPolicy object`
15201619
1620 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
1621
15211622 - `BetaManagedAgentsMCPToolset object`
15221623
1624 - `type: "mcp_toolset"`
1625
15231626 - `configs: array of BetaManagedAgentsMCPToolConfig`
15241627
15251628 - `enabled: boolean`
from line 1629
15261629
15271630 - `name: string`
15281631
1529 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
1632 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
15301633
15311634 Permission policy for tool execution.
15321635
from line 1641
15381641
15391642 Tool calls require user confirmation before execution.
15401643
1644 - `BetaManagedAgentsAutoPolicy object`
1645
1646 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
1647
15411648 - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig`
15421649
15431650 Resolved default configuration for all tools from an MCP server.
from line 1651
15441651
15451652 - `enabled: boolean`
15461653
1547 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
1654 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
15481655
15491656 Permission policy for tool execution.
15501657
from line 1663
15561663
15571664 Tool calls require user confirmation before execution.
15581665
1559 - `mcp_server_name: string`
1666 - `BetaManagedAgentsAutoPolicy object`
15601667
1561 - `type: "mcp_toolset"`
1668 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
15621669
1670 - `mcp_server_name: string`
1671
15631672 - `BetaManagedAgentsCustomTool object`
15641673
15651674 A custom tool as returned in API responses.
15661675
1676 - `type: "custom"`
1677
15671678 - `description: string`
15681679
15691680 - `input_schema: BetaManagedAgentsCustomToolInputSchema`
from line 1689
15781689
15791690 - `name: string`
15801691
1581 - `type: "custom"`
1582
1583 - `type: "agent"`
1584
15851692 - `version: number`
15861693
15871694 format: int32
from line 1697
15901697
15911698 Platform advisor roster entry: a model the session's primary thread may consult mid-turn.
15921699
1700 - `type: "advisor"`
1701
15931702 - `model: string`
15941703
15951704 The advisor model id.
15961705
1597 - `type: "advisor"`
1598
1599 - `type: "coordinator"`
1600
16011706 - `name: string`
16021707
16031708 - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill`
from line 1727
16221727
16231728 A custom tool as returned in API responses.
16241729
1625 - `type: "agent"`
1626
16271730 - `version: number`
16281731
16291732 format: int32
from line 1741
16381741
16391742 A hard spend ceiling. The session stops issuing new model requests once the tracked list cost reaches `max_list_cost`.
16401743
1744 - `type: "limit"`
1745
16411746 - `max_list_cost: BetaMonetaryAmount`
16421747
16431748 A monetary amount in a specific currency.
from line 1755
16501755
16511756 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.
16521757
1653 - `type: "limit"`
1654
16551758 - `created_at: string`
16561759
16571760 A timestamp in RFC 3339 format
from line 1769
16661769
16671770 Per-outcome evaluation state. One entry per `define_outcome` event sent to the session.
16681771
1772 - `type: "outcome_evaluation"`
1773
16691774 - `completed_at: string or null`
16701775
16711776 A timestamp in RFC 3339 format
from line 1799
16941799
16951800 Current evaluation state. `pending` before the agent begins work; `running` while producing or revising; `evaluating` while the grader scores; `satisfied`/`max_iterations_reached`/`failed`/`interrupted` are terminal.
16961801
1697 - `type: "outcome_evaluation"`
1698
16991802 - `resources: array of BetaManagedAgentsSessionResource`
17001803
17011804 - `BetaManagedAgentsGitHubRepositoryResource object`
17021805
1806 - `type: "github_repository"`
1807
17031808 - `id: string`
17041809
17051810 - `created_at: string`
from line 1815
17101815
17111816 - `mount_path: string`
17121817
1713 - `type: "github_repository"`
1714
17151818 - `updated_at: string`
17161819
17171820 A timestamp in RFC 3339 format
from line 1827
17241827
17251828 - `BetaManagedAgentsBranchCheckout object`
17261829
1830 - `type: "branch"`
1831
17271832 - `name: string`
17281833
17291834 Branch name to check out.
from line 1835
17301835
17311836 minLength: 1, maxLength: 255
17321837
1733 - `type: "branch"`
1734
17351838 - `BetaManagedAgentsCommitCheckout object`
17361839
1840 - `type: "commit"`
1841
17371842 - `sha: string`
17381843
17391844 Full commit SHA to check out.
from line 1845
17401845
17411846 minLength: 7, maxLength: 64
17421847
1743 - `type: "commit"`
1744
17451848 - `BetaManagedAgentsFileResource object`
17461849
1850 - `type: "file"`
1851
17471852 - `id: string`
17481853
17491854 - `created_at: string`
from line 1861
17561861
17571862 - `mount_path: string`
17581863
1759 - `type: "file"`
1760
17611864 - `updated_at: string`
17621865
17631866 A timestamp in RFC 3339 format
from line 1871
17681871
17691872 A memory store attached to an agent session.
17701873
1874 - `type: "memory_store"`
1875
17711876 - `memory_store_id: string`
17721877
17731878 The memory store ID (memstore_...). Must belong to the caller's organization and workspace.
17741879
1775 - `type: "memory_store"`
1776
17771880 - `access: optional "read_write" or "read_only" or null`
17781881
17791882 Access mode for an attached memory store.
from line 1932
18291932 - `"terminated"`
18301933
18311934 - `title: string or null`
1832
1833 - `type: "session"`
18341935
18351936 - `updated_at: string`
18361937
api/beta/sessions/delete Changed · +12 / -3 lines
from line 1
1---
2title: Delete Session
3url: https://platform.claude.com/docs/en/api/beta/sessions/delete
4---
5
16# Delete Session
27
38**DELETE** `/v1/sessions/{session_id}`
from line 21
1621
1722 - `string`
1823
19 - `"message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 41 more`
24 - `"message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 42 more`
2025
2126 - `"message-batches-2024-09-24"`
2227
from line 69
6469
6570 - `"user-profiles-2026-08-18"`
6671
72 - `"user-profiles-2026-09-04"`
73
6774 - `"advisor-tool-2026-03-01"`
6875
6976 - `"managed-agents-2026-04-01"`
from line 113
106113
107114 - `"mid-conversation-system-clear-at-2026-08-21"`
108115
116- `"anthropic-workspace-id": optional string`
117
109118## Returns
110119
111120- `BetaManagedAgentsDeletedSession object`
from line 121
112121
113122 Confirmation that a `session` has been permanently deleted.
114123
115 - `id: string`
116
117124 - `type: "session_deleted"`
125
126 - `id: string`
118127
119128## Example
120129
api/beta/sessions/events Changed · +14155 / -13414 lines
### Beta Managed Agents Agent Auto Evaluated Permission ### Beta Managed Agents Agent Auto Evaluated Permission Allow ### Beta Managed Agents Agent Auto Evaluated Permission Ask ### Beta Managed Agents Agent Auto Evaluated Permission Deny ### Beta Managed Agents Agent Tool Evaluation ### Beta Managed Agents Agent Tool Evaluation Always Allow ### Beta Managed Agents Agent Tool Evaluation Always Ask ### Beta Managed Agents Agent Tool Evaluation Auto
This page is larger than the 256 KiB this site keeps, so one side of the diff below stops where the stored text does.
Nothing in the body moved in this read. What changed is above.
api/beta/sessions/events/list Changed · +2122 / -2007 lines
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: List Events
3url: https://platform.claude.com/docs/en/api/beta/sessions/events/list
4---
5
16# List Events
27
38**GET** `/v1/sessions/{session_id}/events`
from line 69
6469
6570 - `string`
6671
67 - `"message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 41 more`
72 - `"message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 42 more`
6873
6974 - `"message-batches-2024-09-24"`
7075
from line 117
112117
113118 - `"user-profiles-2026-08-18"`
114119
120 - `"user-profiles-2026-09-04"`
121
115122 - `"advisor-tool-2026-03-01"`
116123
117124 - `"managed-agents-2026-04-01"`
from line 161
154161
155162 - `"mid-conversation-system-clear-at-2026-08-21"`
156163
164- `"anthropic-workspace-id": optional string`
165
157166## Returns
158167
159168- `data: optional array of BetaManagedAgentsSessionEvent`
from line 173
164173
165174 A user message event in the session conversation.
166175
176 - `type: "user.message"`
177
167178 - `id: string`
168179
169180 Unique identifier for this event.
from line 187
176187
177188 Regular text content.
178189
190 - `type: "text"`
191
179192 - `text: string`
180193
181194 The text content.
182195
183196 minLength: 1
184197
198 - `BetaManagedAgentsImageBlock object`
199
200 Image content specified directly as base64 data or as a reference via a URL.
201
202 - `type: "image"`
203
204 - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource`
205
206 Union type for image source variants.
207
208 - `BetaManagedAgentsBase64ImageSource object`
209
210 Base64-encoded image data.
211
212 - `type: "base64"`
213
214 - `data: string`
215
216 Base64-encoded image data.
217
218 minLength: 1
219
220 - `media_type: string`
221
222 MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp").
223
224 minLength: 1
225
226 - `BetaManagedAgentsURLImageSource object`
227
228 Image referenced by URL.
229
230 - `type: "url"`
231
232 - `url: string`
233
234 URL of the image to fetch.
235
236 minLength: 1
237
238 - `BetaManagedAgentsFileImageSource object`
239
240 Image referenced by file ID.
241
242 - `type: "file"`
243
244 - `file_id: string`
245
246 ID of a previously uploaded file.
247
248 minLength: 1
249
250 - `BetaManagedAgentsDocumentBlock object`
251
252 Document content, either specified directly as base64 data, as text, or as a reference via a URL.
253
254 - `type: "document"`
255
256 - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource`
257
258 Union type for document source variants.
259
260 - `BetaManagedAgentsBase64DocumentSource object`
261
262 Base64-encoded document data.
263
264 - `type: "base64"`
265
266 - `data: string`
267
268 Base64-encoded document data.
269
270 minLength: 1
271
272 - `media_type: string`
273
274 MIME type of the document (e.g., "application/pdf").
275
276 minLength: 1
277
278 - `BetaManagedAgentsPlainTextDocumentSource object`
279
280 Plain text document content.
281
282 - `type: "text"`
283
284 - `data: string`
285
286 The plain text content.
287
288 minLength: 1
289
290 - `media_type: "text/plain"`
291
292 MIME type of the text content. Must be "text/plain".
293
294 - `BetaManagedAgentsURLDocumentSource object`
295
296 Document referenced by URL.
297
298 - `type: "url"`
299
300 - `url: string`
301
302 URL of the document to fetch.
303
304 minLength: 1
305
306 - `BetaManagedAgentsFileDocumentSource object`
307
308 Document referenced by file ID.
309
310 - `type: "file"`
311
312 - `file_id: string`
313
314 ID of a previously uploaded file.
315
316 minLength: 1
317
318 - `context: optional string or null`
319
320 Additional context about the document for the model.
321
322 - `title: optional string or null`
323
324 The title of the document.
325
326 - `BetaManagedAgentsRedactedBlock object`
327
328 Placeholder for content withheld by Anthropic model policy.
329
330 - `type: "redacted"`
331
332 - `processed_at: optional string or null`
333
334 A timestamp in RFC 3339 format
335
336 format: date-time
337
338 - `BetaManagedAgentsUserInterruptEvent object`
339
340 An interrupt event that pauses agent execution and returns control to the user.
341
342 - `type: "user.interrupt"`
343
344 - `id: string`
345
346 Unique identifier for this event.
347
348 - `processed_at: optional string or null`
349
350 A timestamp in RFC 3339 format
351
352 format: date-time
353
354 - `session_thread_id: optional string or null`
355
356 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.
357
358 - `BetaManagedAgentsUserToolConfirmationEvent object`
359
360 A tool confirmation event that approves or denies a pending tool execution.
361
362 - `type: "user.tool_confirmation"`
363
364 - `id: string`
365
366 Unique identifier for this event.
367
368 - `result: "allow" or "deny"`
369
370 UserToolConfirmationResult enum
371
372 - `"allow"`
373
374 - `"deny"`
375
376 - `tool_use_id: string`
377
378 The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field.
379
380 - `deny_message: optional string or null`
381
382 Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'.
383
384 maxLength: 10000
385
386 - `processed_at: optional string or null`
387
388 A timestamp in RFC 3339 format
389
390 format: date-time
391
392 - `session_thread_id: optional string or null`
393
394 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.
395
396 - `BetaManagedAgentsUserCustomToolResultEvent object`
397
398 Event sent by the client providing the result of a custom tool execution.
399
400 - `type: "user.custom_tool_result"`
401
402 - `id: string`
403
404 Unique identifier for this event.
405
406 - `custom_tool_use_id: string`
407
408 The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field.
409
410 - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock`
411
412 The result content returned by the tool.
413
414 - `BetaManagedAgentsTextBlock object`
415
416 Regular text content.
417
418 - `BetaManagedAgentsImageBlock object`
419
420 Image content specified directly as base64 data or as a reference via a URL.
421
422 - `BetaManagedAgentsDocumentBlock object`
423
424 Document content, either specified directly as base64 data, as text, or as a reference via a URL.
425
426 - `BetaManagedAgentsSearchResultBlock object`
427
428 A block containing a web search result.
429
430 - `type: "search_result"`
431
432 - `citations: BetaManagedAgentsSearchResultCitations`
433
434 Citation settings for a search result.
435
436 - `enabled: boolean`
437
438 Whether citations are enabled for this search result.
439
440 - `content: array of BetaManagedAgentsSearchResultContent`
441
442 Array of text content blocks from the search result.
443
444 - `type: "text"`
445
446 - `text: string`
447
448 The text content.
449
450 minLength: 1
451
452 - `source: string`
453
454 The URL source of the search result.
455
456 minLength: 1
457
458 - `title: string`
459
460 The title of the search result.
461
462 minLength: 1
463
464 - `is_error: optional boolean or null`
465
466 Whether the tool execution resulted in an error.
467
468 - `processed_at: optional string or null`
469
470 A timestamp in RFC 3339 format
471
472 format: date-time
473
474 - `session_thread_id: optional string or null`
475
476 Routes this result to a subagent thread. Copy from the `agent.custom_tool_use` event's `session_thread_id`.
477
478 - `BetaManagedAgentsAgentCustomToolUseEvent object`
479
480 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.
481
482 - `type: "agent.custom_tool_use"`
483
484 - `id: string`
485
486 Unique identifier for this event.
487
488 - `input: map[unknown]`
489
490 Input parameters for the tool call.
491
492 - `name: string`
493
494 Name of the custom tool being called.
495
496 - `processed_at: string`
497
498 A timestamp in RFC 3339 format
499
500 format: date-time
501
502 - `session_thread_id: optional string or null`
503
504 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.
505
506 - `BetaManagedAgentsAgentMessageEvent object`
507
508 An agent response event in the session conversation.
509
510 - `type: "agent.message"`
511
512 - `id: string`
513
514 Unique identifier for this event.
515
516 - `content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsRedactedBlock`
517
518 Array of text blocks comprising the agent response.
519
520 - `BetaManagedAgentsTextBlock object`
521
522 Regular text content.
523
524 - `BetaManagedAgentsRedactedBlock object`
525
526 Placeholder for content withheld by Anthropic model policy.
527
528 - `processed_at: string`
529
530 A timestamp in RFC 3339 format
531
532 format: date-time
533
534 - `BetaManagedAgentsAgentThinkingEvent object`
535
536 Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier.
537
538 - `type: "agent.thinking"`
539
540 - `id: string`
541
542 Unique identifier for this event.
543
544 - `processed_at: string`
545
546 A timestamp in RFC 3339 format
547
548 format: date-time
549
550 - `BetaManagedAgentsAgentMCPToolUseEvent object`
551
552 Event emitted when the agent invokes a tool provided by an MCP server.
553
554 - `type: "agent.mcp_tool_use"`
555
556 - `id: string`
557
558 Unique identifier for this event.
559
560 - `input: map[unknown]`
561
562 Input parameters for the tool call.
563
564 - `mcp_server_name: string`
565
566 Name of the MCP server providing the tool.
567
568 - `name: string`
569
570 Name of the MCP tool being used.
571
572 - `processed_at: string`
573
574 A timestamp in RFC 3339 format
575
576 format: date-time
577
578 - `evaluated_permission: optional "allow" or "ask" or "deny"`
579
580 AgentEvaluatedPermission enum
581
582 - `"allow"`
583
584 - `"ask"`
585
586 - `"deny"`
587
588 - `evaluation: optional BetaManagedAgentsAgentToolEvaluation`
589
590 Names the resolved permission_policy that produced evaluated_permission, and under auto carries the judgement. Open union: clients must tolerate unknown variants.
591
592 - `BetaManagedAgentsAgentToolEvaluationAlwaysAllow object`
593
594 The resolved permission_policy was always_allow; accompanies evaluated_permission "allow".
595
596 - `type: "always_allow"`
597
598 - `BetaManagedAgentsAgentToolEvaluationAlwaysAsk object`
599
600 The resolved permission_policy was always_ask; accompanies evaluated_permission "ask".
601
602 - `type: "always_ask"`
603
604 - `BetaManagedAgentsAgentToolEvaluationAuto object`
605
606 The resolved permission_policy was auto: the server judged this invocation individually.
607
608 - `type: "auto"`
609
610 - `evaluated_permission: BetaManagedAgentsAgentAutoEvaluatedPermission`
611
612 The server's per-invocation judgement under the auto permission policy. Its type always equals the event's top-level evaluated_permission. Open union: clients must tolerate unknown variants.
613
614 - `BetaManagedAgentsAgentAutoEvaluatedPermissionAllow object`
615
616 The server judged the invocation safe to execute without client approval.
617
618 - `type: "allow"`
619
620 - `BetaManagedAgentsAgentAutoEvaluatedPermissionAsk object`
621
622 The server reached no judgement; the invocation is held for client approval.
623
624 - `type: "ask"`
625
626 - `reason_code: string`
627
628 The judgement's grounds in registry-bound terms, for client branching and audit rather than end-user display. Open registry; currently "indeterminate" (no judgement was reached). Clients must tolerate values outside this set.
629
630 maxLength: 64
631
632 - `BetaManagedAgentsAgentAutoEvaluatedPermissionDeny object`
633
634 The server judged the invocation high-risk; it does not execute and a synthetic error tool result is appended.
635
636 - `type: "deny"`
637
638 - `reason_code: string`
639
640 The judgement's grounds in registry-bound terms. Open registry; currently "high_risk" (judged high-risk; the call does not run). Clients must tolerate values outside this set.
641
642 maxLength: 64
643
644 - `session_thread_id: optional string or null`
645
646 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.
647
648 - `BetaManagedAgentsAgentMCPToolResultEvent object`
649
650 Event representing the result of an MCP tool execution.
651
652 - `type: "agent.mcp_tool_result"`
653
654 - `id: string`
655
656 Unique identifier for this event.
657
658 - `mcp_tool_use_id: string`
659
660 The id of the `agent.mcp_tool_use` event this result corresponds to.
661
662 - `processed_at: string`
663
664 A timestamp in RFC 3339 format
665
666 format: date-time
667
668 - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock`
669
670 The result content returned by the tool.
671
672 - `BetaManagedAgentsTextBlock object`
673
674 Regular text content.
675
676 - `BetaManagedAgentsImageBlock object`
677
678 Image content specified directly as base64 data or as a reference via a URL.
679
680 - `BetaManagedAgentsDocumentBlock object`
681
682 Document content, either specified directly as base64 data, as text, or as a reference via a URL.
683
684 - `BetaManagedAgentsSearchResultBlock object`
685
686 A block containing a web search result.
687
688 - `is_error: optional boolean or null`
689
690 Whether the tool execution resulted in an error.
691
692 - `BetaManagedAgentsAgentToolUseEvent object`
693
694 Event emitted when the agent invokes a built-in agent tool.
695
696 - `type: "agent.tool_use"`
697
698 - `id: string`
699
700 Unique identifier for this event.
701
702 - `input: map[unknown]`
703
704 Input parameters for the tool call.
705
706 - `name: string`
707
708 Name of the agent tool being used.
709
710 - `processed_at: string`
711
712 A timestamp in RFC 3339 format
713
714 format: date-time
715
716 - `evaluated_permission: optional "allow" or "ask" or "deny"`
717
718 AgentEvaluatedPermission enum
719
720 - `"allow"`
721
722 - `"ask"`
723
724 - `"deny"`
725
726 - `evaluation: optional BetaManagedAgentsAgentToolEvaluation`
727
728 Names the resolved permission_policy that produced evaluated_permission, and under auto carries the judgement. Open union: clients must tolerate unknown variants.
729
730 - `session_thread_id: optional string or null`
731
732 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.
733
734 - `BetaManagedAgentsAgentToolResultEvent object`
735
736 Event representing the result of an agent tool execution.
737
738 - `type: "agent.tool_result"`
739
740 - `id: string`
741
742 Unique identifier for this event.
743
744 - `processed_at: string`
745
746 A timestamp in RFC 3339 format
747
748 format: date-time
749
750 - `tool_use_id: string`
751
752 The id of the `agent.tool_use` event this result corresponds to.
753
754 - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock`
755
756 The result content returned by the tool.
757
758 - `BetaManagedAgentsTextBlock object`
759
760 Regular text content.
761
762 - `BetaManagedAgentsImageBlock object`
763
764 Image content specified directly as base64 data or as a reference via a URL.
765
766 - `BetaManagedAgentsDocumentBlock object`
767
768 Document content, either specified directly as base64 data, as text, or as a reference via a URL.
769
770 - `BetaManagedAgentsSearchResultBlock object`
771
772 A block containing a web search result.
773
774 - `is_error: optional boolean or null`
775
776 Whether the tool execution resulted in an error.
777
778 - `BetaManagedAgentsAgentThreadMessageReceivedEvent object`
779
780 Delivery event written to the target thread's input stream when an agent-to-agent message arrives.
781
782 - `type: "agent.thread_message_received"`
783
784 - `id: string`
785
786 Unique identifier for this event.
787
788 - `content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsRedactedBlock`
789
790 Message content blocks.
791
792 - `BetaManagedAgentsTextBlock object`
793
794 Regular text content.
795
796 - `BetaManagedAgentsImageBlock object`
797
798 Image content specified directly as base64 data or as a reference via a URL.
799
800 - `BetaManagedAgentsDocumentBlock object`
801
802 Document content, either specified directly as base64 data, as text, or as a reference via a URL.
803
804 - `BetaManagedAgentsRedactedBlock object`
805
806 Placeholder for content withheld by Anthropic model policy.
807
808 - `from_session_thread_id: string`
809
810 Public `sthr_` ID of the thread that sent the message.
811
812 - `processed_at: string`
813
814 A timestamp in RFC 3339 format
815
816 format: date-time
817
818 - `from_agent_name: optional string or null`
819
820 Name of the callable agent this message came from. Absent when received from the primary agent.
821
822 - `BetaManagedAgentsAgentThreadMessageSentEvent object`
823
824 Observability event emitted to the sender's output stream when an agent-to-agent message is sent.
825
826 - `type: "agent.thread_message_sent"`
827
828 - `id: string`
829
830 Unique identifier for this event.
831
832 - `content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsRedactedBlock`
833
834 Message content blocks.
835
836 - `BetaManagedAgentsTextBlock object`
837
838 Regular text content.
839
840 - `BetaManagedAgentsImageBlock object`
841
842 Image content specified directly as base64 data or as a reference via a URL.
843
844 - `BetaManagedAgentsDocumentBlock object`
845
846 Document content, either specified directly as base64 data, as text, or as a reference via a URL.
847
848 - `BetaManagedAgentsRedactedBlock object`
849
850 Placeholder for content withheld by Anthropic model policy.
851
852 - `processed_at: string`
853
854 A timestamp in RFC 3339 format
855
856 format: date-time
857
858 - `to_session_thread_id: string`
859
860 Public `sthr_` ID of the thread the message was sent to.
861
862 - `to_agent_name: optional string or null`
863
864 Name of the callable agent this message was sent to. Absent when sent to the primary agent.
865
866 - `BetaManagedAgentsAgentThreadContextCompactedEvent object`
867
868 Indicates that context compaction (summarization) occurred during the session.
869
870 - `type: "agent.thread_context_compacted"`
871
872 - `id: string`
873
874 Unique identifier for this event.
875
876 - `processed_at: string`
877
878 A timestamp in RFC 3339 format
879
880 format: date-time
881
882 - `BetaManagedAgentsSessionErrorEvent object`
883
884 An error event indicating a problem occurred during session execution.
885
886 - `type: "session.error"`
887
888 - `id: string`
889
890 Unique identifier for this event.
891
892 - `error: BetaManagedAgentsUnknownError or BetaManagedAgentsModelOverloadedError or BetaManagedAgentsModelRateLimitedError or 5 more`
893
894 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.
895
896 - `BetaManagedAgentsUnknownError object`
897
898 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.
899
900 - `type: "unknown_error"`
901
902 - `message: string`
903
904 Human-readable error description.
905
906 - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal`
907
908 What the client should do next in response to this error.
909
910 - `BetaManagedAgentsRetryStatusRetrying object`
911
912 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.
913
914 - `type: "retrying"`
915
916 - `BetaManagedAgentsRetryStatusExhausted object`
917
918 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
919
920 - `type: "exhausted"`
921
922 - `BetaManagedAgentsRetryStatusTerminal object`
923
924 The session encountered a terminal error and will transition to `terminated` state.
925
926 - `type: "terminal"`
927
928 - `BetaManagedAgentsModelOverloadedError object`
929
930 The model is currently overloaded. Emitted after automatic retries are exhausted.
931
932 - `type: "model_overloaded_error"`
933
934 - `message: string`
935
936 Human-readable error description.
937
938 - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal`
939
940 What the client should do next in response to this error.
941
942 - `BetaManagedAgentsRetryStatusRetrying object`
943
944 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.
945
946 - `BetaManagedAgentsRetryStatusExhausted object`
947
948 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
949
950 - `BetaManagedAgentsRetryStatusTerminal object`
951
952 The session encountered a terminal error and will transition to `terminated` state.
953
954 - `BetaManagedAgentsModelRateLimitedError object`
955
956 The model request was rate-limited.
957
958 - `type: "model_rate_limited_error"`
959
960 - `message: string`
961
962 Human-readable error description.
963
964 - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal`
965
966 What the client should do next in response to this error.
967
968 - `BetaManagedAgentsRetryStatusRetrying object`
969
970 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.
971
972 - `BetaManagedAgentsRetryStatusExhausted object`
973
974 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
975
976 - `BetaManagedAgentsRetryStatusTerminal object`
977
978 The session encountered a terminal error and will transition to `terminated` state.
979
980 - `BetaManagedAgentsModelRequestFailedError object`
981
982 A model request failed for a reason other than overload or rate-limiting.
983
984 - `type: "model_request_failed_error"`
985
986 - `message: string`
987
988 Human-readable error description.
989
990 - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal`
991
992 What the client should do next in response to this error.
993
994 - `BetaManagedAgentsRetryStatusRetrying object`
995
996 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.
997
998 - `BetaManagedAgentsRetryStatusExhausted object`
999
1000 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
1001
1002 - `BetaManagedAgentsRetryStatusTerminal object`
1003
1004 The session encountered a terminal error and will transition to `terminated` state.
1005
1006 - `BetaManagedAgentsMCPConnectionFailedError object`
1007
1008 Failed to connect to an MCP server.
1009
1010 - `type: "mcp_connection_failed_error"`
1011
1012 - `mcp_server_name: string`
1013
1014 Name of the MCP server that failed to connect.
1015
1016 - `message: string`
1017
1018 Human-readable error description.
1019
1020 - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal`
1021
1022 What the client should do next in response to this error.
1023
1024 - `BetaManagedAgentsRetryStatusRetrying object`
1025
1026 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.
1027
1028 - `BetaManagedAgentsRetryStatusExhausted object`
1029
1030 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
1031
1032 - `BetaManagedAgentsRetryStatusTerminal object`
1033
1034 The session encountered a terminal error and will transition to `terminated` state.
1035
1036 - `BetaManagedAgentsMCPAuthenticationFailedError object`
1037
1038 Authentication to an MCP server failed.
1039
1040 - `type: "mcp_authentication_failed_error"`
1041
1042 - `mcp_server_name: string`
1043
1044 Name of the MCP server that failed authentication.
1045
1046 - `message: string`
1047
1048 Human-readable error description.
1049
1050 - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal`
1051
1052 What the client should do next in response to this error.
1053
1054 - `BetaManagedAgentsRetryStatusRetrying object`
1055
1056 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.
1057
1058 - `BetaManagedAgentsRetryStatusExhausted object`
1059
1060 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
1061
1062 - `BetaManagedAgentsRetryStatusTerminal object`
1063
1064 The session encountered a terminal error and will transition to `terminated` state.
1065
1066 - `BetaManagedAgentsBillingError object`
1067
1068 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.
1069
1070 - `type: "billing_error"`
1071
1072 - `message: string`
1073
1074 Human-readable error description.
1075
1076 - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal`
1077
1078 What the client should do next in response to this error.
1079
1080 - `BetaManagedAgentsRetryStatusRetrying object`
1081
1082 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.
1083
1084 - `BetaManagedAgentsRetryStatusExhausted object`
1085
1086 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
1087
1088 - `BetaManagedAgentsRetryStatusTerminal object`
1089
1090 The session encountered a terminal error and will transition to `terminated` state.
1091
1092 - `BetaManagedAgentsCredentialHostUnreachableError object`
1093
1094 An `environment_variable` credential's `auth.networking.allowed_hosts` includes a host the environment's network policy does not permit.
1095
1096 - `type: "credential_host_unreachable_error"`
1097
1098 - `credential_id: string`
1099
1100 ID of the affected credential.
1101
1102 - `message: string`
1103
1104 Human-readable error description.
1105
1106 - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal`
1107
1108 What the client should do next in response to this error.
1109
1110 - `BetaManagedAgentsRetryStatusRetrying object`
1111
1112 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.
1113
1114 - `BetaManagedAgentsRetryStatusExhausted object`
1115
1116 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
1117
1118 - `BetaManagedAgentsRetryStatusTerminal object`
1119
1120 The session encountered a terminal error and will transition to `terminated` state.
1121
1122 - `vault_id: string`
1123
1124 ID of the vault containing the affected credential.
1125
1126 - `processed_at: string`
1127
1128 A timestamp in RFC 3339 format
1129
1130 format: date-time
1131
1132 - `BetaManagedAgentsSessionStatusRescheduledEvent object`
1133
1134 Indicates the session is recovering from an error state and is rescheduled for execution.
1135
1136 - `type: "session.status_rescheduled"`
1137
1138 - `id: string`
1139
1140 Unique identifier for this event.
1141
1142 - `processed_at: string`
1143
1144 A timestamp in RFC 3339 format
1145
1146 format: date-time
1147
1148 - `BetaManagedAgentsSessionStatusRunningEvent object`
1149
1150 Indicates the session is actively running and the agent is working.
1151
1152 - `type: "session.status_running"`
1153
1154 - `id: string`
1155
1156 Unique identifier for this event.
1157
1158 - `processed_at: string`
1159
1160 A timestamp in RFC 3339 format
1161
1162 format: date-time
1163
1164 - `BetaManagedAgentsSessionStatusIdleEvent object`
1165
1166 Indicates the agent has paused and is awaiting user input.
1167
1168 - `type: "session.status_idle"`
1169
1170 - `id: string`
1171
1172 Unique identifier for this event.
1173
1174 - `processed_at: string`
1175
1176 A timestamp in RFC 3339 format
1177
1178 format: date-time
1179
1180 - `stop_reason: BetaManagedAgentsSessionEndTurn or BetaManagedAgentsSessionRequiresAction or BetaManagedAgentsSessionRetriesExhausted or BetaManagedAgentsSessionBudgetReached`
1181
1182 The agent completed its turn naturally and is ready for the next user message.
1183
1184 - `BetaManagedAgentsSessionEndTurn object`
1185
1186 The agent completed its turn naturally and is ready for the next user message.
1187
1188 - `type: "end_turn"`
1189
1190 - `BetaManagedAgentsSessionRequiresAction object`
1191
1192 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.
1193
1194 - `type: "requires_action"`
1195
1196 - `event_ids: array of string`
1197
1198 The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder.
1199
1200 - `BetaManagedAgentsSessionRetriesExhausted object`
1201
1202 The turn ended because repeated errors exhausted the retry budget or an error escalated to `retry_status: 'exhausted'`.
1203
1204 - `type: "retries_exhausted"`
1205
1206 - `BetaManagedAgentsSessionBudgetReached object`
1207
1208 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.
1209
1210 - `type: "budget_reached"`
1211
1212 - `BetaManagedAgentsSessionStatusTerminatedEvent object`
1213
1214 Indicates the session has terminated, either due to an error or completion.
1215
1216 - `type: "session.status_terminated"`
1217
1218 - `id: string`
1219
1220 Unique identifier for this event.
1221
1222 - `processed_at: string`
1223
1224 A timestamp in RFC 3339 format
1225
1226 format: date-time
1227
1228 - `BetaManagedAgentsSessionThreadCreatedEvent object`
1229
1230 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.
1231
1232 - `type: "session.thread_created"`
1233
1234 - `id: string`
1235
1236 Unique identifier for this event.
1237
1238 - `agent_name: string`
1239
1240 Name of the callable agent the thread runs.
1241
1242 - `processed_at: string`
1243
1244 A timestamp in RFC 3339 format
1245
1246 format: date-time
1247
1248 - `session_thread_id: string`
1249
1250 Public `sthr_` ID of the newly created thread.
1251
1252 - `BetaManagedAgentsSpanOutcomeEvaluationStartEvent object`
1253
1254 Emitted when an outcome evaluation cycle begins.
1255
1256 - `type: "span.outcome_evaluation_start"`
1257
1258 - `id: string`
1259
1260 Unique identifier for this event.
1261
1262 - `iteration: number`
1263
1264 0-indexed revision cycle. 0 is the first evaluation; 1 is the re-evaluation after the first revision; etc.
1265
1266 format: int32
1267
1268 - `outcome_id: string`
1269
1270 The `outc_` ID of the outcome being evaluated.
1271
1272 - `processed_at: string`
1273
1274 A timestamp in RFC 3339 format
1275
1276 format: date-time
1277
1278 - `BetaManagedAgentsSpanOutcomeEvaluationEndEvent object`
1279
1280 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.
1281
1282 - `type: "span.outcome_evaluation_end"`
1283
1284 - `id: string`
1285
1286 Unique identifier for this event.
1287
1288 - `explanation: string`
1289
1290 Human-readable explanation of the verdict. For `needs_revision`, describes which criteria failed and why.
1291
1292 - `iteration: number`
1293
1294 0-indexed revision cycle, matching the corresponding `span.outcome_evaluation_start`.
1295
1296 format: int32
1297
1298 - `outcome_evaluation_start_id: string`
1299
1300 The id of the corresponding `span.outcome_evaluation_start` event.
1301
1302 - `outcome_id: string`
1303
1304 The `outc_` ID of the outcome being evaluated.
1305
1306 - `processed_at: string`
1307
1308 A timestamp in RFC 3339 format
1309
1310 format: date-time
1311
1312 - `result: string`
1313
1314 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.
1315
1316 - `usage: BetaManagedAgentsSpanModelUsage`
1317
1318 Token usage for a single model request.
1319
1320 - `cache_creation_input_tokens: number`
1321
1322 Tokens used to create prompt cache in this request.
1323
1324 format: int32
1325
1326 - `cache_read_input_tokens: number`
1327
1328 Tokens read from prompt cache in this request.
1329
1330 format: int32
1331
1332 - `input_tokens: number`
1333
1334 Input tokens consumed by this request.
1335
1336 format: int32
1337
1338 - `output_tokens: number`
1339
1340 Output tokens generated by this request.
1341
1342 format: int32
1343
1344 - `speed: optional "standard" or "fast" or null`
1345
1346 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.
1347
1348 - `"standard"`
1349
1350 - `"fast"`
1351
1352 - `BetaManagedAgentsSpanModelRequestStartEvent object`
1353
1354 Emitted when a model request is initiated by the agent.
1355
1356 - `type: "span.model_request_start"`
1357
1358 - `id: string`
1359
1360 Unique identifier for this event.
1361
1362 - `processed_at: string`
1363
1364 A timestamp in RFC 3339 format
1365
1366 format: date-time
1367
1368 - `BetaManagedAgentsSpanModelRequestEndEvent object`
1369
1370 Emitted when a model request completes.
1371
1372 - `type: "span.model_request_end"`
1373
1374 - `id: string`
1375
1376 Unique identifier for this event.
1377
1378 - `is_error: boolean or null`
1379
1380 Whether the model request resulted in an error.
1381
1382 - `model_request_start_id: string`
1383
1384 The id of the corresponding `span.model_request_start` event.
1385
1386 - `model_usage: BetaManagedAgentsSpanModelUsage`
1387
1388 Token usage for a single model request.
1389
1390 - `processed_at: string`
1391
1392 A timestamp in RFC 3339 format
1393
1394 format: date-time
1395
1396 - `BetaManagedAgentsSpanOutcomeEvaluationOngoingEvent object`
1397
1398 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.
1399
1400 - `type: "span.outcome_evaluation_ongoing"`
1401
1402 - `id: string`
1403
1404 Unique identifier for this event.
1405
1406 - `iteration: number`
1407
1408 0-indexed revision cycle, matching the corresponding `span.outcome_evaluation_start`.
1409
1410 format: int32
1411
1412 - `outcome_id: string`
1413
1414 The `outc_` ID of the outcome being evaluated.
1415
1416 - `processed_at: string`
1417
1418 A timestamp in RFC 3339 format
1419
1420 format: date-time
1421
1422 - `BetaManagedAgentsUserDefineOutcomeEvent object`
1423
1424 Echo of a `user.define_outcome` input event. Carries the server-generated `outcome_id` that subsequent `span.outcome_evaluation_*` events reference.
1425
1426 - `type: "user.define_outcome"`
1427
1428 - `id: string`
1429
1430 Unique identifier for this event.
1431
1432 - `description: string`
1433
1434 What the agent should produce. Copied from the input event.
1435
1436 - `max_iterations: number or null`
1437
1438 Evaluate-then-revise cycles before giving up. Default 3, max 20.
1439
1440 format: int32
1441
1442 - `outcome_id: string`
1443
1444 Server-generated `outc_` ID for this outcome. Referenced by `span.outcome_evaluation_*` events and the session's `outcome_evaluations` list.
1445
1446 - `processed_at: string`
1447
1448 A timestamp in RFC 3339 format
1449
1450 format: date-time
1451
1452 - `rubric: BetaManagedAgentsFileRubric or BetaManagedAgentsTextRubric`
1453
1454 Rubric for grading the quality of an outcome.
1455
1456 - `BetaManagedAgentsFileRubric object`
1457
1458 Rubric referenced by a file uploaded via the Files API.
1459
1460 - `type: "file"`
1461
1462 - `file_id: string`
1463
1464 ID of the rubric file.
1465
1466 - `BetaManagedAgentsTextRubric object`
1467
1468 Rubric content provided inline as text.
1469
1851470 - `type: "text"`
1861471
1472 - `content: string`
1473
1474 Rubric content. Plain text or markdown — the grader treats it as freeform text.
1475
1476 - `BetaManagedAgentsSessionDeletedEvent object`
1477
1478 Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session.
1479
1480 - `type: "session.deleted"`
1481
1482 - `id: string`
1483
1484 Unique identifier for this event.
1485
1486 - `processed_at: string`
1487
1488 A timestamp in RFC 3339 format
1489
1490 format: date-time
1491
1492 - `BetaManagedAgentsSessionThreadStatusRunningEvent object`
1493
1494 A session thread has begun executing. Emitted on the thread's own stream and cross-posted to the primary stream for child threads.
1495
1496 - `type: "session.thread_status_running"`
1497
1498 - `id: string`
1499
1500 Unique identifier for this event.
1501
1502 - `agent_name: string`
1503
1504 Name of the agent the thread runs.
1505
1506 - `processed_at: string`
1507
1508 A timestamp in RFC 3339 format
1509
1510 format: date-time
1511
1512 - `session_thread_id: string`
1513
1514 Public sthr_ ID of the thread that started running.
1515
1516 - `BetaManagedAgentsSessionThreadStatusIdleEvent object`
1517
1518 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.
1519
1520 - `type: "session.thread_status_idle"`
1521
1522 - `id: string`
1523
1524 Unique identifier for this event.
1525
1526 - `agent_name: string`
1527
1528 Name of the agent the thread runs.
1529
1530 - `processed_at: string`
1531
1532 A timestamp in RFC 3339 format
1533
1534 format: date-time
1535
1536 - `session_thread_id: string`
1537
1538 Public sthr_ ID of the thread that went idle.
1539
1540 - `stop_reason: BetaManagedAgentsSessionEndTurn or BetaManagedAgentsSessionRequiresAction or BetaManagedAgentsSessionRetriesExhausted or BetaManagedAgentsSessionBudgetReached`
1541
1542 The agent completed its turn naturally and is ready for the next user message.
1543
1544 - `BetaManagedAgentsSessionEndTurn object`
1545
1546 The agent completed its turn naturally and is ready for the next user message.
1547
1548 - `BetaManagedAgentsSessionRequiresAction object`
1549
1550 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.
1551
1552 - `BetaManagedAgentsSessionRetriesExhausted object`
1553
1554 The turn ended because repeated errors exhausted the retry budget or an error escalated to `retry_status: 'exhausted'`.
1555
1556 - `BetaManagedAgentsSessionBudgetReached object`
1557
1558 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.
1559
1560 - `BetaManagedAgentsSessionThreadStatusTerminatedEvent object`
1561
1562 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.
1563
1564 - `type: "session.thread_status_terminated"`
1565
1566 - `id: string`
1567
1568 Unique identifier for this event.
1569
1570 - `agent_name: string`
1571
1572 Name of the agent the thread runs.
1573
1574 - `processed_at: string`
1575
1576 A timestamp in RFC 3339 format
1577
1578 format: date-time
1579
1580 - `session_thread_id: string`
1581
1582 Public sthr_ ID of the thread that terminated.
1583
1584 - `BetaManagedAgentsUserToolResultEvent object`
1585
1586 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.
1587
1588 - `type: "user.tool_result"`
1589
1590 - `id: string`
1591
1592 Unique identifier for this event.
1593
1594 - `tool_use_id: string`
1595
1596 The id of the `agent.tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field.
1597
1598 - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock`
1599
1600 The result content returned by the tool.
1601
1602 - `BetaManagedAgentsTextBlock object`
1603
1604 Regular text content.
1605
1871606 - `BetaManagedAgentsImageBlock object`
1881607
1891608 Image content specified directly as base64 data or as a reference via a URL.
1901609
191 - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource`
192
193 Union type for image source variants.
194
195 - `BetaManagedAgentsBase64ImageSource object`
196
197 Base64-encoded image data.
198
199 - `data: string`
200
201 Base64-encoded image data.
202
203 minLength: 1
204
205 - `media_type: string`
206
207 MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp").
208
209 minLength: 1
210
211 - `type: "base64"`
212
213 - `BetaManagedAgentsURLImageSource object`
214
215 Image referenced by URL.
216
217 - `type: "url"`
218
219 - `url: string`
220
221 URL of the image to fetch.
222
223 minLength: 1
224
225 - `BetaManagedAgentsFileImageSource object`
226
227 Image referenced by file ID.
228
229 - `file_id: string`
230
231 ID of a previously uploaded file.
232
233 minLength: 1
234
235 - `type: "file"`
236
237 - `type: "image"`
238
2391610 - `BetaManagedAgentsDocumentBlock object`
2401611
2411612 Document content, either specified directly as base64 data, as text, or as a reference via a URL.
2421613
243 - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource`
244
245 Union type for document source variants.
246
247 - `BetaManagedAgentsBase64DocumentSource object`
248
249 Base64-encoded document data.
250
251 - `data: string`
252
253 Base64-encoded document data.
254
255 minLength: 1
256
257 - `media_type: string`
258
259 MIME type of the document (e.g., "application/pdf").
260
261 minLength: 1
262
263 - `type: "base64"`
264
265 - `BetaManagedAgentsPlainTextDocumentSource object`
266
267 Plain text document content.
268
269 - `data: string`
270
271 The plain text content.
272
273 minLength: 1
274
275 - `media_type: "text/plain"`
276
277 MIME type of the text content. Must be "text/plain".
278
279 - `type: "text"`
280
281 - `BetaManagedAgentsURLDocumentSource object`
282
283 Document referenced by URL.
284
285 - `type: "url"`
286
287 - `url: string`
288
289 URL of the document to fetch.
290
291 minLength: 1
292
293 - `BetaManagedAgentsFileDocumentSource object`
294
295 Document referenced by file ID.
296
297 - `file_id: string`
298
299 ID of a previously uploaded file.
300
301 minLength: 1
302
303 - `type: "file"`
304
305 - `type: "document"`
306
307 - `context: optional string or null`
308
309 Additional context about the document for the model.
310
311 - `title: optional string or null`
312
313 The title of the document.
314
315 - `BetaManagedAgentsRedactedBlock object`
316
317 Placeholder for content withheld by Anthropic model policy.
318
319 - `type: "redacted"`
320
321 - `type: "user.message"`
1614 - `BetaManagedAgentsSearchResultBlock object`
1615
1616 A block containing a web search result.
1617
1618 - `is_error: optional boolean or null`
1619
1620 Whether the tool execution resulted in an error.
3221621
3231622 - `processed_at: optional string or null`
3241623
from line 1625
3261625
3271626 format: date-time
3281627
329 - `BetaManagedAgentsUserInterruptEvent object`
330
331 An interrupt event that pauses agent execution and returns control to the user.
332
333 - `id: string`
334
335 Unique identifier for this event.
336
337 - `type: "user.interrupt"`
1628 - `session_thread_id: optional string or null`
1629
1630 Routes this result to a subagent thread. Copy from the `agent.tool_use` event's `session_thread_id`.
1631
1632 - `BetaManagedAgentsSessionThreadStatusRescheduledEvent object`
1633
1634 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.
1635
1636 - `type: "session.thread_status_rescheduled"`
1637
1638 - `id: string`
1639
1640 Unique identifier for this event.
1641
1642 - `agent_name: string`
1643
1644 Name of the agent the thread runs.
1645
1646 - `processed_at: string`
1647
1648 A timestamp in RFC 3339 format
1649
1650 format: date-time
1651
1652 - `session_thread_id: string`
1653
1654 Public sthr_ ID of the thread that is retrying.
1655
1656 - `BetaManagedAgentsSessionUpdatedEvent object`
1657
1658 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.
1659
1660 - `type: "session.updated"`
1661
1662 - `id: string`
1663
1664 Unique identifier for this event.
1665
1666 - `processed_at: string`
1667
1668 A timestamp in RFC 3339 format
1669
1670 format: date-time
1671
1672 - `agent: optional BetaManagedAgentsSessionAgent or null`
1673
1674 Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time.
1675
1676 - `type: "agent"`
1677
1678 - `id: string`
1679
1680 - `description: string or null`
1681
1682 - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition`
1683
1684 - `type: "url"`
1685
1686 - `name: string`
1687
1688 - `url: string`
1689
1690 - `model: BetaManagedAgentsModelConfig`
1691
1692 Model identifier and configuration.
1693
1694 - `id: BetaManagedAgentsModel`
1695
1696 The model that will power your agent.
1697
1698 See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options.
1699
1700 - `"claude-fable-5-1" or "claude-sonnet-5" or "claude-fable-5" or 11 more`
1701
1702 The model that will power your agent.
1703
1704 See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options.
1705
1706 - `"claude-fable-5-1"`
1707
1708 Frontier intelligence for ambitious tasks across coding, scientific discovery, and enterprise workflows
1709
1710 - `"claude-sonnet-5"`
1711
1712 High-performance model for coding and agents
1713
1714 - `"claude-fable-5"`
1715
1716 Next generation of intelligence for the hardest knowledge work and coding problems
1717
1718 - `"claude-opus-5"`
1719
1720 Powerful intelligence for long-running agents and coding
1721
1722 - `"claude-opus-4-8"`
1723
1724 Powerful intelligence for long-running agents and coding
1725
1726 - `"claude-opus-4-7"`
1727
1728 Powerful intelligence for long-running agents and coding
1729
1730 - `"claude-opus-4-6"`
1731
1732 Powerful intelligence for long-running agents and coding
1733
1734 - `"claude-sonnet-4-6"`
1735
1736 Best combination of speed and intelligence
1737
1738 - `"claude-haiku-4-5"`
1739
1740 Fastest model with near-frontier intelligence
1741
1742 - `"claude-haiku-4-5-20251001"`
1743
1744 Fastest model with near-frontier intelligence
1745
1746 - `"claude-opus-4-5"`
1747
1748 Powerful intelligence for long-running agents and coding
1749
1750 - `"claude-opus-4-5-20251101"`
1751
1752 Powerful intelligence for long-running agents and coding
1753
1754 - `"claude-sonnet-4-5"`
1755
1756 High-performance model for agents and coding
1757
1758 - `"claude-sonnet-4-5-20250929"`
1759
1760 High-performance model for agents and coding
1761
1762 - `string`
1763
1764 - `effort: optional BetaManagedAgentsEffortLow or BetaManagedAgentsEffortMedium or BetaManagedAgentsEffortHigh or 2 more`
1765
1766 How hard Claude works on each turn. Sets `output_config.effort` on every Messages call the session makes.
1767
1768 - `BetaManagedAgentsEffortLow object`
1769
1770 Low effort. Favors latency over reasoning depth.
1771
1772 - `type: "low"`
1773
1774 - `BetaManagedAgentsEffortMedium object`
1775
1776 Medium effort. Balances latency and reasoning depth.
1777
1778 - `type: "medium"`
1779
1780 - `BetaManagedAgentsEffortHigh object`
1781
1782 High effort. Favors reasoning depth.
1783
1784 - `type: "high"`
1785
1786 - `BetaManagedAgentsEffortXhigh object`
1787
1788 Extra-high effort. Not all models accept this level.
1789
1790 - `type: "xhigh"`
1791
1792 - `BetaManagedAgentsEffortMax object`
1793
1794 Maximum effort. Favors reasoning depth over latency.
1795
1796 - `type: "max"`
1797
1798 - `inference_geo: optional string`
1799
1800 Geographic region for model inference. When unset, requests fall through to the workspace's default_inference_geo.
1801
1802 - `speed: optional "standard" or "fast"`
1803
1804 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.
1805
1806 - `"standard"`
1807
1808 - `"fast"`
1809
1810 - `multiagent: BetaManagedAgentsSessionMultiagentCoordinator or null`
1811
1812 Resolved coordinator topology with full agent definitions for each roster member.
1813
1814 - `type: "coordinator"`
1815
1816 - `agents: array of BetaManagedAgentsSessionThreadAgent or BetaManagedAgentsAdvisor`
1817
1818 Full `agent` definitions the coordinator may spawn as session threads.
1819
1820 - `BetaManagedAgentsSessionThreadAgent object`
1821
1822 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`.
1823
1824 - `type: "agent"`
1825
1826 - `id: string`
1827
1828 - `description: string or null`
1829
1830 - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition`
1831
1832 - `type: "url"`
1833
1834 - `name: string`
1835
1836 - `url: string`
1837
1838 - `model: BetaManagedAgentsModelConfig`
1839
1840 Model identifier and configuration.
1841
1842 - `name: string`
1843
1844 - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill`
1845
1846 - `BetaManagedAgentsAnthropicSkill object`
1847
1848 A resolved Anthropic-managed skill.
1849
1850 - `type: "anthropic"`
1851
1852 - `skill_id: string`
1853
1854 - `version: string`
1855
1856 - `BetaManagedAgentsCustomSkill object`
1857
1858 A resolved user-created custom skill.
1859
1860 - `type: "custom"`
1861
1862 - `skill_id: string`
1863
1864 - `version: string`
1865
1866 - `system: string or null`
1867
1868 - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool`
1869
1870 - `BetaManagedAgentsAgentToolset20260401 object`
1871
1872 - `type: "agent_toolset_20260401"`
1873
1874 - `configs: array of BetaManagedAgentsAgentToolConfig`
1875
1876 - `BetaManagedAgentsBashToolConfig object`
1877
1878 Configuration for the bash tool.
1879
1880 - `type: "bash"`
1881
1882 - `enabled: boolean`
1883
1884 - `name: "bash"`
1885
1886 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
1887
1888 Permission policy for tool execution.
1889
1890 - `BetaManagedAgentsAlwaysAllowPolicy object`
1891
1892 Tool calls are automatically approved without user confirmation.
1893
1894 - `type: "always_allow"`
1895
1896 - `BetaManagedAgentsAlwaysAskPolicy object`
1897
1898 Tool calls require user confirmation before execution.
1899
1900 - `type: "always_ask"`
1901
1902 - `BetaManagedAgentsAutoPolicy object`
1903
1904 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
1905
1906 - `type: "auto"`
1907
1908 - `BetaManagedAgentsEditToolConfig object`
1909
1910 Configuration for the edit tool.
1911
1912 - `type: "edit"`
1913
1914 - `enabled: boolean`
1915
1916 - `name: "edit"`
1917
1918 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
1919
1920 Permission policy for tool execution.
1921
1922 - `BetaManagedAgentsAlwaysAllowPolicy object`
1923
1924 Tool calls are automatically approved without user confirmation.
1925
1926 - `BetaManagedAgentsAlwaysAskPolicy object`
1927
1928 Tool calls require user confirmation before execution.
1929
1930 - `BetaManagedAgentsAutoPolicy object`
1931
1932 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
1933
1934 - `BetaManagedAgentsReadToolConfig object`
1935
1936 Configuration for the read tool.
1937
1938 - `type: "read"`
1939
1940 - `enabled: boolean`
1941
1942 - `name: "read"`
1943
1944 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
1945
1946 Permission policy for tool execution.
1947
1948 - `BetaManagedAgentsAlwaysAllowPolicy object`
1949
1950 Tool calls are automatically approved without user confirmation.
1951
1952 - `BetaManagedAgentsAlwaysAskPolicy object`
1953
1954 Tool calls require user confirmation before execution.
1955
1956 - `BetaManagedAgentsAutoPolicy object`
1957
1958 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
1959
1960 - `BetaManagedAgentsWriteToolConfig object`
1961
1962 Configuration for the write tool.
1963
1964 - `type: "write"`
1965
1966 - `enabled: boolean`
1967
1968 - `name: "write"`
1969
1970 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
1971
1972 Permission policy for tool execution.
1973
1974 - `BetaManagedAgentsAlwaysAllowPolicy object`
1975
1976 Tool calls are automatically approved without user confirmation.
1977
1978 - `BetaManagedAgentsAlwaysAskPolicy object`
1979
1980 Tool calls require user confirmation before execution.
1981
1982 - `BetaManagedAgentsAutoPolicy object`
1983
1984 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
1985
1986 - `BetaManagedAgentsGlobToolConfig object`
1987
1988 Configuration for the glob tool.
1989
1990 - `type: "glob"`
1991
1992 - `enabled: boolean`
1993
1994 - `name: "glob"`
1995
1996 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
1997
1998 Permission policy for tool execution.
1999
2000 - `BetaManagedAgentsAlwaysAllowPolicy object`
2001
2002 Tool calls are automatically approved without user confirmation.
2003
2004 - `BetaManagedAgentsAlwaysAskPolicy object`
2005
2006 Tool calls require user confirmation before execution.
2007
2008 - `BetaManagedAgentsAutoPolicy object`
2009
2010 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
2011
2012 - `BetaManagedAgentsGrepToolConfig object`
2013
2014 Configuration for the grep tool.
2015
2016 - `type: "grep"`
2017
2018 - `enabled: boolean`
2019
2020 - `name: "grep"`
2021
2022 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
2023
2024 Permission policy for tool execution.
2025
2026 - `BetaManagedAgentsAlwaysAllowPolicy object`
2027
2028 Tool calls are automatically approved without user confirmation.
2029
2030 - `BetaManagedAgentsAlwaysAskPolicy object`
2031
2032 Tool calls require user confirmation before execution.
2033
2034 - `BetaManagedAgentsAutoPolicy object`
2035
2036 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
2037
2038 - `BetaManagedAgentsWebFetchToolConfig object`
2039
2040 Configuration for the web_fetch tool.
2041
2042 - `type: "web_fetch"`
2043
2044 - `enabled: boolean`
2045
2046 - `name: "web_fetch"`
2047
2048 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
2049
2050 Permission policy for tool execution.
2051
2052 - `BetaManagedAgentsAlwaysAllowPolicy object`
2053
2054 Tool calls are automatically approved without user confirmation.
2055
2056 - `BetaManagedAgentsAlwaysAskPolicy object`
2057
2058 Tool calls require user confirmation before execution.
2059
2060 - `BetaManagedAgentsAutoPolicy object`
2061
2062 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
2063
2064 - `allowed_domains: optional array of string`
2065
2066 - `blocked_domains: optional array of string`
2067
2068 - `max_content_tokens: optional number or null`
2069
2070 format: int32
2071
2072 - `BetaManagedAgentsWebSearchToolConfig object`
2073
2074 Configuration for the web_search tool.
2075
2076 - `type: "web_search"`
2077
2078 - `enabled: boolean`
2079
2080 - `name: "web_search"`
2081
2082 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
2083
2084 Permission policy for tool execution.
2085
2086 - `BetaManagedAgentsAlwaysAllowPolicy object`
2087
2088 Tool calls are automatically approved without user confirmation.
2089
2090 - `BetaManagedAgentsAlwaysAskPolicy object`
2091
2092 Tool calls require user confirmation before execution.
2093
2094 - `BetaManagedAgentsAutoPolicy object`
2095
2096 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
2097
2098 - `allowed_domains: optional array of string`
2099
2100 - `blocked_domains: optional array of string`
2101
2102 - `user_location: optional BetaManagedAgentsUserLocation or null`
2103
2104 Approximate user location for search result localization.
2105
2106 - `type: "approximate"`
2107
2108 Location precision. Only "approximate" is supported.
2109
2110 - `city: optional string or null`
2111
2112 City name.
2113
2114 minLength: 1, maxLength: 255
2115
2116 - `country: optional string or null`
2117
2118 Two-letter ISO 3166-1 country code, uppercase.
2119
2120 - `region: optional string or null`
2121
2122 Region or state name.
2123
2124 minLength: 1, maxLength: 255
2125
2126 - `timezone: optional string or null`
2127
2128 IANA timezone identifier, e.g. "America/Los_Angeles".
2129
2130 minLength: 1, maxLength: 255
2131
2132 - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig`
2133
2134 Resolved default configuration for agent tools.
2135
2136 - `enabled: boolean`
2137
2138 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
2139
2140 Permission policy for tool execution.
2141
2142 - `BetaManagedAgentsAlwaysAllowPolicy object`
2143
2144 Tool calls are automatically approved without user confirmation.
2145
2146 - `BetaManagedAgentsAlwaysAskPolicy object`
2147
2148 Tool calls require user confirmation before execution.
2149
2150 - `BetaManagedAgentsAutoPolicy object`
2151
2152 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
2153
2154 - `BetaManagedAgentsMCPToolset object`
2155
2156 - `type: "mcp_toolset"`
2157
2158 - `configs: array of BetaManagedAgentsMCPToolConfig`
2159
2160 - `enabled: boolean`
2161
2162 - `name: string`
2163
2164 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
2165
2166 Permission policy for tool execution.
2167
2168 - `BetaManagedAgentsAlwaysAllowPolicy object`
2169
2170 Tool calls are automatically approved without user confirmation.
2171
2172 - `BetaManagedAgentsAlwaysAskPolicy object`
2173
2174 Tool calls require user confirmation before execution.
2175
2176 - `BetaManagedAgentsAutoPolicy object`
2177
2178 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
2179
2180 - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig`
2181
2182 Resolved default configuration for all tools from an MCP server.
2183
2184 - `enabled: boolean`
2185
2186 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
2187
2188 Permission policy for tool execution.
2189
2190 - `BetaManagedAgentsAlwaysAllowPolicy object`
2191
2192 Tool calls are automatically approved without user confirmation.
2193
2194 - `BetaManagedAgentsAlwaysAskPolicy object`
2195
2196 Tool calls require user confirmation before execution.
2197
2198 - `BetaManagedAgentsAutoPolicy object`
2199
2200 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
2201
2202 - `mcp_server_name: string`
2203
2204 - `BetaManagedAgentsCustomTool object`
2205
2206 A custom tool as returned in API responses.
2207
2208 - `type: "custom"`
2209
2210 - `description: string`
2211
2212 - `input_schema: BetaManagedAgentsCustomToolInputSchema`
2213
2214 JSON Schema for custom tool input parameters.
2215
2216 - `type: "object"`
2217
2218 - `properties: optional map[unknown] or null`
2219
2220 - `required: optional array of string or null`
2221
2222 - `name: string`
2223
2224 - `version: number`
2225
2226 format: int32
2227
2228 - `BetaManagedAgentsAdvisor object`
2229
2230 Platform advisor roster entry: a model the session's primary thread may consult mid-turn.
2231
2232 - `type: "advisor"`
2233
2234 - `model: string`
2235
2236 The advisor model id.
2237
2238 - `name: string`
2239
2240 - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill`
2241
2242 - `BetaManagedAgentsAnthropicSkill object`
2243
2244 A resolved Anthropic-managed skill.
2245
2246 - `BetaManagedAgentsCustomSkill object`
2247
2248 A resolved user-created custom skill.
2249
2250 - `system: string or null`
2251
2252 - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool`
2253
2254 - `BetaManagedAgentsAgentToolset20260401 object`
2255
2256 - `BetaManagedAgentsMCPToolset object`
2257
2258 - `BetaManagedAgentsCustomTool object`
2259
2260 A custom tool as returned in API responses.
2261
2262 - `version: number`
2263
2264 format: int32
2265
2266 - `budget: optional BetaManagedAgentsBudgetLimit or null`
2267
2268 A hard spend ceiling. The session stops issuing new model requests once the tracked list cost reaches `max_list_cost`.
2269
2270 - `type: "limit"`
2271
2272 - `max_list_cost: BetaMonetaryAmount`
2273
2274 A monetary amount in a specific currency.
2275
2276 - `amount: string`
2277
2278 Amount in minor units of the currency, as an integer decimal string with no leading zeros: "2500" is $25.00 and "50" is fifty cents. A string rather than a number so no float rounding is ever applied.
2279
2280 - `currency: BetaCurrency`
2281
2282 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.
2283
2284 - `metadata: optional map[string]`
2285
2286 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.
2287
2288 - `title: optional string or null`
2289
2290 The session's new title. Present only when the update changed it.
2291
2292 - `BetaManagedAgentsSystemMessageEvent object`
2293
2294 A mid-conversation system message event. Carries system-role content that is appended to the session as a `role: "system"` turn.
2295
2296 - `type: "system.message"`
2297
2298 - `id: string`
2299
2300 Unique identifier for this event.
2301
2302 - `content: array of BetaManagedAgentsSystemContentBlock`
2303
2304 System content blocks. Text-only.
2305
2306 - `type: "text"`
2307
2308 - `text: string`
2309
2310 The text content.
2311
2312 minLength: 1
3382313
3392314 - `processed_at: optional string or null`
3402315
from line 2317
3422317
3432318 format: date-time
3442319
345 - `session_thread_id: optional string or null`
346
347 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.
348
349 - `BetaManagedAgentsUserToolConfirmationEvent object`
350
351 A tool confirmation event that approves or denies a pending tool execution.
352
353 - `id: string`
354
355 Unique identifier for this event.
356
357 - `result: "allow" or "deny"`
358
359 UserToolConfirmationResult enum
360
361 - `"allow"`
362
363 - `"deny"`
364
365 - `tool_use_id: string`
366
367 The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field.
368
369 - `type: "user.tool_confirmation"`
370
371 - `deny_message: optional string or null`
372
373 Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'.
374
375 maxLength: 10000
376
377 - `processed_at: optional string or null`
378
379 A timestamp in RFC 3339 format
380
381 format: date-time
382
383 - `session_thread_id: optional string or null`
384
385 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.
386
387 - `BetaManagedAgentsUserCustomToolResultEvent object`
388
389 Event sent by the client providing the result of a custom tool execution.
390
391 - `id: string`
392
393 Unique identifier for this event.
394
395 - `custom_tool_use_id: string`
396
397 The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field.
398
399 - `type: "user.custom_tool_result"`
400
401 - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock`
402
403 The result content returned by the tool.
404
405 - `BetaManagedAgentsTextBlock object`
406
407 Regular text content.
408
409 - `BetaManagedAgentsImageBlock object`
410
411 Image content specified directly as base64 data or as a reference via a URL.
412
413 - `BetaManagedAgentsDocumentBlock object`
414
415 Document content, either specified directly as base64 data, as text, or as a reference via a URL.
416
417 - `BetaManagedAgentsSearchResultBlock object`
418
419 A block containing a web search result.
420
421 - `citations: BetaManagedAgentsSearchResultCitations`
422
423 Citation settings for a search result.
424
425 - `enabled: boolean`
426
427 Whether citations are enabled for this search result.
428
429 - `content: array of BetaManagedAgentsSearchResultContent`
430
431 Array of text content blocks from the search result.
432
433 - `text: string`
434
435 The text content.
436
437 minLength: 1
438
439 - `type: "text"`
440
441 - `source: string`
442
443 The URL source of the search result.
444
445 minLength: 1
446
447 - `title: string`
448
449 The title of the search result.
450
451 minLength: 1
452
453 - `type: "search_result"`
454
455 - `is_error: optional boolean or null`
456
457 Whether the tool execution resulted in an error.
458
459 - `processed_at: optional string or null`
460
461 A timestamp in RFC 3339 format
462
463 format: date-time
464
465 - `session_thread_id: optional string or null`
466
467 Routes this result to a subagent thread. Copy from the `agent.custom_tool_use` event's `session_thread_id`.
468
469 - `BetaManagedAgentsAgentCustomToolUseEvent object`
470
471 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.
472
473 - `id: string`
474
475 Unique identifier for this event.
476
477 - `input: map[unknown]`
478
479 Input parameters for the tool call.
480
481 - `name: string`
482
483 Name of the custom tool being called.
484
485 - `processed_at: string`
486
487 A timestamp in RFC 3339 format
488
489 format: date-time
490
491 - `type: "agent.custom_tool_use"`
492
493 - `session_thread_id: optional string or null`
494
495 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.
496
497 - `BetaManagedAgentsAgentMessageEvent object`
498
499 An agent response event in the session conversation.
500
501 - `id: string`
502
503 Unique identifier for this event.
504
505 - `content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsRedactedBlock`
506
507 Array of text blocks comprising the agent response.
508
509 - `BetaManagedAgentsTextBlock object`
510
511 Regular text content.
512
513 - `BetaManagedAgentsRedactedBlock object`
514
515 Placeholder for content withheld by Anthropic model policy.
516
517 - `processed_at: string`
518
519 A timestamp in RFC 3339 format
520
521 format: date-time
522
523 - `type: "agent.message"`
524
525 - `BetaManagedAgentsAgentThinkingEvent object`
526
527 Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier.
528
529 - `id: string`
530
531 Unique identifier for this event.
532
533 - `processed_at: string`
534
535 A timestamp in RFC 3339 format
536
537 format: date-time
538
539 - `type: "agent.thinking"`
540
541 - `BetaManagedAgentsAgentMCPToolUseEvent object`
542
543 Event emitted when the agent invokes a tool provided by an MCP server.
544
545 - `id: string`
546
547 Unique identifier for this event.
548
549 - `input: map[unknown]`
550
551 Input parameters for the tool call.
552
553 - `mcp_server_name: string`
554
555 Name of the MCP server providing the tool.
556
557 - `name: string`
558
559 Name of the MCP tool being used.
560
561 - `processed_at: string`
562
563 A timestamp in RFC 3339 format
564
565 format: date-time
566
567 - `type: "agent.mcp_tool_use"`
568
569 - `evaluated_permission: optional "allow" or "ask" or "deny"`
570
571 AgentEvaluatedPermission enum
572
573 - `"allow"`
574
575 - `"ask"`
576
577 - `"deny"`
578
579 - `session_thread_id: optional string or null`
580
581 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.
582
583 - `BetaManagedAgentsAgentMCPToolResultEvent object`
584
585 Event representing the result of an MCP tool execution.
586
587 - `id: string`
588
589 Unique identifier for this event.
590
591 - `mcp_tool_use_id: string`
592
593 The id of the `agent.mcp_tool_use` event this result corresponds to.
594
595 - `processed_at: string`
596
597 A timestamp in RFC 3339 format
598
599 format: date-time
600
601 - `type: "agent.mcp_tool_result"`
602
603 - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock`
604
605 The result content returned by the tool.
606
607 - `BetaManagedAgentsTextBlock object`
608
609 Regular text content.
610
611 - `BetaManagedAgentsImageBlock object`
612
613 Image content specified directly as base64 data or as a reference via a URL.
614
615 - `BetaManagedAgentsDocumentBlock object`
616
617 Document content, either specified directly as base64 data, as text, or as a reference via a URL.
618
619 - `BetaManagedAgentsSearchResultBlock object`
620
621 A block containing a web search result.
622
623 - `is_error: optional boolean or null`
624
625 Whether the tool execution resulted in an error.
626
627 - `BetaManagedAgentsAgentToolUseEvent object`
628
629 Event emitted when the agent invokes a built-in agent tool.
630
631 - `id: string`
632
633 Unique identifier for this event.
634
635 - `input: map[unknown]`
636
637 Input parameters for the tool call.
638
639 - `name: string`
640
641 Name of the agent tool being used.
642
643 - `processed_at: string`
644
645 A timestamp in RFC 3339 format
646
647 format: date-time
648
649 - `type: "agent.tool_use"`
650
651 - `evaluated_permission: optional "allow" or "ask" or "deny"`
652
653 AgentEvaluatedPermission enum
654
655 - `"allow"`
656
657 - `"ask"`
658
659 - `"deny"`
660
661 - `session_thread_id: optional string or null`
662
663 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.
664
665 - `BetaManagedAgentsAgentToolResultEvent object`
666
667 Event representing the result of an agent tool execution.
668
669 - `id: string`
670
671 Unique identifier for this event.
672
673 - `processed_at: string`
674
675 A timestamp in RFC 3339 format
676
677 format: date-time
678
679 - `tool_use_id: string`
680
681 The id of the `agent.tool_use` event this result corresponds to.
682
683 - `type: "agent.tool_result"`
684
685 - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock`
686
687 The result content returned by the tool.
688
689 - `BetaManagedAgentsTextBlock object`
690
691 Regular text content.
692
693 - `BetaManagedAgentsImageBlock object`
694
695 Image content specified directly as base64 data or as a reference via a URL.
696
697 - `BetaManagedAgentsDocumentBlock object`
698
699 Document content, either specified directly as base64 data, as text, or as a reference via a URL.
700
701 - `BetaManagedAgentsSearchResultBlock object`
702
703 A block containing a web search result.
704
705 - `is_error: optional boolean or null`
706
707 Whether the tool execution resulted in an error.
708
709 - `BetaManagedAgentsAgentThreadMessageReceivedEvent object`
710
711 Delivery event written to the target thread's input stream when an agent-to-agent message arrives.
712
713 - `id: string`
714
715 Unique identifier for this event.
716
717 - `content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsRedactedBlock`
718
719 Message content blocks.
720
721 - `BetaManagedAgentsTextBlock object`
722
723 Regular text content.
724
725 - `BetaManagedAgentsImageBlock object`
726
727 Image content specified directly as base64 data or as a reference via a URL.
728
729 - `BetaManagedAgentsDocumentBlock object`
730
731 Document content, either specified directly as base64 data, as text, or as a reference via a URL.
732
733 - `BetaManagedAgentsRedactedBlock object`
734
735 Placeholder for content withheld by Anthropic model policy.
736
737 - `from_session_thread_id: string`
738
739 Public `sthr_` ID of the thread that sent the message.
740
741 - `processed_at: string`
742
743 A timestamp in RFC 3339 format
744
745 format: date-time
746
747 - `type: "agent.thread_message_received"`
748
749 - `from_agent_name: optional string or null`
750
751 Name of the callable agent this message came from. Absent when received from the primary agent.
752
753 - `BetaManagedAgentsAgentThreadMessageSentEvent object`
754
755 Observability event emitted to the sender's output stream when an agent-to-agent message is sent.
756
757 - `id: string`
758
759 Unique identifier for this event.
760
761 - `content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsRedactedBlock`
762
763 Message content blocks.
764
765 - `BetaManagedAgentsTextBlock object`
766
767 Regular text content.
768
769 - `BetaManagedAgentsImageBlock object`
770
771 Image content specified directly as base64 data or as a reference via a URL.
772
773 - `BetaManagedAgentsDocumentBlock object`
774
775 Document content, either specified directly as base64 data, as text, or as a reference via a URL.
776
777 - `BetaManagedAgentsRedactedBlock object`
778
779 Placeholder for content withheld by Anthropic model policy.
780
781 - `processed_at: string`
782
783 A timestamp in RFC 3339 format
784
785 format: date-time
786
787 - `to_session_thread_id: string`
788
789 Public `sthr_` ID of the thread the message was sent to.
790
791 - `type: "agent.thread_message_sent"`
792
793 - `to_agent_name: optional string or null`
794
795 Name of the callable agent this message was sent to. Absent when sent to the primary agent.
796
797 - `BetaManagedAgentsAgentThreadContextCompactedEvent object`
798
799 Indicates that context compaction (summarization) occurred during the session.
800
801 - `id: string`
802
803 Unique identifier for this event.
804
805 - `processed_at: string`
806
807 A timestamp in RFC 3339 format
808
809 format: date-time
810
811 - `type: "agent.thread_context_compacted"`
812
813 - `BetaManagedAgentsSessionErrorEvent object`
814
815 An error event indicating a problem occurred during session execution.
816
817 - `id: string`
818
819 Unique identifier for this event.
820
821 - `error: BetaManagedAgentsUnknownError or BetaManagedAgentsModelOverloadedError or BetaManagedAgentsModelRateLimitedError or 5 more`
822
823 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.
824
825 - `BetaManagedAgentsUnknownError object`
826
827 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.
828
829 - `message: string`
830
831 Human-readable error description.
832
833 - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal`
834
835 What the client should do next in response to this error.
836
837 - `BetaManagedAgentsRetryStatusRetrying object`
838
839 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.
840
841 - `type: "retrying"`
842
843 - `BetaManagedAgentsRetryStatusExhausted object`
844
845 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
846
847 - `type: "exhausted"`
848
849 - `BetaManagedAgentsRetryStatusTerminal object`
850
851 The session encountered a terminal error and will transition to `terminated` state.
852
853 - `type: "terminal"`
854
855 - `type: "unknown_error"`
856
857 - `BetaManagedAgentsModelOverloadedError object`
858
859 The model is currently overloaded. Emitted after automatic retries are exhausted.
860
861 - `message: string`
862
863 Human-readable error description.
864
865 - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal`
866
867 What the client should do next in response to this error.
868
869 - `BetaManagedAgentsRetryStatusRetrying object`
870
871 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.
872
873 - `BetaManagedAgentsRetryStatusExhausted object`
874
875 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
876
877 - `BetaManagedAgentsRetryStatusTerminal object`
878
879 The session encountered a terminal error and will transition to `terminated` state.
880
881 - `type: "model_overloaded_error"`
882
883 - `BetaManagedAgentsModelRateLimitedError object`
884
885 The model request was rate-limited.
886
887 - `message: string`
888
889 Human-readable error description.
890
891 - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal`
892
893 What the client should do next in response to this error.
894
895 - `BetaManagedAgentsRetryStatusRetrying object`
896
897 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.
898
899 - `BetaManagedAgentsRetryStatusExhausted object`
900
901 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
902
903 - `BetaManagedAgentsRetryStatusTerminal object`
904
905 The session encountered a terminal error and will transition to `terminated` state.
906
907 - `type: "model_rate_limited_error"`
908
909 - `BetaManagedAgentsModelRequestFailedError object`
910
911 A model request failed for a reason other than overload or rate-limiting.
912
913 - `message: string`
914
915 Human-readable error description.
916
917 - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal`
918
919 What the client should do next in response to this error.
920
921 - `BetaManagedAgentsRetryStatusRetrying object`
922
923 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.
924
925 - `BetaManagedAgentsRetryStatusExhausted object`
926
927 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
928
929 - `BetaManagedAgentsRetryStatusTerminal object`
930
931 The session encountered a terminal error and will transition to `terminated` state.
932
933 - `type: "model_request_failed_error"`
934
935 - `BetaManagedAgentsMCPConnectionFailedError object`
936
937 Failed to connect to an MCP server.
938
939 - `mcp_server_name: string`
940
941 Name of the MCP server that failed to connect.
942
943 - `message: string`
944
945 Human-readable error description.
946
947 - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal`
948
949 What the client should do next in response to this error.
950
951 - `BetaManagedAgentsRetryStatusRetrying object`
952
953 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.
954
955 - `BetaManagedAgentsRetryStatusExhausted object`
956
957 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
958
959 - `BetaManagedAgentsRetryStatusTerminal object`
960
961 The session encountered a terminal error and will transition to `terminated` state.
962
963 - `type: "mcp_connection_failed_error"`
964
965 - `BetaManagedAgentsMCPAuthenticationFailedError object`
966
967 Authentication to an MCP server failed.
968
969 - `mcp_server_name: string`
970
971 Name of the MCP server that failed authentication.
972
973 - `message: string`
974
975 Human-readable error description.
976
977 - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal`
978
979 What the client should do next in response to this error.
980
981 - `BetaManagedAgentsRetryStatusRetrying object`
982
983 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.
984
985 - `BetaManagedAgentsRetryStatusExhausted object`
986
987 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
988
989 - `BetaManagedAgentsRetryStatusTerminal object`
990
991 The session encountered a terminal error and will transition to `terminated` state.
992
993 - `type: "mcp_authentication_failed_error"`
994
995 - `BetaManagedAgentsBillingError object`
996
997 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.
998
999 - `message: string`
1000
1001 Human-readable error description.
1002
1003 - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal`
1004
1005 What the client should do next in response to this error.
1006
1007 - `BetaManagedAgentsRetryStatusRetrying object`
1008
1009 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.
1010
1011 - `BetaManagedAgentsRetryStatusExhausted object`
1012
1013 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
1014
1015 - `BetaManagedAgentsRetryStatusTerminal object`
1016
1017 The session encountered a terminal error and will transition to `terminated` state.
1018
1019 - `type: "billing_error"`
1020
1021 - `BetaManagedAgentsCredentialHostUnreachableError object`
1022
1023 An `environment_variable` credential's `auth.networking.allowed_hosts` includes a host the environment's network policy does not permit.
1024
1025 - `credential_id: string`
1026
1027 ID of the affected credential.
1028
1029 - `message: string`
1030
1031 Human-readable error description.
1032
1033 - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal`
1034
1035 What the client should do next in response to this error.
1036
1037 - `BetaManagedAgentsRetryStatusRetrying object`
1038
1039 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.
1040
1041 - `BetaManagedAgentsRetryStatusExhausted object`
1042
1043 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
1044
1045 - `BetaManagedAgentsRetryStatusTerminal object`
1046
1047 The session encountered a terminal error and will transition to `terminated` state.
1048
1049 - `type: "credential_host_unreachable_error"`
1050
1051 - `vault_id: string`
1052
1053 ID of the vault containing the affected credential.
1054
1055 - `processed_at: string`
1056
1057 A timestamp in RFC 3339 format
1058
1059 format: date-time
1060
1061 - `type: "session.error"`
1062
1063 - `BetaManagedAgentsSessionStatusRescheduledEvent object`
1064
1065 Indicates the session is recovering from an error state and is rescheduled for execution.
1066
1067 - `id: string`
1068
1069 Unique identifier for this event.
1070
1071 - `processed_at: string`
1072
1073 A timestamp in RFC 3339 format
1074
1075 format: date-time
1076
1077 - `type: "session.status_rescheduled"`
1078
1079 - `BetaManagedAgentsSessionStatusRunningEvent object`
1080
1081 Indicates the session is actively running and the agent is working.
1082
1083 - `id: string`
1084
1085 Unique identifier for this event.
1086
1087 - `processed_at: string`
1088
1089 A timestamp in RFC 3339 format
1090
1091 format: date-time
1092
1093 - `type: "session.status_running"`
1094
1095 - `BetaManagedAgentsSessionStatusIdleEvent object`
1096
1097 Indicates the agent has paused and is awaiting user input.
1098
1099 - `id: string`
1100
1101 Unique identifier for this event.
1102
1103 - `processed_at: string`
1104
1105 A timestamp in RFC 3339 format
1106
1107 format: date-time
1108
1109 - `stop_reason: BetaManagedAgentsSessionEndTurn or BetaManagedAgentsSessionRequiresAction or BetaManagedAgentsSessionRetriesExhausted or BetaManagedAgentsSessionBudgetReached`
1110
1111 The agent completed its turn naturally and is ready for the next user message.
1112
1113 - `BetaManagedAgentsSessionEndTurn object`
1114
1115 The agent completed its turn naturally and is ready for the next user message.
1116
1117 - `type: "end_turn"`
1118
1119 - `BetaManagedAgentsSessionRequiresAction object`
1120
1121 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.
1122
1123 - `event_ids: array of string`
1124
1125 The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder.
1126
1127 - `type: "requires_action"`
1128
1129 - `BetaManagedAgentsSessionRetriesExhausted object`
1130
1131 The turn ended because repeated errors exhausted the retry budget or an error escalated to `retry_status: 'exhausted'`.
1132
1133 - `type: "retries_exhausted"`
1134
1135 - `BetaManagedAgentsSessionBudgetReached object`
1136
1137 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.
1138
1139 - `type: "budget_reached"`
1140
1141 - `type: "session.status_idle"`
1142
1143 - `BetaManagedAgentsSessionStatusTerminatedEvent object`
1144
1145 Indicates the session has terminated, either due to an error or completion.
1146
1147 - `id: string`
1148
1149 Unique identifier for this event.
1150
1151 - `processed_at: string`
1152
1153 A timestamp in RFC 3339 format
1154
1155 format: date-time
1156
1157 - `type: "session.status_terminated"`
1158
1159 - `BetaManagedAgentsSessionThreadCreatedEvent object`
1160
1161 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.
1162
1163 - `id: string`
1164
1165 Unique identifier for this event.
1166
1167 - `agent_name: string`
1168
1169 Name of the callable agent the thread runs.
1170
1171 - `processed_at: string`
1172
1173 A timestamp in RFC 3339 format
1174
1175 format: date-time
1176
1177 - `session_thread_id: string`
1178
1179 Public `sthr_` ID of the newly created thread.
1180
1181 - `type: "session.thread_created"`
1182
1183 - `BetaManagedAgentsSpanOutcomeEvaluationStartEvent object`
1184
1185 Emitted when an outcome evaluation cycle begins.
1186
1187 - `id: string`
1188
1189 Unique identifier for this event.
1190
1191 - `iteration: number`
1192
1193 0-indexed revision cycle. 0 is the first evaluation; 1 is the re-evaluation after the first revision; etc.
1194
1195 format: int32
1196
1197 - `outcome_id: string`
1198
1199 The `outc_` ID of the outcome being evaluated.
1200
1201 - `processed_at: string`
1202
1203 A timestamp in RFC 3339 format
1204
1205 format: date-time
1206
1207 - `type: "span.outcome_evaluation_start"`
1208
1209 - `BetaManagedAgentsSpanOutcomeEvaluationEndEvent object`
1210
1211 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.
1212
1213 - `id: string`
1214
1215 Unique identifier for this event.
1216
1217 - `explanation: string`
1218
1219 Human-readable explanation of the verdict. For `needs_revision`, describes which criteria failed and why.
1220
1221 - `iteration: number`
1222
1223 0-indexed revision cycle, matching the corresponding `span.outcome_evaluation_start`.
1224
1225 format: int32
1226
1227 - `outcome_evaluation_start_id: string`
1228
1229 The id of the corresponding `span.outcome_evaluation_start` event.
1230
1231 - `outcome_id: string`
1232
1233 The `outc_` ID of the outcome being evaluated.
1234
1235 - `processed_at: string`
1236
1237 A timestamp in RFC 3339 format
1238
1239 format: date-time
1240
1241 - `result: string`
1242
1243 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.
1244
1245 - `type: "span.outcome_evaluation_end"`
1246
1247 - `usage: BetaManagedAgentsSpanModelUsage`
1248
1249 Token usage for a single model request.
1250
1251 - `cache_creation_input_tokens: number`
1252
1253 Tokens used to create prompt cache in this request.
1254
1255 format: int32
1256
1257 - `cache_read_input_tokens: number`
1258
1259 Tokens read from prompt cache in this request.
1260
1261 format: int32
1262
1263 - `input_tokens: number`
1264
1265 Input tokens consumed by this request.
1266
1267 format: int32
1268
1269 - `output_tokens: number`
1270
1271 Output tokens generated by this request.
1272
1273 format: int32
1274
1275 - `speed: optional "standard" or "fast" or null`
1276
1277 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.
1278
1279 - `"standard"`
1280
1281 - `"fast"`
1282
1283 - `BetaManagedAgentsSpanModelRequestStartEvent object`
1284
1285 Emitted when a model request is initiated by the agent.
1286
1287 - `id: string`
1288
1289 Unique identifier for this event.
1290
1291 - `processed_at: string`
1292
1293 A timestamp in RFC 3339 format
1294
1295 format: date-time
1296
1297 - `type: "span.model_request_start"`
1298
1299 - `BetaManagedAgentsSpanModelRequestEndEvent object`
1300
1301 Emitted when a model request completes.
1302
1303 - `id: string`
1304
1305 Unique identifier for this event.
1306
1307 - `is_error: boolean or null`
1308
1309 Whether the model request resulted in an error.
1310
1311 - `model_request_start_id: string`
1312
1313 The id of the corresponding `span.model_request_start` event.
1314
1315 - `model_usage: BetaManagedAgentsSpanModelUsage`
1316
1317 Token usage for a single model request.
1318
1319 - `processed_at: string`
1320
1321 A timestamp in RFC 3339 format
1322
1323 format: date-time
1324
1325 - `type: "span.model_request_end"`
1326
1327 - `BetaManagedAgentsSpanOutcomeEvaluationOngoingEvent object`
1328
1329 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.
1330
1331 - `id: string`
1332
1333 Unique identifier for this event.
1334
1335 - `iteration: number`
1336
1337 0-indexed revision cycle, matching the corresponding `span.outcome_evaluation_start`.
1338
1339 format: int32
1340
1341 - `outcome_id: string`
1342
1343 The `outc_` ID of the outcome being evaluated.
1344
1345 - `processed_at: string`
1346
1347 A timestamp in RFC 3339 format
1348
1349 format: date-time
1350
1351 - `type: "span.outcome_evaluation_ongoing"`
1352
1353 - `BetaManagedAgentsUserDefineOutcomeEvent object`
1354
1355 Echo of a `user.define_outcome` input event. Carries the server-generated `outcome_id` that subsequent `span.outcome_evaluation_*` events reference.
1356
1357 - `id: string`
1358
1359 Unique identifier for this event.
1360
1361 - `description: string`
1362
1363 What the agent should produce. Copied from the input event.
1364
1365 - `max_iterations: number or null`
1366
1367 Evaluate-then-revise cycles before giving up. Default 3, max 20.
1368
1369 format: int32
1370
1371 - `outcome_id: string`
1372
1373 Server-generated `outc_` ID for this outcome. Referenced by `span.outcome_evaluation_*` events and the session's `outcome_evaluations` list.
1374
1375 - `processed_at: string`
1376
1377 A timestamp in RFC 3339 format
1378
1379 format: date-time
1380
1381 - `rubric: BetaManagedAgentsFileRubric or BetaManagedAgentsTextRubric`
1382
1383 Rubric for grading the quality of an outcome.
1384
1385 - `BetaManagedAgentsFileRubric object`
1386
1387 Rubric referenced by a file uploaded via the Files API.
1388
1389 - `file_id: string`
1390
1391 ID of the rubric file.
1392
1393 - `type: "file"`
1394
1395 - `BetaManagedAgentsTextRubric object`
1396
1397 Rubric content provided inline as text.
1398
1399 - `content: string`
1400
1401 Rubric content. Plain text or markdown — the grader treats it as freeform text.
1402
1403 - `type: "text"`
1404
1405 - `type: "user.define_outcome"`
1406
1407 - `BetaManagedAgentsSessionDeletedEvent object`
1408
1409 Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session.
1410
1411 - `id: string`
1412
1413 Unique identifier for this event.
1414
1415 - `processed_at: string`
1416
1417 A timestamp in RFC 3339 format
1418
1419 format: date-time
1420
1421 - `type: "session.deleted"`
1422
1423 - `BetaManagedAgentsSessionThreadStatusRunningEvent object`
1424
1425 A session thread has begun executing. Emitted on the thread's own stream and cross-posted to the primary stream for child threads.
1426
1427 - `id: string`
1428
1429 Unique identifier for this event.
1430
1431 - `agent_name: string`
1432
1433 Name of the agent the thread runs.
1434
1435 - `processed_at: string`
1436
1437 A timestamp in RFC 3339 format
1438
1439 format: date-time
1440
1441 - `session_thread_id: string`
1442
1443 Public sthr_ ID of the thread that started running.
1444
1445 - `type: "session.thread_status_running"`
1446
1447 - `BetaManagedAgentsSessionThreadStatusIdleEvent object`
1448
1449 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.
1450
1451 - `id: string`
1452
1453 Unique identifier for this event.
1454
1455 - `agent_name: string`
1456
1457 Name of the agent the thread runs.
1458
1459 - `processed_at: string`
1460
1461 A timestamp in RFC 3339 format
1462
1463 format: date-time
1464
1465 - `session_thread_id: string`
1466
1467 Public sthr_ ID of the thread that went idle.
1468
1469 - `stop_reason: BetaManagedAgentsSessionEndTurn or BetaManagedAgentsSessionRequiresAction or BetaManagedAgentsSessionRetriesExhausted or BetaManagedAgentsSessionBudgetReached`
1470
1471 The agent completed its turn naturally and is ready for the next user message.
1472
1473 - `BetaManagedAgentsSessionEndTurn object`
1474
1475 The agent completed its turn naturally and is ready for the next user message.
1476
1477 - `BetaManagedAgentsSessionRequiresAction object`
1478
1479 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.
1480
1481 - `BetaManagedAgentsSessionRetriesExhausted object`
1482
1483 The turn ended because repeated errors exhausted the retry budget or an error escalated to `retry_status: 'exhausted'`.
1484
1485 - `BetaManagedAgentsSessionBudgetReached object`
1486
1487 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.
1488
1489 - `type: "session.thread_status_idle"`
1490
1491 - `BetaManagedAgentsSessionThreadStatusTerminatedEvent object`
1492
1493 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.
1494
1495 - `id: string`
1496
1497 Unique identifier for this event.
1498
1499 - `agent_name: string`
1500
1501 Name of the agent the thread runs.
1502
1503 - `processed_at: string`
1504
1505 A timestamp in RFC 3339 format
1506
1507 format: date-time
1508
1509 - `session_thread_id: string`
1510
1511 Public sthr_ ID of the thread that terminated.
1512
1513 - `type: "session.thread_status_terminated"`
1514
1515 - `BetaManagedAgentsUserToolResultEvent object`
1516
1517 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.
1518
1519 - `id: string`
1520
1521 Unique identifier for this event.
1522
1523 - `tool_use_id: string`
1524
1525 The id of the `agent.tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field.
1526
1527 - `type: "user.tool_result"`
1528
1529 - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock`
1530
1531 The result content returned by the tool.
1532
1533 - `BetaManagedAgentsTextBlock object`
1534
1535 Regular text content.
1536
1537 - `BetaManagedAgentsImageBlock object`
1538
1539 Image content specified directly as base64 data or as a reference via a URL.
1540
1541 - `BetaManagedAgentsDocumentBlock object`
1542
1543 Document content, either specified directly as base64 data, as text, or as a reference via a URL.
1544
1545 - `BetaManagedAgentsSearchResultBlock object`
1546
1547 A block containing a web search result.
1548
1549 - `is_error: optional boolean or null`
1550
1551 Whether the tool execution resulted in an error.
1552
1553 - `processed_at: optional string or null`
1554
1555 A timestamp in RFC 3339 format
1556
1557 format: date-time
1558
1559 - `session_thread_id: optional string or null`
1560
1561 Routes this result to a subagent thread. Copy from the `agent.tool_use` event's `session_thread_id`.
1562
1563 - `BetaManagedAgentsSessionThreadStatusRescheduledEvent object`
1564
1565 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.
1566
1567 - `id: string`
1568
1569 Unique identifier for this event.
1570
1571 - `agent_name: string`
1572
1573 Name of the agent the thread runs.
1574
1575 - `processed_at: string`
1576
1577 A timestamp in RFC 3339 format
1578
1579 format: date-time
1580
1581 - `session_thread_id: string`
1582
1583 Public sthr_ ID of the thread that is retrying.
1584
1585 - `type: "session.thread_status_rescheduled"`
1586
1587 - `BetaManagedAgentsSessionUpdatedEvent object`
1588
1589 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.
1590
1591 - `id: string`
1592
1593 Unique identifier for this event.
1594
1595 - `processed_at: string`
1596
1597 A timestamp in RFC 3339 format
1598
1599 format: date-time
1600
1601 - `type: "session.updated"`
1602
1603 - `agent: optional BetaManagedAgentsSessionAgent or null`
1604
1605 Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time.
1606
1607 - `id: string`
1608
1609 - `description: string or null`
1610
1611 - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition`
1612
1613 - `name: string`
1614
1615 - `type: "url"`
1616
1617 - `url: string`
1618
1619 - `model: BetaManagedAgentsModelConfig`
1620
1621 Model identifier and configuration.
1622
1623 - `id: BetaManagedAgentsModel`
1624
1625 The model that will power your agent.
1626
1627 See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options.
1628
1629 - `"claude-fable-5-1" or "claude-sonnet-5" or "claude-fable-5" or 11 more`
1630
1631 The model that will power your agent.
1632
1633 See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options.
1634
1635 - `"claude-fable-5-1"`
1636
1637 Frontier intelligence for ambitious tasks across coding, scientific discovery, and enterprise workflows
1638
1639 - `"claude-sonnet-5"`
1640
1641 High-performance model for coding and agents
1642
1643 - `"claude-fable-5"`
1644
1645 Next generation of intelligence for the hardest knowledge work and coding problems
1646
1647 - `"claude-opus-5"`
1648
1649 Powerful intelligence for long-running agents and coding
1650
1651 - `"claude-opus-4-8"`
1652
1653 Powerful intelligence for long-running agents and coding
1654
1655 - `"claude-opus-4-7"`
1656
1657 Powerful intelligence for long-running agents and coding
1658
1659 - `"claude-opus-4-6"`
1660
1661 Powerful intelligence for long-running agents and coding
1662
1663 - `"claude-sonnet-4-6"`
1664
1665 Best combination of speed and intelligence
1666
1667 - `"claude-haiku-4-5"`
1668
1669 Fastest model with near-frontier intelligence
1670
1671 - `"claude-haiku-4-5-20251001"`
1672
1673 Fastest model with near-frontier intelligence
1674
1675 - `"claude-opus-4-5"`
1676
1677 Powerful intelligence for long-running agents and coding
1678
1679 - `"claude-opus-4-5-20251101"`
1680
1681 Powerful intelligence for long-running agents and coding
1682
1683 - `"claude-sonnet-4-5"`
1684
1685 High-performance model for agents and coding
1686
1687 - `"claude-sonnet-4-5-20250929"`
1688
1689 High-performance model for agents and coding
1690
1691 - `string`
1692
1693 - `effort: optional BetaManagedAgentsEffortLow or BetaManagedAgentsEffortMedium or BetaManagedAgentsEffortHigh or 2 more`
1694
1695 How hard Claude works on each turn. Sets `output_config.effort` on every Messages call the session makes.
1696
1697 - `BetaManagedAgentsEffortLow object`
1698
1699 Low effort. Favors latency over reasoning depth.
1700
1701 - `type: "low"`
1702
1703 - `BetaManagedAgentsEffortMedium object`
1704
1705 Medium effort. Balances latency and reasoning depth.
1706
1707 - `type: "medium"`
1708
1709 - `BetaManagedAgentsEffortHigh object`
1710
1711 High effort. Favors reasoning depth.
1712
1713 - `type: "high"`
1714
1715 - `BetaManagedAgentsEffortXhigh object`
1716
1717 Extra-high effort. Not all models accept this level.
1718
1719 - `type: "xhigh"`
1720
1721 - `BetaManagedAgentsEffortMax object`
1722
1723 Maximum effort. Favors reasoning depth over latency.
1724
1725 - `type: "max"`
1726
1727 - `inference_geo: optional string`
1728
1729 Geographic region for model inference. When unset, requests fall through to the workspace's default_inference_geo.
1730
1731 - `speed: optional "standard" or "fast"`
1732
1733 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.
1734
1735 - `"standard"`
1736
1737 - `"fast"`
1738
1739 - `multiagent: BetaManagedAgentsSessionMultiagentCoordinator or null`
1740
1741 Resolved coordinator topology with full agent definitions for each roster member.
1742
1743 - `agents: array of BetaManagedAgentsSessionThreadAgent or BetaManagedAgentsAdvisor`
1744
1745 Full `agent` definitions the coordinator may spawn as session threads.
1746
1747 - `BetaManagedAgentsSessionThreadAgent object`
1748
1749 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`.
1750
1751 - `id: string`
1752
1753 - `description: string or null`
1754
1755 - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition`
1756
1757 - `name: string`
1758
1759 - `type: "url"`
1760
1761 - `url: string`
1762
1763 - `model: BetaManagedAgentsModelConfig`
1764
1765 Model identifier and configuration.
1766
1767 - `name: string`
1768
1769 - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill`
1770
1771 - `BetaManagedAgentsAnthropicSkill object`
1772
1773 A resolved Anthropic-managed skill.
1774
1775 - `skill_id: string`
1776
1777 - `type: "anthropic"`
1778
1779 - `version: string`
1780
1781 - `BetaManagedAgentsCustomSkill object`
1782
1783 A resolved user-created custom skill.
1784
1785 - `skill_id: string`
1786
1787 - `type: "custom"`
1788
1789 - `version: string`
1790
1791 - `system: string or null`
1792
1793 - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool`
1794
1795 - `BetaManagedAgentsAgentToolset20260401 object`
1796
1797 - `configs: array of BetaManagedAgentsAgentToolConfig`
1798
1799 - `BetaManagedAgentsBashToolConfig object`
1800
1801 Configuration for the bash tool.
1802
1803 - `enabled: boolean`
1804
1805 - `name: "bash"`
1806
1807 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
1808
1809 Permission policy for tool execution.
1810
1811 - `BetaManagedAgentsAlwaysAllowPolicy object`
1812
1813 Tool calls are automatically approved without user confirmation.
1814
1815 - `type: "always_allow"`
1816
1817 - `BetaManagedAgentsAlwaysAskPolicy object`
1818
1819 Tool calls require user confirmation before execution.
1820
1821 - `type: "always_ask"`
1822
1823 - `type: "bash"`
1824
1825 - `BetaManagedAgentsEditToolConfig object`
1826
1827 Configuration for the edit tool.
1828
1829 - `enabled: boolean`
1830
1831 - `name: "edit"`
1832
1833 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
1834
1835 Permission policy for tool execution.
1836
1837 - `BetaManagedAgentsAlwaysAllowPolicy object`
1838
1839 Tool calls are automatically approved without user confirmation.
1840
1841 - `BetaManagedAgentsAlwaysAskPolicy object`
1842
1843 Tool calls require user confirmation before execution.
1844
1845 - `type: "edit"`
1846
1847 - `BetaManagedAgentsReadToolConfig object`
1848
1849 Configuration for the read tool.
1850
1851 - `enabled: boolean`
1852
1853 - `name: "read"`
1854
1855 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
1856
1857 Permission policy for tool execution.
1858
1859 - `BetaManagedAgentsAlwaysAllowPolicy object`
1860
1861 Tool calls are automatically approved without user confirmation.
1862
1863 - `BetaManagedAgentsAlwaysAskPolicy object`
1864
1865 Tool calls require user confirmation before execution.
1866
1867 - `type: "read"`
1868
1869 - `BetaManagedAgentsWriteToolConfig object`
1870
1871 Configuration for the write tool.
1872
1873 - `enabled: boolean`
1874
1875 - `name: "write"`
1876
1877 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
1878
1879 Permission policy for tool execution.
1880
1881 - `BetaManagedAgentsAlwaysAllowPolicy object`
1882
1883 Tool calls are automatically approved without user confirmation.
1884
1885 - `BetaManagedAgentsAlwaysAskPolicy object`
1886
1887 Tool calls require user confirmation before execution.
1888
1889 - `type: "write"`
1890
1891 - `BetaManagedAgentsGlobToolConfig object`
1892
1893 Configuration for the glob tool.
1894
1895 - `enabled: boolean`
1896
1897 - `name: "glob"`
1898
1899 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
1900
1901 Permission policy for tool execution.
1902
1903 - `BetaManagedAgentsAlwaysAllowPolicy object`
1904
1905 Tool calls are automatically approved without user confirmation.
1906
1907 - `BetaManagedAgentsAlwaysAskPolicy object`
1908
1909 Tool calls require user confirmation before execution.
1910
1911 - `type: "glob"`
1912
1913 - `BetaManagedAgentsGrepToolConfig object`
1914
1915 Configuration for the grep tool.
1916
1917 - `enabled: boolean`
1918
1919 - `name: "grep"`
1920
1921 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
1922
1923 Permission policy for tool execution.
1924
1925 - `BetaManagedAgentsAlwaysAllowPolicy object`
1926
1927 Tool calls are automatically approved without user confirmation.
1928
1929 - `BetaManagedAgentsAlwaysAskPolicy object`
1930
1931 Tool calls require user confirmation before execution.
1932
1933 - `type: "grep"`
1934
1935 - `BetaManagedAgentsWebFetchToolConfig object`
1936
1937 Configuration for the web_fetch tool.
1938
1939 - `enabled: boolean`
1940
1941 - `name: "web_fetch"`
1942
1943 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
1944
1945 Permission policy for tool execution.
1946
1947 - `BetaManagedAgentsAlwaysAllowPolicy object`
1948
1949 Tool calls are automatically approved without user confirmation.
1950
1951 - `BetaManagedAgentsAlwaysAskPolicy object`
1952
1953 Tool calls require user confirmation before execution.
1954
1955 - `type: "web_fetch"`
1956
1957 - `allowed_domains: optional array of string`
1958
1959 - `blocked_domains: optional array of string`
1960
1961 - `max_content_tokens: optional number or null`
1962
1963 format: int32
1964
1965 - `BetaManagedAgentsWebSearchToolConfig object`
1966
1967 Configuration for the web_search tool.
1968
1969 - `enabled: boolean`
1970
1971 - `name: "web_search"`
1972
1973 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
1974
1975 Permission policy for tool execution.
1976
1977 - `BetaManagedAgentsAlwaysAllowPolicy object`
1978
1979 Tool calls are automatically approved without user confirmation.
1980
1981 - `BetaManagedAgentsAlwaysAskPolicy object`
1982
1983 Tool calls require user confirmation before execution.
1984
1985 - `type: "web_search"`
1986
1987 - `allowed_domains: optional array of string`
1988
1989 - `blocked_domains: optional array of string`
1990
1991 - `user_location: optional BetaManagedAgentsUserLocation or null`
1992
1993 Approximate user location for search result localization.
1994
1995 - `type: "approximate"`
1996
1997 Location precision. Only "approximate" is supported.
1998
1999 - `city: optional string or null`
2000
2001 City name.
2002
2003 minLength: 1, maxLength: 255
2004
2005 - `country: optional string or null`
2006
2007 Two-letter ISO 3166-1 country code, uppercase.
2008
2009 - `region: optional string or null`
2010
2011 Region or state name.
2012
2013 minLength: 1, maxLength: 255
2014
2015 - `timezone: optional string or null`
2016
2017 IANA timezone identifier, e.g. "America/Los_Angeles".
2018
2019 minLength: 1, maxLength: 255
2020
2021 - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig`
2022
2023 Resolved default configuration for agent tools.
2024
2025 - `enabled: boolean`
2026
2027 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
2028
2029 Permission policy for tool execution.
2030
2031 - `BetaManagedAgentsAlwaysAllowPolicy object`
2032
2033 Tool calls are automatically approved without user confirmation.
2034
2035 - `BetaManagedAgentsAlwaysAskPolicy object`
2036
2037 Tool calls require user confirmation before execution.
2038
2039 - `type: "agent_toolset_20260401"`
2040
2041 - `BetaManagedAgentsMCPToolset object`
2042
2043 - `configs: array of BetaManagedAgentsMCPToolConfig`
2044
2045 - `enabled: boolean`
2046
2047 - `name: string`
2048
2049 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
2050
2051 Permission policy for tool execution.
2052
2053 - `BetaManagedAgentsAlwaysAllowPolicy object`
2054
2055 Tool calls are automatically approved without user confirmation.
2056
2057 - `BetaManagedAgentsAlwaysAskPolicy object`
2058
2059 Tool calls require user confirmation before execution.
2060
2061 - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig`
2062
2063 Resolved default configuration for all tools from an MCP server.
2064
2065 - `enabled: boolean`
2066
2067 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
2068
2069 Permission policy for tool execution.
2070
2071 - `BetaManagedAgentsAlwaysAllowPolicy object`
2072
2073 Tool calls are automatically approved without user confirmation.
2074
2075 - `BetaManagedAgentsAlwaysAskPolicy object`
2076
2077 Tool calls require user confirmation before execution.
2078
2079 - `mcp_server_name: string`
2080
2081 - `type: "mcp_toolset"`
2082
2083 - `BetaManagedAgentsCustomTool object`
2084
2085 A custom tool as returned in API responses.
2086
2087 - `description: string`
2088
2089 - `input_schema: BetaManagedAgentsCustomToolInputSchema`
2090
2091 JSON Schema for custom tool input parameters.
2092
2093 - `type: "object"`
2094
2095 - `properties: optional map[unknown] or null`
2096
2097 - `required: optional array of string or null`
2098
2099 - `name: string`
2100
2101 - `type: "custom"`
2102
2103 - `type: "agent"`
2104
2105 - `version: number`
2106
2107 format: int32
2108
2109 - `BetaManagedAgentsAdvisor object`
2110
2111 Platform advisor roster entry: a model the session's primary thread may consult mid-turn.
2112
2113 - `model: string`
2114
2115 The advisor model id.
2116
2117 - `type: "advisor"`
2118
2119 - `type: "coordinator"`
2120
2121 - `name: string`
2122
2123 - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill`
2124
2125 - `BetaManagedAgentsAnthropicSkill object`
2126
2127 A resolved Anthropic-managed skill.
2128
2129 - `BetaManagedAgentsCustomSkill object`
2130
2131 A resolved user-created custom skill.
2132
2133 - `system: string or null`
2134
2135 - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool`
2136
2137 - `BetaManagedAgentsAgentToolset20260401 object`
2138
2139 - `BetaManagedAgentsMCPToolset object`
2140
2141 - `BetaManagedAgentsCustomTool object`
2142
2143 A custom tool as returned in API responses.
2144
2145 - `type: "agent"`
2146
2147 - `version: number`
2148
2149 format: int32
2150
2151 - `budget: optional BetaManagedAgentsBudgetLimit or null`
2152
2153 A hard spend ceiling. The session stops issuing new model requests once the tracked list cost reaches `max_list_cost`.
2154
2155 - `max_list_cost: BetaMonetaryAmount`
2156
2157 A monetary amount in a specific currency.
2158
2159 - `amount: string`
2160
2161 Amount in minor units of the currency, as an integer decimal string with no leading zeros: "2500" is $25.00 and "50" is fifty cents. A string rather than a number so no float rounding is ever applied.
2162
2163 - `currency: BetaCurrency`
2164
2165 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.
2166
2167 - `type: "limit"`
2168
2169 - `metadata: optional map[string]`
2170
2171 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.
2172
2173 - `title: optional string or null`
2174
2175 The session's new title. Present only when the update changed it.
2176
2177 - `BetaManagedAgentsSystemMessageEvent object`
2178
2179 A mid-conversation system message event. Carries system-role content that is appended to the session as a `role: "system"` turn.
2180
2181 - `id: string`
2182
2183 Unique identifier for this event.
2184
2185 - `content: array of BetaManagedAgentsSystemContentBlock`
2186
2187 System content blocks. Text-only.
2188
2189 - `text: string`
2190
2191 The text content.
2192
2193 minLength: 1
2194
2195 - `type: "text"`
2196
2197 - `type: "system.message"`
2198
2199 - `processed_at: optional string or null`
2200
2201 A timestamp in RFC 3339 format
2202
2203 format: date-time
2204
22052320 - `BetaManagedAgentsSessionUsageEvent object`
22062321
22072322 Periodic snapshot of the session's cumulative usage and tracked list cost.
22082323
2209 - `id: string`
2210
2211 Unique identifier for this event.
2212
2213 - `processed_at: string`
2214
2215 A timestamp in RFC 3339 format
2216
2217 format: date-time
2218
22192324 - `type: "session.usage"`
2325
2326 - `id: string`
2327
2328 Unique identifier for this event.
2329
2330 - `processed_at: string`
2331
2332 A timestamp in RFC 3339 format
2333
2334 format: date-time
22202335
22212336 - `usage: BetaManagedAgentsSessionUsageSnapshot`
22222337
22232338
api/beta/sessions/events/send Changed · +771 / -762 lines
from line 1
1---
2title: Send Events
3url: https://platform.claude.com/docs/en/api/beta/sessions/events/send
4---
5
16# Send Events
27
38**POST** `/v1/sessions/{session_id}/events`
from line 21
1621
1722 - `string`
1823
19 - `"message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 41 more`
24 - `"message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 42 more`
2025
2126 - `"message-batches-2024-09-24"`
2227
from line 69
6469
6570 - `"user-profiles-2026-08-18"`
6671
72 - `"user-profiles-2026-09-04"`
73
6774 - `"advisor-tool-2026-03-01"`
6875
6976 - `"managed-agents-2026-04-01"`
from line 113
106113
107114 - `"mid-conversation-system-clear-at-2026-08-21"`
108115
116- `"anthropic-workspace-id": optional string`
117
109118## Body parameters
110119
111120- `events: array of BetaManagedAgentsEventParams`
from line 125
116125
117126 Parameters for sending a user message to the session.
118127
128 - `type: "user.message"`
129
119130 - `content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsRedactedBlock`
120131
121132 Array of content blocks for the user message.
from line 135
124135
125136 Regular text content.
126137
138 - `type: "text"`
139
127140 - `text: string`
128141
129142 The text content.
from line 143
130143
131144 minLength: 1
132145
133 - `type: "text"`
134
135146 - `BetaManagedAgentsImageBlock object`
136147
137148 Image content specified directly as base64 data or as a reference via a URL.
138149
150 - `type: "image"`
151
139152 - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource`
140153
141154 Union type for image source variants.
from line 157
144157
145158 Base64-encoded image data.
146159
160 - `type: "base64"`
161
147162 - `data: string`
148163
149164 Base64-encoded image data.
from line 171
156171
157172 minLength: 1
158173
159 - `type: "base64"`
160
161174 - `BetaManagedAgentsURLImageSource object`
162175
163176 Image referenced by URL.
from line 187
174187
175188 Image referenced by file ID.
176189
190 - `type: "file"`
191
177192 - `file_id: string`
178193
179194 ID of a previously uploaded file.
from line 195
180195
181196 minLength: 1
182197
183 - `type: "file"`
184
185 - `type: "image"`
186
187198 - `BetaManagedAgentsDocumentBlock object`
188199
189200 Document content, either specified directly as base64 data, as text, or as a reference via a URL.
190201
202 - `type: "document"`
203
191204 - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource`
192205
193206 Union type for document source variants.
from line 209
196209
197210 Base64-encoded document data.
198211
212 - `type: "base64"`
213
199214 - `data: string`
200215
201216 Base64-encoded document data.
from line 223
208223
209224 minLength: 1
210225
211 - `type: "base64"`
212
213226 - `BetaManagedAgentsPlainTextDocumentSource object`
214227
215228 Plain text document content.
216229
230 - `type: "text"`
231
217232 - `data: string`
218233
219234 The plain text content.
from line 239
224239
225240 MIME type of the text content. Must be "text/plain".
226241
227 - `type: "text"`
228
229242 - `BetaManagedAgentsURLDocumentSource object`
230243
231244 Document referenced by URL.
from line 255
242255
243256 Document referenced by file ID.
244257
258 - `type: "file"`
259
245260 - `file_id: string`
246261
247262 ID of a previously uploaded file.
from line 263
248263
249264 minLength: 1
250265
251 - `type: "file"`
252
253 - `type: "document"`
254
255266 - `context: optional string or null`
256267
257268 Additional context about the document for the model.
from line 277
266277
267278 - `type: "redacted"`
268279
269 - `type: "user.message"`
270
271280 - `BetaManagedAgentsUserInterruptEventParams object`
272281
273282 Parameters for sending an interrupt to pause the agent.
from line 291
282291
283292 Parameters for confirming or denying a tool execution request.
284293
294 - `type: "user.tool_confirmation"`
295
285296 - `result: "allow" or "deny"`
286297
287298 UserToolConfirmationResult enum
from line 307
296307
297308 minLength: 1, maxLength: 128
298309
299 - `type: "user.tool_confirmation"`
300
301310 - `deny_message: optional string or null`
302311
303312 Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'.
from line 317
308317
309318 Parameters for providing the result of a custom tool execution.
310319
320 - `type: "user.custom_tool_result"`
321
311322 - `custom_tool_use_id: string`
312323
313324 The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field.
from line 325
314325
315326 minLength: 1, maxLength: 128
316327
317 - `type: "user.custom_tool_result"`
318
319328 - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock`
320329
321330 The result content returned by the tool.
from line 345
336345
337346 A block containing a web search result.
338347
348 - `type: "search_result"`
349
339350 - `citations: BetaManagedAgentsSearchResultCitations`
340351
341352 Citation settings for a search result.
from line 359
348359
349360 Array of text content blocks from the search result.
350361
362 - `type: "text"`
363
351364 - `text: string`
352365
353366 The text content.
from line 367
354367
355368 minLength: 1
356369
357 - `type: "text"`
358
359370 - `source: string`
360371
361372 The URL source of the search result.
from line 379
368379
369380 minLength: 1
370381
371 - `type: "search_result"`
372
373382 - `is_error: optional boolean or null`
374383
375384 Whether the tool execution resulted in an error.
from line 387
378387
379388 Parameters for defining an outcome the agent should work toward. The agent begins work on receipt.
380389
390 - `type: "user.define_outcome"`
391
381392 - `description: string`
382393
383394 What the agent should produce. This is the task specification.
from line 401
390401
391402 Rubric referenced by a file uploaded via the Files API.
392403
404 - `type: "file"`
405
393406 - `file_id: string`
394407
395408 ID of the rubric file.
396409
397 - `type: "file"`
398
399410 - `BetaManagedAgentsTextRubricParams object`
400411
401412 Rubric content provided inline as text.
402413
414 - `type: "text"`
415
403416 - `content: string`
404417
405418 Rubric content. Plain text or markdown — the grader treats it as freeform text. Maximum 262144 characters.
from line 419
406419
407420 maxLength: 262144
408421
409 - `type: "text"`
410
411 - `type: "user.define_outcome"`
412
413422 - `max_iterations: optional number or null`
414423
415424 Eval→revision cycles before giving up. Default 3, max 20.
from line 429
420429
421430 Parameters for 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.
422431
432 - `type: "user.tool_result"`
433
423434 - `tool_use_id: string`
424435
425436 The id of the `agent.tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field.
from line 437
426437
427438 minLength: 1, maxLength: 128
428439
429 - `type: "user.tool_result"`
430
431440 - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock`
432441
433442 The result content returned by the tool.
from line 465
456465
457466 Privileged context for the accompanying turn and all subsequent turns, appended to the session's system context as a `role: "system"` turn rather than replacing the top-level system prompt. At most one per request: it must be the final event and immediately follow the `user.message`, `user.tool_result`, or `user.custom_tool_result` it accompanies. Only supported on models that accept mid-conversation system messages.
458467
468 - `type: "system.message"`
469
459470 - `content: array of BetaManagedAgentsSystemContentBlock`
460471
461472 System content blocks to append. Text-only.
462473
474 - `type: "text"`
475
463476 - `text: string`
464477
465478 The text content.
from line 479
466479
467480 minLength: 1
468481
469 - `type: "text"`
470
471 - `type: "system.message"`
472
473482## Returns
474483
475484- `BetaManagedAgentsSendSessionEvents object`
from line 493
484493
485494 A user message event in the session conversation.
486495
496 - `type: "user.message"`
497
487498 - `id: string`
488499
489500 Unique identifier for this event.
from line 507
496507
497508 Regular text content.
498509
510 - `type: "text"`
511
499512 - `text: string`
500513
501514 The text content.
from line 515
502515
503516 minLength: 1
504517
505 - `type: "text"`
506
507518 - `BetaManagedAgentsImageBlock object`
508519
509520 Image content specified directly as base64 data or as a reference via a URL.
510521
522 - `type: "image"`
523
511524 - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource`
512525
513526 Union type for image source variants.
from line 529
516529
517530 Base64-encoded image data.
518531
532 - `type: "base64"`
533
519534 - `data: string`
520535
521536 Base64-encoded image data.
from line 543
528543
529544 minLength: 1
530545
531 - `type: "base64"`
532
533546 - `BetaManagedAgentsURLImageSource object`
534547
535548 Image referenced by URL.
from line 559
546559
547560 Image referenced by file ID.
548561
562 - `type: "file"`
563
549564 - `file_id: string`
550565
551566 ID of a previously uploaded file.
from line 567
552567
553568 minLength: 1
554569
555 - `type: "file"`
556
557 - `type: "image"`
558
559570 - `BetaManagedAgentsDocumentBlock object`
560571
561572 Document content, either specified directly as base64 data, as text, or as a reference via a URL.
562573
574 - `type: "document"`
575
563576 - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource`
564577
565578 Union type for document source variants.
from line 581
568581
569582 Base64-encoded document data.
570583
584 - `type: "base64"`
585
571586 - `data: string`
572587
573588 Base64-encoded document data.
from line 595
580595
581596 minLength: 1
582597
583 - `type: "base64"`
584
585598 - `BetaManagedAgentsPlainTextDocumentSource object`
586599
587600 Plain text document content.
588601
602 - `type: "text"`
603
589604 - `data: string`
590605
591606 The plain text content.
from line 611
596611
597612 MIME type of the text content. Must be "text/plain".
598613
599 - `type: "text"`
600
601614 - `BetaManagedAgentsURLDocumentSource object`
602615
603616 Document referenced by URL.
from line 627
614627
615628 Document referenced by file ID.
616629
630 - `type: "file"`
631
617632 - `file_id: string`
618633
619634 ID of a previously uploaded file.
from line 635
620635
621636 minLength: 1
622637
623 - `type: "file"`
624
625 - `type: "document"`
626
627638 - `context: optional string or null`
628639
629640 Additional context about the document for the model.
from line 649
638649
639650 - `type: "redacted"`
640651
641 - `type: "user.message"`
642
643652 - `processed_at: optional string or null`
644653
645654 A timestamp in RFC 3339 format
from line 659
650659
651660 An interrupt event that pauses agent execution and returns control to the user.
652661
662 - `type: "user.interrupt"`
663
653664 - `id: string`
654665
655666 Unique identifier for this event.
656667
657 - `type: "user.interrupt"`
658
659668 - `processed_at: optional string or null`
660669
661670 A timestamp in RFC 3339 format
from line 679
670679
671680 A tool confirmation event that approves or denies a pending tool execution.
672681
682 - `type: "user.tool_confirmation"`
683
673684 - `id: string`
674685
675686 Unique identifier for this event.
from line 697
686697
687698 The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field.
688699
689 - `type: "user.tool_confirmation"`
690
691700 - `deny_message: optional string or null`
692701
693702 Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'.
from line 717
708717
709718 Event sent by the client providing the result of a custom tool execution.
710719
720 - `type: "user.custom_tool_result"`
721
711722 - `id: string`
712723
713724 Unique identifier for this event.
from line 727
716727
717728 The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field.
718729
719 - `type: "user.custom_tool_result"`
720
721730 - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock`
722731
723732 The result content returned by the tool.
from line 747
738747
739748 A block containing a web search result.
740749
750 - `type: "search_result"`
751
741752 - `citations: BetaManagedAgentsSearchResultCitations`
742753
743754 Citation settings for a search result.
from line 761
750761
751762 Array of text content blocks from the search result.
752763
764 - `type: "text"`
765
753766 - `text: string`
754767
755768 The text content.
from line 769
756769
757770 minLength: 1
758771
759 - `type: "text"`
760
761772 - `source: string`
762773
763774 The URL source of the search result.
from line 781
770781
771782 minLength: 1
772783
773 - `type: "search_result"`
774
775784 - `is_error: optional boolean or null`
776785
777786 Whether the tool execution resulted in an error.
from line 799
790799
791800 Echo of a `user.define_outcome` input event. Carries the server-generated `outcome_id` that subsequent `span.outcome_evaluation_*` events reference.
792801
802 - `type: "user.define_outcome"`
803
793804 - `id: string`
794805
795806 Unique identifier for this event.
from line 833
822833
823834 Rubric referenced by a file uploaded via the Files API.
824835
836 - `type: "file"`
837
825838 - `file_id: string`
826839
827840 ID of the rubric file.
828841
829 - `type: "file"`
830
831842 - `BetaManagedAgentsTextRubric object`
832843
833844 Rubric content provided inline as text.
834845
846 - `type: "text"`
847
835848 - `content: string`
836849
837850 Rubric content. Plain text or markdown — the grader treats it as freeform text.
838851
839 - `type: "text"`
840
841 - `type: "user.define_outcome"`
842
843852 - `BetaManagedAgentsUserToolResultEvent object`
844853
845854 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.
846855
856 - `type: "user.tool_result"`
857
847858 - `id: string`
848859
849860 Unique identifier for this event.
from line 863
852863
853864 The id of the `agent.tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field.
854865
855 - `type: "user.tool_result"`
856
857866 - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock`
858867
859868 The result content returned by the tool.
from line 901
892901
893902 A mid-conversation system message event. Carries system-role content that is appended to the session as a `role: "system"` turn.
894903
904 - `type: "system.message"`
905
895906 - `id: string`
896907
897908 Unique identifier for this event.
from line 911
900911
901912 System content blocks. Text-only.
902913
914 - `type: "text"`
915
903916 - `text: string`
904917
905918 The text content.
906919
907920 minLength: 1
908
909 - `type: "text"`
910
911 - `type: "system.message"`
912921
913922 - `processed_at: optional string or null`
914923
api/beta/sessions/events/stream Changed · +2174 / -2059 lines
The two sides of this change are more than 400 edits apart, too far apart to line up, so this is the differ's own diff of it and the words inside a line are not marked.
from line 1
1---
2title: Stream Events
3url: https://platform.claude.com/docs/en/api/beta/sessions/events/stream
4---
5
16# Stream Events
27
38**GET** `/v1/sessions/{session_id}/events/stream`
from line 31
2631
2732 - `string`
2833
29 - `"message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 41 more`
34 - `"message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 42 more`
3035
3136 - `"message-batches-2024-09-24"`
3237
from line 79
7479
7580 - `"user-profiles-2026-08-18"`
7681
82 - `"user-profiles-2026-09-04"`
83
7784 - `"advisor-tool-2026-03-01"`
7885
7986 - `"managed-agents-2026-04-01"`
from line 123
116123
117124 - `"mid-conversation-system-clear-at-2026-08-21"`
118125
126- `"anthropic-workspace-id": optional string`
127
119128## Returns
120129
121130- `BetaManagedAgentsStreamSessionEvents = BetaManagedAgentsUserMessageEvent or BetaManagedAgentsUserInterruptEvent or BetaManagedAgentsUserToolConfirmationEvent or 34 more`
from line 135
126135
127136 A user message event in the session conversation.
128137
138 - `type: "user.message"`
139
129140 - `id: string`
130141
131142 Unique identifier for this event.
from line 149
138149
139150 Regular text content.
140151
152 - `type: "text"`
153
141154 - `text: string`
142155
143156 The text content.
144157
145158 minLength: 1
146159
160 - `BetaManagedAgentsImageBlock object`
161
162 Image content specified directly as base64 data or as a reference via a URL.
163
164 - `type: "image"`
165
166 - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource`
167
168 Union type for image source variants.
169
170 - `BetaManagedAgentsBase64ImageSource object`
171
172 Base64-encoded image data.
173
174 - `type: "base64"`
175
176 - `data: string`
177
178 Base64-encoded image data.
179
180 minLength: 1
181
182 - `media_type: string`
183
184 MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp").
185
186 minLength: 1
187
188 - `BetaManagedAgentsURLImageSource object`
189
190 Image referenced by URL.
191
192 - `type: "url"`
193
194 - `url: string`
195
196 URL of the image to fetch.
197
198 minLength: 1
199
200 - `BetaManagedAgentsFileImageSource object`
201
202 Image referenced by file ID.
203
204 - `type: "file"`
205
206 - `file_id: string`
207
208 ID of a previously uploaded file.
209
210 minLength: 1
211
212 - `BetaManagedAgentsDocumentBlock object`
213
214 Document content, either specified directly as base64 data, as text, or as a reference via a URL.
215
216 - `type: "document"`
217
218 - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource`
219
220 Union type for document source variants.
221
222 - `BetaManagedAgentsBase64DocumentSource object`
223
224 Base64-encoded document data.
225
226 - `type: "base64"`
227
228 - `data: string`
229
230 Base64-encoded document data.
231
232 minLength: 1
233
234 - `media_type: string`
235
236 MIME type of the document (e.g., "application/pdf").
237
238 minLength: 1
239
240 - `BetaManagedAgentsPlainTextDocumentSource object`
241
242 Plain text document content.
243
244 - `type: "text"`
245
246 - `data: string`
247
248 The plain text content.
249
250 minLength: 1
251
252 - `media_type: "text/plain"`
253
254 MIME type of the text content. Must be "text/plain".
255
256 - `BetaManagedAgentsURLDocumentSource object`
257
258 Document referenced by URL.
259
260 - `type: "url"`
261
262 - `url: string`
263
264 URL of the document to fetch.
265
266 minLength: 1
267
268 - `BetaManagedAgentsFileDocumentSource object`
269
270 Document referenced by file ID.
271
272 - `type: "file"`
273
274 - `file_id: string`
275
276 ID of a previously uploaded file.
277
278 minLength: 1
279
280 - `context: optional string or null`
281
282 Additional context about the document for the model.
283
284 - `title: optional string or null`
285
286 The title of the document.
287
288 - `BetaManagedAgentsRedactedBlock object`
289
290 Placeholder for content withheld by Anthropic model policy.
291
292 - `type: "redacted"`
293
294 - `processed_at: optional string or null`
295
296 A timestamp in RFC 3339 format
297
298 format: date-time
299
300 - `BetaManagedAgentsUserInterruptEvent object`
301
302 An interrupt event that pauses agent execution and returns control to the user.
303
304 - `type: "user.interrupt"`
305
306 - `id: string`
307
308 Unique identifier for this event.
309
310 - `processed_at: optional string or null`
311
312 A timestamp in RFC 3339 format
313
314 format: date-time
315
316 - `session_thread_id: optional string or null`
317
318 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.
319
320 - `BetaManagedAgentsUserToolConfirmationEvent object`
321
322 A tool confirmation event that approves or denies a pending tool execution.
323
324 - `type: "user.tool_confirmation"`
325
326 - `id: string`
327
328 Unique identifier for this event.
329
330 - `result: "allow" or "deny"`
331
332 UserToolConfirmationResult enum
333
334 - `"allow"`
335
336 - `"deny"`
337
338 - `tool_use_id: string`
339
340 The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field.
341
342 - `deny_message: optional string or null`
343
344 Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'.
345
346 maxLength: 10000
347
348 - `processed_at: optional string or null`
349
350 A timestamp in RFC 3339 format
351
352 format: date-time
353
354 - `session_thread_id: optional string or null`
355
356 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.
357
358 - `BetaManagedAgentsUserCustomToolResultEvent object`
359
360 Event sent by the client providing the result of a custom tool execution.
361
362 - `type: "user.custom_tool_result"`
363
364 - `id: string`
365
366 Unique identifier for this event.
367
368 - `custom_tool_use_id: string`
369
370 The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field.
371
372 - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock`
373
374 The result content returned by the tool.
375
376 - `BetaManagedAgentsTextBlock object`
377
378 Regular text content.
379
380 - `BetaManagedAgentsImageBlock object`
381
382 Image content specified directly as base64 data or as a reference via a URL.
383
384 - `BetaManagedAgentsDocumentBlock object`
385
386 Document content, either specified directly as base64 data, as text, or as a reference via a URL.
387
388 - `BetaManagedAgentsSearchResultBlock object`
389
390 A block containing a web search result.
391
392 - `type: "search_result"`
393
394 - `citations: BetaManagedAgentsSearchResultCitations`
395
396 Citation settings for a search result.
397
398 - `enabled: boolean`
399
400 Whether citations are enabled for this search result.
401
402 - `content: array of BetaManagedAgentsSearchResultContent`
403
404 Array of text content blocks from the search result.
405
406 - `type: "text"`
407
408 - `text: string`
409
410 The text content.
411
412 minLength: 1
413
414 - `source: string`
415
416 The URL source of the search result.
417
418 minLength: 1
419
420 - `title: string`
421
422 The title of the search result.
423
424 minLength: 1
425
426 - `is_error: optional boolean or null`
427
428 Whether the tool execution resulted in an error.
429
430 - `processed_at: optional string or null`
431
432 A timestamp in RFC 3339 format
433
434 format: date-time
435
436 - `session_thread_id: optional string or null`
437
438 Routes this result to a subagent thread. Copy from the `agent.custom_tool_use` event's `session_thread_id`.
439
440 - `BetaManagedAgentsAgentCustomToolUseEvent object`
441
442 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.
443
444 - `type: "agent.custom_tool_use"`
445
446 - `id: string`
447
448 Unique identifier for this event.
449
450 - `input: map[unknown]`
451
452 Input parameters for the tool call.
453
454 - `name: string`
455
456 Name of the custom tool being called.
457
458 - `processed_at: string`
459
460 A timestamp in RFC 3339 format
461
462 format: date-time
463
464 - `session_thread_id: optional string or null`
465
466 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.
467
468 - `BetaManagedAgentsAgentMessageEvent object`
469
470 An agent response event in the session conversation.
471
472 - `type: "agent.message"`
473
474 - `id: string`
475
476 Unique identifier for this event.
477
478 - `content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsRedactedBlock`
479
480 Array of text blocks comprising the agent response.
481
482 - `BetaManagedAgentsTextBlock object`
483
484 Regular text content.
485
486 - `BetaManagedAgentsRedactedBlock object`
487
488 Placeholder for content withheld by Anthropic model policy.
489
490 - `processed_at: string`
491
492 A timestamp in RFC 3339 format
493
494 format: date-time
495
496 - `BetaManagedAgentsAgentThinkingEvent object`
497
498 Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier.
499
500 - `type: "agent.thinking"`
501
502 - `id: string`
503
504 Unique identifier for this event.
505
506 - `processed_at: string`
507
508 A timestamp in RFC 3339 format
509
510 format: date-time
511
512 - `BetaManagedAgentsAgentMCPToolUseEvent object`
513
514 Event emitted when the agent invokes a tool provided by an MCP server.
515
516 - `type: "agent.mcp_tool_use"`
517
518 - `id: string`
519
520 Unique identifier for this event.
521
522 - `input: map[unknown]`
523
524 Input parameters for the tool call.
525
526 - `mcp_server_name: string`
527
528 Name of the MCP server providing the tool.
529
530 - `name: string`
531
532 Name of the MCP tool being used.
533
534 - `processed_at: string`
535
536 A timestamp in RFC 3339 format
537
538 format: date-time
539
540 - `evaluated_permission: optional "allow" or "ask" or "deny"`
541
542 AgentEvaluatedPermission enum
543
544 - `"allow"`
545
546 - `"ask"`
547
548 - `"deny"`
549
550 - `evaluation: optional BetaManagedAgentsAgentToolEvaluation`
551
552 Names the resolved permission_policy that produced evaluated_permission, and under auto carries the judgement. Open union: clients must tolerate unknown variants.
553
554 - `BetaManagedAgentsAgentToolEvaluationAlwaysAllow object`
555
556 The resolved permission_policy was always_allow; accompanies evaluated_permission "allow".
557
558 - `type: "always_allow"`
559
560 - `BetaManagedAgentsAgentToolEvaluationAlwaysAsk object`
561
562 The resolved permission_policy was always_ask; accompanies evaluated_permission "ask".
563
564 - `type: "always_ask"`
565
566 - `BetaManagedAgentsAgentToolEvaluationAuto object`
567
568 The resolved permission_policy was auto: the server judged this invocation individually.
569
570 - `type: "auto"`
571
572 - `evaluated_permission: BetaManagedAgentsAgentAutoEvaluatedPermission`
573
574 The server's per-invocation judgement under the auto permission policy. Its type always equals the event's top-level evaluated_permission. Open union: clients must tolerate unknown variants.
575
576 - `BetaManagedAgentsAgentAutoEvaluatedPermissionAllow object`
577
578 The server judged the invocation safe to execute without client approval.
579
580 - `type: "allow"`
581
582 - `BetaManagedAgentsAgentAutoEvaluatedPermissionAsk object`
583
584 The server reached no judgement; the invocation is held for client approval.
585
586 - `type: "ask"`
587
588 - `reason_code: string`
589
590 The judgement's grounds in registry-bound terms, for client branching and audit rather than end-user display. Open registry; currently "indeterminate" (no judgement was reached). Clients must tolerate values outside this set.
591
592 maxLength: 64
593
594 - `BetaManagedAgentsAgentAutoEvaluatedPermissionDeny object`
595
596 The server judged the invocation high-risk; it does not execute and a synthetic error tool result is appended.
597
598 - `type: "deny"`
599
600 - `reason_code: string`
601
602 The judgement's grounds in registry-bound terms. Open registry; currently "high_risk" (judged high-risk; the call does not run). Clients must tolerate values outside this set.
603
604 maxLength: 64
605
606 - `session_thread_id: optional string or null`
607
608 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.
609
610 - `BetaManagedAgentsAgentMCPToolResultEvent object`
611
612 Event representing the result of an MCP tool execution.
613
614 - `type: "agent.mcp_tool_result"`
615
616 - `id: string`
617
618 Unique identifier for this event.
619
620 - `mcp_tool_use_id: string`
621
622 The id of the `agent.mcp_tool_use` event this result corresponds to.
623
624 - `processed_at: string`
625
626 A timestamp in RFC 3339 format
627
628 format: date-time
629
630 - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock`
631
632 The result content returned by the tool.
633
634 - `BetaManagedAgentsTextBlock object`
635
636 Regular text content.
637
638 - `BetaManagedAgentsImageBlock object`
639
640 Image content specified directly as base64 data or as a reference via a URL.
641
642 - `BetaManagedAgentsDocumentBlock object`
643
644 Document content, either specified directly as base64 data, as text, or as a reference via a URL.
645
646 - `BetaManagedAgentsSearchResultBlock object`
647
648 A block containing a web search result.
649
650 - `is_error: optional boolean or null`
651
652 Whether the tool execution resulted in an error.
653
654 - `BetaManagedAgentsAgentToolUseEvent object`
655
656 Event emitted when the agent invokes a built-in agent tool.
657
658 - `type: "agent.tool_use"`
659
660 - `id: string`
661
662 Unique identifier for this event.
663
664 - `input: map[unknown]`
665
666 Input parameters for the tool call.
667
668 - `name: string`
669
670 Name of the agent tool being used.
671
672 - `processed_at: string`
673
674 A timestamp in RFC 3339 format
675
676 format: date-time
677
678 - `evaluated_permission: optional "allow" or "ask" or "deny"`
679
680 AgentEvaluatedPermission enum
681
682 - `"allow"`
683
684 - `"ask"`
685
686 - `"deny"`
687
688 - `evaluation: optional BetaManagedAgentsAgentToolEvaluation`
689
690 Names the resolved permission_policy that produced evaluated_permission, and under auto carries the judgement. Open union: clients must tolerate unknown variants.
691
692 - `session_thread_id: optional string or null`
693
694 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.
695
696 - `BetaManagedAgentsAgentToolResultEvent object`
697
698 Event representing the result of an agent tool execution.
699
700 - `type: "agent.tool_result"`
701
702 - `id: string`
703
704 Unique identifier for this event.
705
706 - `processed_at: string`
707
708 A timestamp in RFC 3339 format
709
710 format: date-time
711
712 - `tool_use_id: string`
713
714 The id of the `agent.tool_use` event this result corresponds to.
715
716 - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock`
717
718 The result content returned by the tool.
719
720 - `BetaManagedAgentsTextBlock object`
721
722 Regular text content.
723
724 - `BetaManagedAgentsImageBlock object`
725
726 Image content specified directly as base64 data or as a reference via a URL.
727
728 - `BetaManagedAgentsDocumentBlock object`
729
730 Document content, either specified directly as base64 data, as text, or as a reference via a URL.
731
732 - `BetaManagedAgentsSearchResultBlock object`
733
734 A block containing a web search result.
735
736 - `is_error: optional boolean or null`
737
738 Whether the tool execution resulted in an error.
739
740 - `BetaManagedAgentsAgentThreadMessageReceivedEvent object`
741
742 Delivery event written to the target thread's input stream when an agent-to-agent message arrives.
743
744 - `type: "agent.thread_message_received"`
745
746 - `id: string`
747
748 Unique identifier for this event.
749
750 - `content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsRedactedBlock`
751
752 Message content blocks.
753
754 - `BetaManagedAgentsTextBlock object`
755
756 Regular text content.
757
758 - `BetaManagedAgentsImageBlock object`
759
760 Image content specified directly as base64 data or as a reference via a URL.
761
762 - `BetaManagedAgentsDocumentBlock object`
763
764 Document content, either specified directly as base64 data, as text, or as a reference via a URL.
765
766 - `BetaManagedAgentsRedactedBlock object`
767
768 Placeholder for content withheld by Anthropic model policy.
769
770 - `from_session_thread_id: string`
771
772 Public `sthr_` ID of the thread that sent the message.
773
774 - `processed_at: string`
775
776 A timestamp in RFC 3339 format
777
778 format: date-time
779
780 - `from_agent_name: optional string or null`
781
782 Name of the callable agent this message came from. Absent when received from the primary agent.
783
784 - `BetaManagedAgentsAgentThreadMessageSentEvent object`
785
786 Observability event emitted to the sender's output stream when an agent-to-agent message is sent.
787
788 - `type: "agent.thread_message_sent"`
789
790 - `id: string`
791
792 Unique identifier for this event.
793
794 - `content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsRedactedBlock`
795
796 Message content blocks.
797
798 - `BetaManagedAgentsTextBlock object`
799
800 Regular text content.
801
802 - `BetaManagedAgentsImageBlock object`
803
804 Image content specified directly as base64 data or as a reference via a URL.
805
806 - `BetaManagedAgentsDocumentBlock object`
807
808 Document content, either specified directly as base64 data, as text, or as a reference via a URL.
809
810 - `BetaManagedAgentsRedactedBlock object`
811
812 Placeholder for content withheld by Anthropic model policy.
813
814 - `processed_at: string`
815
816 A timestamp in RFC 3339 format
817
818 format: date-time
819
820 - `to_session_thread_id: string`
821
822 Public `sthr_` ID of the thread the message was sent to.
823
824 - `to_agent_name: optional string or null`
825
826 Name of the callable agent this message was sent to. Absent when sent to the primary agent.
827
828 - `BetaManagedAgentsAgentThreadContextCompactedEvent object`
829
830 Indicates that context compaction (summarization) occurred during the session.
831
832 - `type: "agent.thread_context_compacted"`
833
834 - `id: string`
835
836 Unique identifier for this event.
837
838 - `processed_at: string`
839
840 A timestamp in RFC 3339 format
841
842 format: date-time
843
844 - `BetaManagedAgentsSessionErrorEvent object`
845
846 An error event indicating a problem occurred during session execution.
847
848 - `type: "session.error"`
849
850 - `id: string`
851
852 Unique identifier for this event.
853
854 - `error: BetaManagedAgentsUnknownError or BetaManagedAgentsModelOverloadedError or BetaManagedAgentsModelRateLimitedError or 5 more`
855
856 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.
857
858 - `BetaManagedAgentsUnknownError object`
859
860 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.
861
862 - `type: "unknown_error"`
863
864 - `message: string`
865
866 Human-readable error description.
867
868 - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal`
869
870 What the client should do next in response to this error.
871
872 - `BetaManagedAgentsRetryStatusRetrying object`
873
874 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.
875
876 - `type: "retrying"`
877
878 - `BetaManagedAgentsRetryStatusExhausted object`
879
880 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
881
882 - `type: "exhausted"`
883
884 - `BetaManagedAgentsRetryStatusTerminal object`
885
886 The session encountered a terminal error and will transition to `terminated` state.
887
888 - `type: "terminal"`
889
890 - `BetaManagedAgentsModelOverloadedError object`
891
892 The model is currently overloaded. Emitted after automatic retries are exhausted.
893
894 - `type: "model_overloaded_error"`
895
896 - `message: string`
897
898 Human-readable error description.
899
900 - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal`
901
902 What the client should do next in response to this error.
903
904 - `BetaManagedAgentsRetryStatusRetrying object`
905
906 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.
907
908 - `BetaManagedAgentsRetryStatusExhausted object`
909
910 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
911
912 - `BetaManagedAgentsRetryStatusTerminal object`
913
914 The session encountered a terminal error and will transition to `terminated` state.
915
916 - `BetaManagedAgentsModelRateLimitedError object`
917
918 The model request was rate-limited.
919
920 - `type: "model_rate_limited_error"`
921
922 - `message: string`
923
924 Human-readable error description.
925
926 - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal`
927
928 What the client should do next in response to this error.
929
930 - `BetaManagedAgentsRetryStatusRetrying object`
931
932 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.
933
934 - `BetaManagedAgentsRetryStatusExhausted object`
935
936 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
937
938 - `BetaManagedAgentsRetryStatusTerminal object`
939
940 The session encountered a terminal error and will transition to `terminated` state.
941
942 - `BetaManagedAgentsModelRequestFailedError object`
943
944 A model request failed for a reason other than overload or rate-limiting.
945
946 - `type: "model_request_failed_error"`
947
948 - `message: string`
949
950 Human-readable error description.
951
952 - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal`
953
954 What the client should do next in response to this error.
955
956 - `BetaManagedAgentsRetryStatusRetrying object`
957
958 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.
959
960 - `BetaManagedAgentsRetryStatusExhausted object`
961
962 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
963
964 - `BetaManagedAgentsRetryStatusTerminal object`
965
966 The session encountered a terminal error and will transition to `terminated` state.
967
968 - `BetaManagedAgentsMCPConnectionFailedError object`
969
970 Failed to connect to an MCP server.
971
972 - `type: "mcp_connection_failed_error"`
973
974 - `mcp_server_name: string`
975
976 Name of the MCP server that failed to connect.
977
978 - `message: string`
979
980 Human-readable error description.
981
982 - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal`
983
984 What the client should do next in response to this error.
985
986 - `BetaManagedAgentsRetryStatusRetrying object`
987
988 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.
989
990 - `BetaManagedAgentsRetryStatusExhausted object`
991
992 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
993
994 - `BetaManagedAgentsRetryStatusTerminal object`
995
996 The session encountered a terminal error and will transition to `terminated` state.
997
998 - `BetaManagedAgentsMCPAuthenticationFailedError object`
999
1000 Authentication to an MCP server failed.
1001
1002 - `type: "mcp_authentication_failed_error"`
1003
1004 - `mcp_server_name: string`
1005
1006 Name of the MCP server that failed authentication.
1007
1008 - `message: string`
1009
1010 Human-readable error description.
1011
1012 - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal`
1013
1014 What the client should do next in response to this error.
1015
1016 - `BetaManagedAgentsRetryStatusRetrying object`
1017
1018 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.
1019
1020 - `BetaManagedAgentsRetryStatusExhausted object`
1021
1022 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
1023
1024 - `BetaManagedAgentsRetryStatusTerminal object`
1025
1026 The session encountered a terminal error and will transition to `terminated` state.
1027
1028 - `BetaManagedAgentsBillingError object`
1029
1030 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.
1031
1032 - `type: "billing_error"`
1033
1034 - `message: string`
1035
1036 Human-readable error description.
1037
1038 - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal`
1039
1040 What the client should do next in response to this error.
1041
1042 - `BetaManagedAgentsRetryStatusRetrying object`
1043
1044 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.
1045
1046 - `BetaManagedAgentsRetryStatusExhausted object`
1047
1048 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
1049
1050 - `BetaManagedAgentsRetryStatusTerminal object`
1051
1052 The session encountered a terminal error and will transition to `terminated` state.
1053
1054 - `BetaManagedAgentsCredentialHostUnreachableError object`
1055
1056 An `environment_variable` credential's `auth.networking.allowed_hosts` includes a host the environment's network policy does not permit.
1057
1058 - `type: "credential_host_unreachable_error"`
1059
1060 - `credential_id: string`
1061
1062 ID of the affected credential.
1063
1064 - `message: string`
1065
1066 Human-readable error description.
1067
1068 - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal`
1069
1070 What the client should do next in response to this error.
1071
1072 - `BetaManagedAgentsRetryStatusRetrying object`
1073
1074 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.
1075
1076 - `BetaManagedAgentsRetryStatusExhausted object`
1077
1078 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
1079
1080 - `BetaManagedAgentsRetryStatusTerminal object`
1081
1082 The session encountered a terminal error and will transition to `terminated` state.
1083
1084 - `vault_id: string`
1085
1086 ID of the vault containing the affected credential.
1087
1088 - `processed_at: string`
1089
1090 A timestamp in RFC 3339 format
1091
1092 format: date-time
1093
1094 - `BetaManagedAgentsSessionStatusRescheduledEvent object`
1095
1096 Indicates the session is recovering from an error state and is rescheduled for execution.
1097
1098 - `type: "session.status_rescheduled"`
1099
1100 - `id: string`
1101
1102 Unique identifier for this event.
1103
1104 - `processed_at: string`
1105
1106 A timestamp in RFC 3339 format
1107
1108 format: date-time
1109
1110 - `BetaManagedAgentsSessionStatusRunningEvent object`
1111
1112 Indicates the session is actively running and the agent is working.
1113
1114 - `type: "session.status_running"`
1115
1116 - `id: string`
1117
1118 Unique identifier for this event.
1119
1120 - `processed_at: string`
1121
1122 A timestamp in RFC 3339 format
1123
1124 format: date-time
1125
1126 - `BetaManagedAgentsSessionStatusIdleEvent object`
1127
1128 Indicates the agent has paused and is awaiting user input.
1129
1130 - `type: "session.status_idle"`
1131
1132 - `id: string`
1133
1134 Unique identifier for this event.
1135
1136 - `processed_at: string`
1137
1138 A timestamp in RFC 3339 format
1139
1140 format: date-time
1141
1142 - `stop_reason: BetaManagedAgentsSessionEndTurn or BetaManagedAgentsSessionRequiresAction or BetaManagedAgentsSessionRetriesExhausted or BetaManagedAgentsSessionBudgetReached`
1143
1144 The agent completed its turn naturally and is ready for the next user message.
1145
1146 - `BetaManagedAgentsSessionEndTurn object`
1147
1148 The agent completed its turn naturally and is ready for the next user message.
1149
1150 - `type: "end_turn"`
1151
1152 - `BetaManagedAgentsSessionRequiresAction object`
1153
1154 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.
1155
1156 - `type: "requires_action"`
1157
1158 - `event_ids: array of string`
1159
1160 The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder.
1161
1162 - `BetaManagedAgentsSessionRetriesExhausted object`
1163
1164 The turn ended because repeated errors exhausted the retry budget or an error escalated to `retry_status: 'exhausted'`.
1165
1166 - `type: "retries_exhausted"`
1167
1168 - `BetaManagedAgentsSessionBudgetReached object`
1169
1170 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.
1171
1172 - `type: "budget_reached"`
1173
1174 - `BetaManagedAgentsSessionStatusTerminatedEvent object`
1175
1176 Indicates the session has terminated, either due to an error or completion.
1177
1178 - `type: "session.status_terminated"`
1179
1180 - `id: string`
1181
1182 Unique identifier for this event.
1183
1184 - `processed_at: string`
1185
1186 A timestamp in RFC 3339 format
1187
1188 format: date-time
1189
1190 - `BetaManagedAgentsSessionThreadCreatedEvent object`
1191
1192 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.
1193
1194 - `type: "session.thread_created"`
1195
1196 - `id: string`
1197
1198 Unique identifier for this event.
1199
1200 - `agent_name: string`
1201
1202 Name of the callable agent the thread runs.
1203
1204 - `processed_at: string`
1205
1206 A timestamp in RFC 3339 format
1207
1208 format: date-time
1209
1210 - `session_thread_id: string`
1211
1212 Public `sthr_` ID of the newly created thread.
1213
1214 - `BetaManagedAgentsSpanOutcomeEvaluationStartEvent object`
1215
1216 Emitted when an outcome evaluation cycle begins.
1217
1218 - `type: "span.outcome_evaluation_start"`
1219
1220 - `id: string`
1221
1222 Unique identifier for this event.
1223
1224 - `iteration: number`
1225
1226 0-indexed revision cycle. 0 is the first evaluation; 1 is the re-evaluation after the first revision; etc.
1227
1228 format: int32
1229
1230 - `outcome_id: string`
1231
1232 The `outc_` ID of the outcome being evaluated.
1233
1234 - `processed_at: string`
1235
1236 A timestamp in RFC 3339 format
1237
1238 format: date-time
1239
1240 - `BetaManagedAgentsSpanOutcomeEvaluationEndEvent object`
1241
1242 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.
1243
1244 - `type: "span.outcome_evaluation_end"`
1245
1246 - `id: string`
1247
1248 Unique identifier for this event.
1249
1250 - `explanation: string`
1251
1252 Human-readable explanation of the verdict. For `needs_revision`, describes which criteria failed and why.
1253
1254 - `iteration: number`
1255
1256 0-indexed revision cycle, matching the corresponding `span.outcome_evaluation_start`.
1257
1258 format: int32
1259
1260 - `outcome_evaluation_start_id: string`
1261
1262 The id of the corresponding `span.outcome_evaluation_start` event.
1263
1264 - `outcome_id: string`
1265
1266 The `outc_` ID of the outcome being evaluated.
1267
1268 - `processed_at: string`
1269
1270 A timestamp in RFC 3339 format
1271
1272 format: date-time
1273
1274 - `result: string`
1275
1276 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.
1277
1278 - `usage: BetaManagedAgentsSpanModelUsage`
1279
1280 Token usage for a single model request.
1281
1282 - `cache_creation_input_tokens: number`
1283
1284 Tokens used to create prompt cache in this request.
1285
1286 format: int32
1287
1288 - `cache_read_input_tokens: number`
1289
1290 Tokens read from prompt cache in this request.
1291
1292 format: int32
1293
1294 - `input_tokens: number`
1295
1296 Input tokens consumed by this request.
1297
1298 format: int32
1299
1300 - `output_tokens: number`
1301
1302 Output tokens generated by this request.
1303
1304 format: int32
1305
1306 - `speed: optional "standard" or "fast" or null`
1307
1308 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.
1309
1310 - `"standard"`
1311
1312 - `"fast"`
1313
1314 - `BetaManagedAgentsSpanModelRequestStartEvent object`
1315
1316 Emitted when a model request is initiated by the agent.
1317
1318 - `type: "span.model_request_start"`
1319
1320 - `id: string`
1321
1322 Unique identifier for this event.
1323
1324 - `processed_at: string`
1325
1326 A timestamp in RFC 3339 format
1327
1328 format: date-time
1329
1330 - `BetaManagedAgentsSpanModelRequestEndEvent object`
1331
1332 Emitted when a model request completes.
1333
1334 - `type: "span.model_request_end"`
1335
1336 - `id: string`
1337
1338 Unique identifier for this event.
1339
1340 - `is_error: boolean or null`
1341
1342 Whether the model request resulted in an error.
1343
1344 - `model_request_start_id: string`
1345
1346 The id of the corresponding `span.model_request_start` event.
1347
1348 - `model_usage: BetaManagedAgentsSpanModelUsage`
1349
1350 Token usage for a single model request.
1351
1352 - `processed_at: string`
1353
1354 A timestamp in RFC 3339 format
1355
1356 format: date-time
1357
1358 - `BetaManagedAgentsSpanOutcomeEvaluationOngoingEvent object`
1359
1360 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.
1361
1362 - `type: "span.outcome_evaluation_ongoing"`
1363
1364 - `id: string`
1365
1366 Unique identifier for this event.
1367
1368 - `iteration: number`
1369
1370 0-indexed revision cycle, matching the corresponding `span.outcome_evaluation_start`.
1371
1372 format: int32
1373
1374 - `outcome_id: string`
1375
1376 The `outc_` ID of the outcome being evaluated.
1377
1378 - `processed_at: string`
1379
1380 A timestamp in RFC 3339 format
1381
1382 format: date-time
1383
1384 - `BetaManagedAgentsUserDefineOutcomeEvent object`
1385
1386 Echo of a `user.define_outcome` input event. Carries the server-generated `outcome_id` that subsequent `span.outcome_evaluation_*` events reference.
1387
1388 - `type: "user.define_outcome"`
1389
1390 - `id: string`
1391
1392 Unique identifier for this event.
1393
1394 - `description: string`
1395
1396 What the agent should produce. Copied from the input event.
1397
1398 - `max_iterations: number or null`
1399
1400 Evaluate-then-revise cycles before giving up. Default 3, max 20.
1401
1402 format: int32
1403
1404 - `outcome_id: string`
1405
1406 Server-generated `outc_` ID for this outcome. Referenced by `span.outcome_evaluation_*` events and the session's `outcome_evaluations` list.
1407
1408 - `processed_at: string`
1409
1410 A timestamp in RFC 3339 format
1411
1412 format: date-time
1413
1414 - `rubric: BetaManagedAgentsFileRubric or BetaManagedAgentsTextRubric`
1415
1416 Rubric for grading the quality of an outcome.
1417
1418 - `BetaManagedAgentsFileRubric object`
1419
1420 Rubric referenced by a file uploaded via the Files API.
1421
1422 - `type: "file"`
1423
1424 - `file_id: string`
1425
1426 ID of the rubric file.
1427
1428 - `BetaManagedAgentsTextRubric object`
1429
1430 Rubric content provided inline as text.
1431
1471432 - `type: "text"`
1481433
1434 - `content: string`
1435
1436 Rubric content. Plain text or markdown — the grader treats it as freeform text.
1437
1438 - `BetaManagedAgentsSessionDeletedEvent object`
1439
1440 Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session.
1441
1442 - `type: "session.deleted"`
1443
1444 - `id: string`
1445
1446 Unique identifier for this event.
1447
1448 - `processed_at: string`
1449
1450 A timestamp in RFC 3339 format
1451
1452 format: date-time
1453
1454 - `BetaManagedAgentsSessionThreadStatusRunningEvent object`
1455
1456 A session thread has begun executing. Emitted on the thread's own stream and cross-posted to the primary stream for child threads.
1457
1458 - `type: "session.thread_status_running"`
1459
1460 - `id: string`
1461
1462 Unique identifier for this event.
1463
1464 - `agent_name: string`
1465
1466 Name of the agent the thread runs.
1467
1468 - `processed_at: string`
1469
1470 A timestamp in RFC 3339 format
1471
1472 format: date-time
1473
1474 - `session_thread_id: string`
1475
1476 Public sthr_ ID of the thread that started running.
1477
1478 - `BetaManagedAgentsSessionThreadStatusIdleEvent object`
1479
1480 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.
1481
1482 - `type: "session.thread_status_idle"`
1483
1484 - `id: string`
1485
1486 Unique identifier for this event.
1487
1488 - `agent_name: string`
1489
1490 Name of the agent the thread runs.
1491
1492 - `processed_at: string`
1493
1494 A timestamp in RFC 3339 format
1495
1496 format: date-time
1497
1498 - `session_thread_id: string`
1499
1500 Public sthr_ ID of the thread that went idle.
1501
1502 - `stop_reason: BetaManagedAgentsSessionEndTurn or BetaManagedAgentsSessionRequiresAction or BetaManagedAgentsSessionRetriesExhausted or BetaManagedAgentsSessionBudgetReached`
1503
1504 The agent completed its turn naturally and is ready for the next user message.
1505
1506 - `BetaManagedAgentsSessionEndTurn object`
1507
1508 The agent completed its turn naturally and is ready for the next user message.
1509
1510 - `BetaManagedAgentsSessionRequiresAction object`
1511
1512 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.
1513
1514 - `BetaManagedAgentsSessionRetriesExhausted object`
1515
1516 The turn ended because repeated errors exhausted the retry budget or an error escalated to `retry_status: 'exhausted'`.
1517
1518 - `BetaManagedAgentsSessionBudgetReached object`
1519
1520 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.
1521
1522 - `BetaManagedAgentsSessionThreadStatusTerminatedEvent object`
1523
1524 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.
1525
1526 - `type: "session.thread_status_terminated"`
1527
1528 - `id: string`
1529
1530 Unique identifier for this event.
1531
1532 - `agent_name: string`
1533
1534 Name of the agent the thread runs.
1535
1536 - `processed_at: string`
1537
1538 A timestamp in RFC 3339 format
1539
1540 format: date-time
1541
1542 - `session_thread_id: string`
1543
1544 Public sthr_ ID of the thread that terminated.
1545
1546 - `BetaManagedAgentsUserToolResultEvent object`
1547
1548 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.
1549
1550 - `type: "user.tool_result"`
1551
1552 - `id: string`
1553
1554 Unique identifier for this event.
1555
1556 - `tool_use_id: string`
1557
1558 The id of the `agent.tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field.
1559
1560 - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock`
1561
1562 The result content returned by the tool.
1563
1564 - `BetaManagedAgentsTextBlock object`
1565
1566 Regular text content.
1567
1491568 - `BetaManagedAgentsImageBlock object`
1501569
1511570 Image content specified directly as base64 data or as a reference via a URL.
1521571
153 - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource`
154
155 Union type for image source variants.
156
157 - `BetaManagedAgentsBase64ImageSource object`
158
159 Base64-encoded image data.
160
161 - `data: string`
162
163 Base64-encoded image data.
164
165 minLength: 1
166
167 - `media_type: string`
168
169 MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp").
170
171 minLength: 1
172
173 - `type: "base64"`
174
175 - `BetaManagedAgentsURLImageSource object`
176
177 Image referenced by URL.
178
179 - `type: "url"`
180
181 - `url: string`
182
183 URL of the image to fetch.
184
185 minLength: 1
186
187 - `BetaManagedAgentsFileImageSource object`
188
189 Image referenced by file ID.
190
191 - `file_id: string`
192
193 ID of a previously uploaded file.
194
195 minLength: 1
196
197 - `type: "file"`
198
199 - `type: "image"`
200
2011572 - `BetaManagedAgentsDocumentBlock object`
2021573
2031574 Document content, either specified directly as base64 data, as text, or as a reference via a URL.
2041575
205 - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource`
206
207 Union type for document source variants.
208
209 - `BetaManagedAgentsBase64DocumentSource object`
210
211 Base64-encoded document data.
212
213 - `data: string`
214
215 Base64-encoded document data.
216
217 minLength: 1
218
219 - `media_type: string`
220
221 MIME type of the document (e.g., "application/pdf").
222
223 minLength: 1
224
225 - `type: "base64"`
226
227 - `BetaManagedAgentsPlainTextDocumentSource object`
228
229 Plain text document content.
230
231 - `data: string`
232
233 The plain text content.
234
235 minLength: 1
236
237 - `media_type: "text/plain"`
238
239 MIME type of the text content. Must be "text/plain".
240
241 - `type: "text"`
242
243 - `BetaManagedAgentsURLDocumentSource object`
244
245 Document referenced by URL.
246
247 - `type: "url"`
248
249 - `url: string`
250
251 URL of the document to fetch.
252
253 minLength: 1
254
255 - `BetaManagedAgentsFileDocumentSource object`
256
257 Document referenced by file ID.
258
259 - `file_id: string`
260
261 ID of a previously uploaded file.
262
263 minLength: 1
264
265 - `type: "file"`
266
267 - `type: "document"`
268
269 - `context: optional string or null`
270
271 Additional context about the document for the model.
272
273 - `title: optional string or null`
274
275 The title of the document.
276
277 - `BetaManagedAgentsRedactedBlock object`
278
279 Placeholder for content withheld by Anthropic model policy.
280
281 - `type: "redacted"`
282
283 - `type: "user.message"`
1576 - `BetaManagedAgentsSearchResultBlock object`
1577
1578 A block containing a web search result.
1579
1580 - `is_error: optional boolean or null`
1581
1582 Whether the tool execution resulted in an error.
2841583
2851584 - `processed_at: optional string or null`
2861585
from line 1587
2881587
2891588 format: date-time
2901589
291 - `BetaManagedAgentsUserInterruptEvent object`
292
293 An interrupt event that pauses agent execution and returns control to the user.
294
295 - `id: string`
296
297 Unique identifier for this event.
298
299 - `type: "user.interrupt"`
1590 - `session_thread_id: optional string or null`
1591
1592 Routes this result to a subagent thread. Copy from the `agent.tool_use` event's `session_thread_id`.
1593
1594 - `BetaManagedAgentsSessionThreadStatusRescheduledEvent object`
1595
1596 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.
1597
1598 - `type: "session.thread_status_rescheduled"`
1599
1600 - `id: string`
1601
1602 Unique identifier for this event.
1603
1604 - `agent_name: string`
1605
1606 Name of the agent the thread runs.
1607
1608 - `processed_at: string`
1609
1610 A timestamp in RFC 3339 format
1611
1612 format: date-time
1613
1614 - `session_thread_id: string`
1615
1616 Public sthr_ ID of the thread that is retrying.
1617
1618 - `BetaManagedAgentsSessionUpdatedEvent object`
1619
1620 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.
1621
1622 - `type: "session.updated"`
1623
1624 - `id: string`
1625
1626 Unique identifier for this event.
1627
1628 - `processed_at: string`
1629
1630 A timestamp in RFC 3339 format
1631
1632 format: date-time
1633
1634 - `agent: optional BetaManagedAgentsSessionAgent or null`
1635
1636 Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time.
1637
1638 - `type: "agent"`
1639
1640 - `id: string`
1641
1642 - `description: string or null`
1643
1644 - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition`
1645
1646 - `type: "url"`
1647
1648 - `name: string`
1649
1650 - `url: string`
1651
1652 - `model: BetaManagedAgentsModelConfig`
1653
1654 Model identifier and configuration.
1655
1656 - `id: BetaManagedAgentsModel`
1657
1658 The model that will power your agent.
1659
1660 See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options.
1661
1662 - `"claude-fable-5-1" or "claude-sonnet-5" or "claude-fable-5" or 11 more`
1663
1664 The model that will power your agent.
1665
1666 See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options.
1667
1668 - `"claude-fable-5-1"`
1669
1670 Frontier intelligence for ambitious tasks across coding, scientific discovery, and enterprise workflows
1671
1672 - `"claude-sonnet-5"`
1673
1674 High-performance model for coding and agents
1675
1676 - `"claude-fable-5"`
1677
1678 Next generation of intelligence for the hardest knowledge work and coding problems
1679
1680 - `"claude-opus-5"`
1681
1682 Powerful intelligence for long-running agents and coding
1683
1684 - `"claude-opus-4-8"`
1685
1686 Powerful intelligence for long-running agents and coding
1687
1688 - `"claude-opus-4-7"`
1689
1690 Powerful intelligence for long-running agents and coding
1691
1692 - `"claude-opus-4-6"`
1693
1694 Powerful intelligence for long-running agents and coding
1695
1696 - `"claude-sonnet-4-6"`
1697
1698 Best combination of speed and intelligence
1699
1700 - `"claude-haiku-4-5"`
1701
1702 Fastest model with near-frontier intelligence
1703
1704 - `"claude-haiku-4-5-20251001"`
1705
1706 Fastest model with near-frontier intelligence
1707
1708 - `"claude-opus-4-5"`
1709
1710 Powerful intelligence for long-running agents and coding
1711
1712 - `"claude-opus-4-5-20251101"`
1713
1714 Powerful intelligence for long-running agents and coding
1715
1716 - `"claude-sonnet-4-5"`
1717
1718 High-performance model for agents and coding
1719
1720 - `"claude-sonnet-4-5-20250929"`
1721
1722 High-performance model for agents and coding
1723
1724 - `string`
1725
1726 - `effort: optional BetaManagedAgentsEffortLow or BetaManagedAgentsEffortMedium or BetaManagedAgentsEffortHigh or 2 more`
1727
1728 How hard Claude works on each turn. Sets `output_config.effort` on every Messages call the session makes.
1729
1730 - `BetaManagedAgentsEffortLow object`
1731
1732 Low effort. Favors latency over reasoning depth.
1733
1734 - `type: "low"`
1735
1736 - `BetaManagedAgentsEffortMedium object`
1737
1738 Medium effort. Balances latency and reasoning depth.
1739
1740 - `type: "medium"`
1741
1742 - `BetaManagedAgentsEffortHigh object`
1743
1744 High effort. Favors reasoning depth.
1745
1746 - `type: "high"`
1747
1748 - `BetaManagedAgentsEffortXhigh object`
1749
1750 Extra-high effort. Not all models accept this level.
1751
1752 - `type: "xhigh"`
1753
1754 - `BetaManagedAgentsEffortMax object`
1755
1756 Maximum effort. Favors reasoning depth over latency.
1757
1758 - `type: "max"`
1759
1760 - `inference_geo: optional string`
1761
1762 Geographic region for model inference. When unset, requests fall through to the workspace's default_inference_geo.
1763
1764 - `speed: optional "standard" or "fast"`
1765
1766 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.
1767
1768 - `"standard"`
1769
1770 - `"fast"`
1771
1772 - `multiagent: BetaManagedAgentsSessionMultiagentCoordinator or null`
1773
1774 Resolved coordinator topology with full agent definitions for each roster member.
1775
1776 - `type: "coordinator"`
1777
1778 - `agents: array of BetaManagedAgentsSessionThreadAgent or BetaManagedAgentsAdvisor`
1779
1780 Full `agent` definitions the coordinator may spawn as session threads.
1781
1782 - `BetaManagedAgentsSessionThreadAgent object`
1783
1784 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`.
1785
1786 - `type: "agent"`
1787
1788 - `id: string`
1789
1790 - `description: string or null`
1791
1792 - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition`
1793
1794 - `type: "url"`
1795
1796 - `name: string`
1797
1798 - `url: string`
1799
1800 - `model: BetaManagedAgentsModelConfig`
1801
1802 Model identifier and configuration.
1803
1804 - `name: string`
1805
1806 - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill`
1807
1808 - `BetaManagedAgentsAnthropicSkill object`
1809
1810 A resolved Anthropic-managed skill.
1811
1812 - `type: "anthropic"`
1813
1814 - `skill_id: string`
1815
1816 - `version: string`
1817
1818 - `BetaManagedAgentsCustomSkill object`
1819
1820 A resolved user-created custom skill.
1821
1822 - `type: "custom"`
1823
1824 - `skill_id: string`
1825
1826 - `version: string`
1827
1828 - `system: string or null`
1829
1830 - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool`
1831
1832 - `BetaManagedAgentsAgentToolset20260401 object`
1833
1834 - `type: "agent_toolset_20260401"`
1835
1836 - `configs: array of BetaManagedAgentsAgentToolConfig`
1837
1838 - `BetaManagedAgentsBashToolConfig object`
1839
1840 Configuration for the bash tool.
1841
1842 - `type: "bash"`
1843
1844 - `enabled: boolean`
1845
1846 - `name: "bash"`
1847
1848 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
1849
1850 Permission policy for tool execution.
1851
1852 - `BetaManagedAgentsAlwaysAllowPolicy object`
1853
1854 Tool calls are automatically approved without user confirmation.
1855
1856 - `type: "always_allow"`
1857
1858 - `BetaManagedAgentsAlwaysAskPolicy object`
1859
1860 Tool calls require user confirmation before execution.
1861
1862 - `type: "always_ask"`
1863
1864 - `BetaManagedAgentsAutoPolicy object`
1865
1866 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
1867
1868 - `type: "auto"`
1869
1870 - `BetaManagedAgentsEditToolConfig object`
1871
1872 Configuration for the edit tool.
1873
1874 - `type: "edit"`
1875
1876 - `enabled: boolean`
1877
1878 - `name: "edit"`
1879
1880 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
1881
1882 Permission policy for tool execution.
1883
1884 - `BetaManagedAgentsAlwaysAllowPolicy object`
1885
1886 Tool calls are automatically approved without user confirmation.
1887
1888 - `BetaManagedAgentsAlwaysAskPolicy object`
1889
1890 Tool calls require user confirmation before execution.
1891
1892 - `BetaManagedAgentsAutoPolicy object`
1893
1894 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
1895
1896 - `BetaManagedAgentsReadToolConfig object`
1897
1898 Configuration for the read tool.
1899
1900 - `type: "read"`
1901
1902 - `enabled: boolean`
1903
1904 - `name: "read"`
1905
1906 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
1907
1908 Permission policy for tool execution.
1909
1910 - `BetaManagedAgentsAlwaysAllowPolicy object`
1911
1912 Tool calls are automatically approved without user confirmation.
1913
1914 - `BetaManagedAgentsAlwaysAskPolicy object`
1915
1916 Tool calls require user confirmation before execution.
1917
1918 - `BetaManagedAgentsAutoPolicy object`
1919
1920 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
1921
1922 - `BetaManagedAgentsWriteToolConfig object`
1923
1924 Configuration for the write tool.
1925
1926 - `type: "write"`
1927
1928 - `enabled: boolean`
1929
1930 - `name: "write"`
1931
1932 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
1933
1934 Permission policy for tool execution.
1935
1936 - `BetaManagedAgentsAlwaysAllowPolicy object`
1937
1938 Tool calls are automatically approved without user confirmation.
1939
1940 - `BetaManagedAgentsAlwaysAskPolicy object`
1941
1942 Tool calls require user confirmation before execution.
1943
1944 - `BetaManagedAgentsAutoPolicy object`
1945
1946 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
1947
1948 - `BetaManagedAgentsGlobToolConfig object`
1949
1950 Configuration for the glob tool.
1951
1952 - `type: "glob"`
1953
1954 - `enabled: boolean`
1955
1956 - `name: "glob"`
1957
1958 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
1959
1960 Permission policy for tool execution.
1961
1962 - `BetaManagedAgentsAlwaysAllowPolicy object`
1963
1964 Tool calls are automatically approved without user confirmation.
1965
1966 - `BetaManagedAgentsAlwaysAskPolicy object`
1967
1968 Tool calls require user confirmation before execution.
1969
1970 - `BetaManagedAgentsAutoPolicy object`
1971
1972 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
1973
1974 - `BetaManagedAgentsGrepToolConfig object`
1975
1976 Configuration for the grep tool.
1977
1978 - `type: "grep"`
1979
1980 - `enabled: boolean`
1981
1982 - `name: "grep"`
1983
1984 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
1985
1986 Permission policy for tool execution.
1987
1988 - `BetaManagedAgentsAlwaysAllowPolicy object`
1989
1990 Tool calls are automatically approved without user confirmation.
1991
1992 - `BetaManagedAgentsAlwaysAskPolicy object`
1993
1994 Tool calls require user confirmation before execution.
1995
1996 - `BetaManagedAgentsAutoPolicy object`
1997
1998 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
1999
2000 - `BetaManagedAgentsWebFetchToolConfig object`
2001
2002 Configuration for the web_fetch tool.
2003
2004 - `type: "web_fetch"`
2005
2006 - `enabled: boolean`
2007
2008 - `name: "web_fetch"`
2009
2010 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
2011
2012 Permission policy for tool execution.
2013
2014 - `BetaManagedAgentsAlwaysAllowPolicy object`
2015
2016 Tool calls are automatically approved without user confirmation.
2017
2018 - `BetaManagedAgentsAlwaysAskPolicy object`
2019
2020 Tool calls require user confirmation before execution.
2021
2022 - `BetaManagedAgentsAutoPolicy object`
2023
2024 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
2025
2026 - `allowed_domains: optional array of string`
2027
2028 - `blocked_domains: optional array of string`
2029
2030 - `max_content_tokens: optional number or null`
2031
2032 format: int32
2033
2034 - `BetaManagedAgentsWebSearchToolConfig object`
2035
2036 Configuration for the web_search tool.
2037
2038 - `type: "web_search"`
2039
2040 - `enabled: boolean`
2041
2042 - `name: "web_search"`
2043
2044 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
2045
2046 Permission policy for tool execution.
2047
2048 - `BetaManagedAgentsAlwaysAllowPolicy object`
2049
2050 Tool calls are automatically approved without user confirmation.
2051
2052 - `BetaManagedAgentsAlwaysAskPolicy object`
2053
2054 Tool calls require user confirmation before execution.
2055
2056 - `BetaManagedAgentsAutoPolicy object`
2057
2058 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
2059
2060 - `allowed_domains: optional array of string`
2061
2062 - `blocked_domains: optional array of string`
2063
2064 - `user_location: optional BetaManagedAgentsUserLocation or null`
2065
2066 Approximate user location for search result localization.
2067
2068 - `type: "approximate"`
2069
2070 Location precision. Only "approximate" is supported.
2071
2072 - `city: optional string or null`
2073
2074 City name.
2075
2076 minLength: 1, maxLength: 255
2077
2078 - `country: optional string or null`
2079
2080 Two-letter ISO 3166-1 country code, uppercase.
2081
2082 - `region: optional string or null`
2083
2084 Region or state name.
2085
2086 minLength: 1, maxLength: 255
2087
2088 - `timezone: optional string or null`
2089
2090 IANA timezone identifier, e.g. "America/Los_Angeles".
2091
2092 minLength: 1, maxLength: 255
2093
2094 - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig`
2095
2096 Resolved default configuration for agent tools.
2097
2098 - `enabled: boolean`
2099
2100 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
2101
2102 Permission policy for tool execution.
2103
2104 - `BetaManagedAgentsAlwaysAllowPolicy object`
2105
2106 Tool calls are automatically approved without user confirmation.
2107
2108 - `BetaManagedAgentsAlwaysAskPolicy object`
2109
2110 Tool calls require user confirmation before execution.
2111
2112 - `BetaManagedAgentsAutoPolicy object`
2113
2114 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
2115
2116 - `BetaManagedAgentsMCPToolset object`
2117
2118 - `type: "mcp_toolset"`
2119
2120 - `configs: array of BetaManagedAgentsMCPToolConfig`
2121
2122 - `enabled: boolean`
2123
2124 - `name: string`
2125
2126 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
2127
2128 Permission policy for tool execution.
2129
2130 - `BetaManagedAgentsAlwaysAllowPolicy object`
2131
2132 Tool calls are automatically approved without user confirmation.
2133
2134 - `BetaManagedAgentsAlwaysAskPolicy object`
2135
2136 Tool calls require user confirmation before execution.
2137
2138 - `BetaManagedAgentsAutoPolicy object`
2139
2140 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
2141
2142 - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig`
2143
2144 Resolved default configuration for all tools from an MCP server.
2145
2146 - `enabled: boolean`
2147
2148 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
2149
2150 Permission policy for tool execution.
2151
2152 - `BetaManagedAgentsAlwaysAllowPolicy object`
2153
2154 Tool calls are automatically approved without user confirmation.
2155
2156 - `BetaManagedAgentsAlwaysAskPolicy object`
2157
2158 Tool calls require user confirmation before execution.
2159
2160 - `BetaManagedAgentsAutoPolicy object`
2161
2162 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
2163
2164 - `mcp_server_name: string`
2165
2166 - `BetaManagedAgentsCustomTool object`
2167
2168 A custom tool as returned in API responses.
2169
2170 - `type: "custom"`
2171
2172 - `description: string`
2173
2174 - `input_schema: BetaManagedAgentsCustomToolInputSchema`
2175
2176 JSON Schema for custom tool input parameters.
2177
2178 - `type: "object"`
2179
2180 - `properties: optional map[unknown] or null`
2181
2182 - `required: optional array of string or null`
2183
2184 - `name: string`
2185
2186 - `version: number`
2187
2188 format: int32
2189
2190 - `BetaManagedAgentsAdvisor object`
2191
2192 Platform advisor roster entry: a model the session's primary thread may consult mid-turn.
2193
2194 - `type: "advisor"`
2195
2196 - `model: string`
2197
2198 The advisor model id.
2199
2200 - `name: string`
2201
2202 - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill`
2203
2204 - `BetaManagedAgentsAnthropicSkill object`
2205
2206 A resolved Anthropic-managed skill.
2207
2208 - `BetaManagedAgentsCustomSkill object`
2209
2210 A resolved user-created custom skill.
2211
2212 - `system: string or null`
2213
2214 - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool`
2215
2216 - `BetaManagedAgentsAgentToolset20260401 object`
2217
2218 - `BetaManagedAgentsMCPToolset object`
2219
2220 - `BetaManagedAgentsCustomTool object`
2221
2222 A custom tool as returned in API responses.
2223
2224 - `version: number`
2225
2226 format: int32
2227
2228 - `budget: optional BetaManagedAgentsBudgetLimit or null`
2229
2230 A hard spend ceiling. The session stops issuing new model requests once the tracked list cost reaches `max_list_cost`.
2231
2232 - `type: "limit"`
2233
2234 - `max_list_cost: BetaMonetaryAmount`
2235
2236 A monetary amount in a specific currency.
2237
2238 - `amount: string`
2239
2240 Amount in minor units of the currency, as an integer decimal string with no leading zeros: "2500" is $25.00 and "50" is fifty cents. A string rather than a number so no float rounding is ever applied.
2241
2242 - `currency: BetaCurrency`
2243
2244 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.
2245
2246 - `metadata: optional map[string]`
2247
2248 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.
2249
2250 - `title: optional string or null`
2251
2252 The session's new title. Present only when the update changed it.
2253
2254 - `BetaManagedAgentsStartEvent object`
2255
2256 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.
2257
2258 - `type: "event_start"`
2259
2260 - `event: BetaManagedAgentsStartEventPreview`
2261
2262 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.
2263
2264 - `BetaManagedAgentsAgentMessagePreview object`
2265
2266 - `type: "agent.message"`
2267
2268 - `id: string`
2269
2270 The id the buffered agent.message will carry if it is emitted. Matches the event_id on this preview's event_delta events.
2271
2272 - `BetaManagedAgentsAgentThinkingPreview object`
2273
2274 - `type: "agent.thinking"`
2275
2276 - `id: string`
2277
2278 The id the buffered agent.thinking will carry if it is emitted. Start-only — no event_delta events follow.
2279
2280 - `BetaManagedAgentsDeltaEvent object`
2281
2282 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.
2283
2284 - `type: "event_delta"`
2285
2286 - `delta: BetaManagedAgentsDeltaContent`
2287
2288 One fragment of the previewed event. The delta type is named for the previewed event's field it streams into: agent.message events stream content_delta fragments, each a partial element of the content array.
2289
2290 - `type: "content_delta"`
2291
2292 - `content: BetaManagedAgentsTextBlock`
2293
2294 Regular text content.
2295
2296 - `index: optional number`
2297
2298 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.
2299
2300 format: uint32
2301
2302 - `event_id: string`
2303
2304 The id of the event being previewed. Matches event.id on the corresponding event_start and the buffered event that reconciles the preview.
2305
2306 - `BetaManagedAgentsSystemMessageEvent object`
2307
2308 A mid-conversation system message event. Carries system-role content that is appended to the session as a `role: "system"` turn.
2309
2310 - `type: "system.message"`
2311
2312 - `id: string`
2313
2314 Unique identifier for this event.
2315
2316 - `content: array of BetaManagedAgentsSystemContentBlock`
2317
2318 System content blocks. Text-only.
2319
2320 - `type: "text"`
2321
2322 - `text: string`
2323
2324 The text content.
2325
2326 minLength: 1
3002327
3012328 - `processed_at: optional string or null`
3022329
from line 2331
3042331
3052332 format: date-time
3062333
307 - `session_thread_id: optional string or null`
308
309 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.
310
311 - `BetaManagedAgentsUserToolConfirmationEvent object`
312
313 A tool confirmation event that approves or denies a pending tool execution.
314
315 - `id: string`
316
317 Unique identifier for this event.
318
319 - `result: "allow" or "deny"`
320
321 UserToolConfirmationResult enum
322
323 - `"allow"`
324
325 - `"deny"`
326
327 - `tool_use_id: string`
328
329 The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field.
330
331 - `type: "user.tool_confirmation"`
332
333 - `deny_message: optional string or null`
334
335 Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'.
336
337 maxLength: 10000
338
339 - `processed_at: optional string or null`
340
341 A timestamp in RFC 3339 format
342
343 format: date-time
344
345 - `session_thread_id: optional string or null`
346
347 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.
348
349 - `BetaManagedAgentsUserCustomToolResultEvent object`
350
351 Event sent by the client providing the result of a custom tool execution.
352
353 - `id: string`
354
355 Unique identifier for this event.
356
357 - `custom_tool_use_id: string`
358
359 The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field.
360
361 - `type: "user.custom_tool_result"`
362
363 - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock`
364
365 The result content returned by the tool.
366
367 - `BetaManagedAgentsTextBlock object`
368
369 Regular text content.
370
371 - `BetaManagedAgentsImageBlock object`
372
373 Image content specified directly as base64 data or as a reference via a URL.
374
375 - `BetaManagedAgentsDocumentBlock object`
376
377 Document content, either specified directly as base64 data, as text, or as a reference via a URL.
378
379 - `BetaManagedAgentsSearchResultBlock object`
380
381 A block containing a web search result.
382
383 - `citations: BetaManagedAgentsSearchResultCitations`
384
385 Citation settings for a search result.
386
387 - `enabled: boolean`
388
389 Whether citations are enabled for this search result.
390
391 - `content: array of BetaManagedAgentsSearchResultContent`
392
393 Array of text content blocks from the search result.
394
395 - `text: string`
396
397 The text content.
398
399 minLength: 1
400
401 - `type: "text"`
402
403 - `source: string`
404
405 The URL source of the search result.
406
407 minLength: 1
408
409 - `title: string`
410
411 The title of the search result.
412
413 minLength: 1
414
415 - `type: "search_result"`
416
417 - `is_error: optional boolean or null`
418
419 Whether the tool execution resulted in an error.
420
421 - `processed_at: optional string or null`
422
423 A timestamp in RFC 3339 format
424
425 format: date-time
426
427 - `session_thread_id: optional string or null`
428
429 Routes this result to a subagent thread. Copy from the `agent.custom_tool_use` event's `session_thread_id`.
430
431 - `BetaManagedAgentsAgentCustomToolUseEvent object`
432
433 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.
434
435 - `id: string`
436
437 Unique identifier for this event.
438
439 - `input: map[unknown]`
440
441 Input parameters for the tool call.
442
443 - `name: string`
444
445 Name of the custom tool being called.
446
447 - `processed_at: string`
448
449 A timestamp in RFC 3339 format
450
451 format: date-time
452
453 - `type: "agent.custom_tool_use"`
454
455 - `session_thread_id: optional string or null`
456
457 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.
458
459 - `BetaManagedAgentsAgentMessageEvent object`
460
461 An agent response event in the session conversation.
462
463 - `id: string`
464
465 Unique identifier for this event.
466
467 - `content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsRedactedBlock`
468
469 Array of text blocks comprising the agent response.
470
471 - `BetaManagedAgentsTextBlock object`
472
473 Regular text content.
474
475 - `BetaManagedAgentsRedactedBlock object`
476
477 Placeholder for content withheld by Anthropic model policy.
478
479 - `processed_at: string`
480
481 A timestamp in RFC 3339 format
482
483 format: date-time
484
485 - `type: "agent.message"`
486
487 - `BetaManagedAgentsAgentThinkingEvent object`
488
489 Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier.
490
491 - `id: string`
492
493 Unique identifier for this event.
494
495 - `processed_at: string`
496
497 A timestamp in RFC 3339 format
498
499 format: date-time
500
501 - `type: "agent.thinking"`
502
503 - `BetaManagedAgentsAgentMCPToolUseEvent object`
504
505 Event emitted when the agent invokes a tool provided by an MCP server.
506
507 - `id: string`
508
509 Unique identifier for this event.
510
511 - `input: map[unknown]`
512
513 Input parameters for the tool call.
514
515 - `mcp_server_name: string`
516
517 Name of the MCP server providing the tool.
518
519 - `name: string`
520
521 Name of the MCP tool being used.
522
523 - `processed_at: string`
524
525 A timestamp in RFC 3339 format
526
527 format: date-time
528
529 - `type: "agent.mcp_tool_use"`
530
531 - `evaluated_permission: optional "allow" or "ask" or "deny"`
532
533 AgentEvaluatedPermission enum
534
535 - `"allow"`
536
537 - `"ask"`
538
539 - `"deny"`
540
541 - `session_thread_id: optional string or null`
542
543 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.
544
545 - `BetaManagedAgentsAgentMCPToolResultEvent object`
546
547 Event representing the result of an MCP tool execution.
548
549 - `id: string`
550
551 Unique identifier for this event.
552
553 - `mcp_tool_use_id: string`
554
555 The id of the `agent.mcp_tool_use` event this result corresponds to.
556
557 - `processed_at: string`
558
559 A timestamp in RFC 3339 format
560
561 format: date-time
562
563 - `type: "agent.mcp_tool_result"`
564
565 - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock`
566
567 The result content returned by the tool.
568
569 - `BetaManagedAgentsTextBlock object`
570
571 Regular text content.
572
573 - `BetaManagedAgentsImageBlock object`
574
575 Image content specified directly as base64 data or as a reference via a URL.
576
577 - `BetaManagedAgentsDocumentBlock object`
578
579 Document content, either specified directly as base64 data, as text, or as a reference via a URL.
580
581 - `BetaManagedAgentsSearchResultBlock object`
582
583 A block containing a web search result.
584
585 - `is_error: optional boolean or null`
586
587 Whether the tool execution resulted in an error.
588
589 - `BetaManagedAgentsAgentToolUseEvent object`
590
591 Event emitted when the agent invokes a built-in agent tool.
592
593 - `id: string`
594
595 Unique identifier for this event.
596
597 - `input: map[unknown]`
598
599 Input parameters for the tool call.
600
601 - `name: string`
602
603 Name of the agent tool being used.
604
605 - `processed_at: string`
606
607 A timestamp in RFC 3339 format
608
609 format: date-time
610
611 - `type: "agent.tool_use"`
612
613 - `evaluated_permission: optional "allow" or "ask" or "deny"`
614
615 AgentEvaluatedPermission enum
616
617 - `"allow"`
618
619 - `"ask"`
620
621 - `"deny"`
622
623 - `session_thread_id: optional string or null`
624
625 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.
626
627 - `BetaManagedAgentsAgentToolResultEvent object`
628
629 Event representing the result of an agent tool execution.
630
631 - `id: string`
632
633 Unique identifier for this event.
634
635 - `processed_at: string`
636
637 A timestamp in RFC 3339 format
638
639 format: date-time
640
641 - `tool_use_id: string`
642
643 The id of the `agent.tool_use` event this result corresponds to.
644
645 - `type: "agent.tool_result"`
646
647 - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock`
648
649 The result content returned by the tool.
650
651 - `BetaManagedAgentsTextBlock object`
652
653 Regular text content.
654
655 - `BetaManagedAgentsImageBlock object`
656
657 Image content specified directly as base64 data or as a reference via a URL.
658
659 - `BetaManagedAgentsDocumentBlock object`
660
661 Document content, either specified directly as base64 data, as text, or as a reference via a URL.
662
663 - `BetaManagedAgentsSearchResultBlock object`
664
665 A block containing a web search result.
666
667 - `is_error: optional boolean or null`
668
669 Whether the tool execution resulted in an error.
670
671 - `BetaManagedAgentsAgentThreadMessageReceivedEvent object`
672
673 Delivery event written to the target thread's input stream when an agent-to-agent message arrives.
674
675 - `id: string`
676
677 Unique identifier for this event.
678
679 - `content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsRedactedBlock`
680
681 Message content blocks.
682
683 - `BetaManagedAgentsTextBlock object`
684
685 Regular text content.
686
687 - `BetaManagedAgentsImageBlock object`
688
689 Image content specified directly as base64 data or as a reference via a URL.
690
691 - `BetaManagedAgentsDocumentBlock object`
692
693 Document content, either specified directly as base64 data, as text, or as a reference via a URL.
694
695 - `BetaManagedAgentsRedactedBlock object`
696
697 Placeholder for content withheld by Anthropic model policy.
698
699 - `from_session_thread_id: string`
700
701 Public `sthr_` ID of the thread that sent the message.
702
703 - `processed_at: string`
704
705 A timestamp in RFC 3339 format
706
707 format: date-time
708
709 - `type: "agent.thread_message_received"`
710
711 - `from_agent_name: optional string or null`
712
713 Name of the callable agent this message came from. Absent when received from the primary agent.
714
715 - `BetaManagedAgentsAgentThreadMessageSentEvent object`
716
717 Observability event emitted to the sender's output stream when an agent-to-agent message is sent.
718
719 - `id: string`
720
721 Unique identifier for this event.
722
723 - `content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsRedactedBlock`
724
725 Message content blocks.
726
727 - `BetaManagedAgentsTextBlock object`
728
729 Regular text content.
730
731 - `BetaManagedAgentsImageBlock object`
732
733 Image content specified directly as base64 data or as a reference via a URL.
734
735 - `BetaManagedAgentsDocumentBlock object`
736
737 Document content, either specified directly as base64 data, as text, or as a reference via a URL.
738
739 - `BetaManagedAgentsRedactedBlock object`
740
741 Placeholder for content withheld by Anthropic model policy.
742
743 - `processed_at: string`
744
745 A timestamp in RFC 3339 format
746
747 format: date-time
748
749 - `to_session_thread_id: string`
750
751 Public `sthr_` ID of the thread the message was sent to.
752
753 - `type: "agent.thread_message_sent"`
754
755 - `to_agent_name: optional string or null`
756
757 Name of the callable agent this message was sent to. Absent when sent to the primary agent.
758
759 - `BetaManagedAgentsAgentThreadContextCompactedEvent object`
760
761 Indicates that context compaction (summarization) occurred during the session.
762
763 - `id: string`
764
765 Unique identifier for this event.
766
767 - `processed_at: string`
768
769 A timestamp in RFC 3339 format
770
771 format: date-time
772
773 - `type: "agent.thread_context_compacted"`
774
775 - `BetaManagedAgentsSessionErrorEvent object`
776
777 An error event indicating a problem occurred during session execution.
778
779 - `id: string`
780
781 Unique identifier for this event.
782
783 - `error: BetaManagedAgentsUnknownError or BetaManagedAgentsModelOverloadedError or BetaManagedAgentsModelRateLimitedError or 5 more`
784
785 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.
786
787 - `BetaManagedAgentsUnknownError object`
788
789 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.
790
791 - `message: string`
792
793 Human-readable error description.
794
795 - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal`
796
797 What the client should do next in response to this error.
798
799 - `BetaManagedAgentsRetryStatusRetrying object`
800
801 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.
802
803 - `type: "retrying"`
804
805 - `BetaManagedAgentsRetryStatusExhausted object`
806
807 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
808
809 - `type: "exhausted"`
810
811 - `BetaManagedAgentsRetryStatusTerminal object`
812
813 The session encountered a terminal error and will transition to `terminated` state.
814
815 - `type: "terminal"`
816
817 - `type: "unknown_error"`
818
819 - `BetaManagedAgentsModelOverloadedError object`
820
821 The model is currently overloaded. Emitted after automatic retries are exhausted.
822
823 - `message: string`
824
825 Human-readable error description.
826
827 - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal`
828
829 What the client should do next in response to this error.
830
831 - `BetaManagedAgentsRetryStatusRetrying object`
832
833 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.
834
835 - `BetaManagedAgentsRetryStatusExhausted object`
836
837 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
838
839 - `BetaManagedAgentsRetryStatusTerminal object`
840
841 The session encountered a terminal error and will transition to `terminated` state.
842
843 - `type: "model_overloaded_error"`
844
845 - `BetaManagedAgentsModelRateLimitedError object`
846
847 The model request was rate-limited.
848
849 - `message: string`
850
851 Human-readable error description.
852
853 - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal`
854
855 What the client should do next in response to this error.
856
857 - `BetaManagedAgentsRetryStatusRetrying object`
858
859 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.
860
861 - `BetaManagedAgentsRetryStatusExhausted object`
862
863 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
864
865 - `BetaManagedAgentsRetryStatusTerminal object`
866
867 The session encountered a terminal error and will transition to `terminated` state.
868
869 - `type: "model_rate_limited_error"`
870
871 - `BetaManagedAgentsModelRequestFailedError object`
872
873 A model request failed for a reason other than overload or rate-limiting.
874
875 - `message: string`
876
877 Human-readable error description.
878
879 - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal`
880
881 What the client should do next in response to this error.
882
883 - `BetaManagedAgentsRetryStatusRetrying object`
884
885 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.
886
887 - `BetaManagedAgentsRetryStatusExhausted object`
888
889 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
890
891 - `BetaManagedAgentsRetryStatusTerminal object`
892
893 The session encountered a terminal error and will transition to `terminated` state.
894
895 - `type: "model_request_failed_error"`
896
897 - `BetaManagedAgentsMCPConnectionFailedError object`
898
899 Failed to connect to an MCP server.
900
901 - `mcp_server_name: string`
902
903 Name of the MCP server that failed to connect.
904
905 - `message: string`
906
907 Human-readable error description.
908
909 - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal`
910
911 What the client should do next in response to this error.
912
913 - `BetaManagedAgentsRetryStatusRetrying object`
914
915 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.
916
917 - `BetaManagedAgentsRetryStatusExhausted object`
918
919 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
920
921 - `BetaManagedAgentsRetryStatusTerminal object`
922
923 The session encountered a terminal error and will transition to `terminated` state.
924
925 - `type: "mcp_connection_failed_error"`
926
927 - `BetaManagedAgentsMCPAuthenticationFailedError object`
928
929 Authentication to an MCP server failed.
930
931 - `mcp_server_name: string`
932
933 Name of the MCP server that failed authentication.
934
935 - `message: string`
936
937 Human-readable error description.
938
939 - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal`
940
941 What the client should do next in response to this error.
942
943 - `BetaManagedAgentsRetryStatusRetrying object`
944
945 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.
946
947 - `BetaManagedAgentsRetryStatusExhausted object`
948
949 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
950
951 - `BetaManagedAgentsRetryStatusTerminal object`
952
953 The session encountered a terminal error and will transition to `terminated` state.
954
955 - `type: "mcp_authentication_failed_error"`
956
957 - `BetaManagedAgentsBillingError object`
958
959 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.
960
961 - `message: string`
962
963 Human-readable error description.
964
965 - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal`
966
967 What the client should do next in response to this error.
968
969 - `BetaManagedAgentsRetryStatusRetrying object`
970
971 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.
972
973 - `BetaManagedAgentsRetryStatusExhausted object`
974
975 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
976
977 - `BetaManagedAgentsRetryStatusTerminal object`
978
979 The session encountered a terminal error and will transition to `terminated` state.
980
981 - `type: "billing_error"`
982
983 - `BetaManagedAgentsCredentialHostUnreachableError object`
984
985 An `environment_variable` credential's `auth.networking.allowed_hosts` includes a host the environment's network policy does not permit.
986
987 - `credential_id: string`
988
989 ID of the affected credential.
990
991 - `message: string`
992
993 Human-readable error description.
994
995 - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal`
996
997 What the client should do next in response to this error.
998
999 - `BetaManagedAgentsRetryStatusRetrying object`
1000
1001 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.
1002
1003 - `BetaManagedAgentsRetryStatusExhausted object`
1004
1005 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
1006
1007 - `BetaManagedAgentsRetryStatusTerminal object`
1008
1009 The session encountered a terminal error and will transition to `terminated` state.
1010
1011 - `type: "credential_host_unreachable_error"`
1012
1013 - `vault_id: string`
1014
1015 ID of the vault containing the affected credential.
1016
1017 - `processed_at: string`
1018
1019 A timestamp in RFC 3339 format
1020
1021 format: date-time
1022
1023 - `type: "session.error"`
1024
1025 - `BetaManagedAgentsSessionStatusRescheduledEvent object`
1026
1027 Indicates the session is recovering from an error state and is rescheduled for execution.
1028
1029 - `id: string`
1030
1031 Unique identifier for this event.
1032
1033 - `processed_at: string`
1034
1035 A timestamp in RFC 3339 format
1036
1037 format: date-time
1038
1039 - `type: "session.status_rescheduled"`
1040
1041 - `BetaManagedAgentsSessionStatusRunningEvent object`
1042
1043 Indicates the session is actively running and the agent is working.
1044
1045 - `id: string`
1046
1047 Unique identifier for this event.
1048
1049 - `processed_at: string`
1050
1051 A timestamp in RFC 3339 format
1052
1053 format: date-time
1054
1055 - `type: "session.status_running"`
1056
1057 - `BetaManagedAgentsSessionStatusIdleEvent object`
1058
1059 Indicates the agent has paused and is awaiting user input.
1060
1061 - `id: string`
1062
1063 Unique identifier for this event.
1064
1065 - `processed_at: string`
1066
1067 A timestamp in RFC 3339 format
1068
1069 format: date-time
1070
1071 - `stop_reason: BetaManagedAgentsSessionEndTurn or BetaManagedAgentsSessionRequiresAction or BetaManagedAgentsSessionRetriesExhausted or BetaManagedAgentsSessionBudgetReached`
1072
1073 The agent completed its turn naturally and is ready for the next user message.
1074
1075 - `BetaManagedAgentsSessionEndTurn object`
1076
1077 The agent completed its turn naturally and is ready for the next user message.
1078
1079 - `type: "end_turn"`
1080
1081 - `BetaManagedAgentsSessionRequiresAction object`
1082
1083 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.
1084
1085 - `event_ids: array of string`
1086
1087 The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder.
1088
1089 - `type: "requires_action"`
1090
1091 - `BetaManagedAgentsSessionRetriesExhausted object`
1092
1093 The turn ended because repeated errors exhausted the retry budget or an error escalated to `retry_status: 'exhausted'`.
1094
1095 - `type: "retries_exhausted"`
1096
1097 - `BetaManagedAgentsSessionBudgetReached object`
1098
1099 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.
1100
1101 - `type: "budget_reached"`
1102
1103 - `type: "session.status_idle"`
1104
1105 - `BetaManagedAgentsSessionStatusTerminatedEvent object`
1106
1107 Indicates the session has terminated, either due to an error or completion.
1108
1109 - `id: string`
1110
1111 Unique identifier for this event.
1112
1113 - `processed_at: string`
1114
1115 A timestamp in RFC 3339 format
1116
1117 format: date-time
1118
1119 - `type: "session.status_terminated"`
1120
1121 - `BetaManagedAgentsSessionThreadCreatedEvent object`
1122
1123 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.
1124
1125 - `id: string`
1126
1127 Unique identifier for this event.
1128
1129 - `agent_name: string`
1130
1131 Name of the callable agent the thread runs.
1132
1133 - `processed_at: string`
1134
1135 A timestamp in RFC 3339 format
1136
1137 format: date-time
1138
1139 - `session_thread_id: string`
1140
1141 Public `sthr_` ID of the newly created thread.
1142
1143 - `type: "session.thread_created"`
1144
1145 - `BetaManagedAgentsSpanOutcomeEvaluationStartEvent object`
1146
1147 Emitted when an outcome evaluation cycle begins.
1148
1149 - `id: string`
1150
1151 Unique identifier for this event.
1152
1153 - `iteration: number`
1154
1155 0-indexed revision cycle. 0 is the first evaluation; 1 is the re-evaluation after the first revision; etc.
1156
1157 format: int32
1158
1159 - `outcome_id: string`
1160
1161 The `outc_` ID of the outcome being evaluated.
1162
1163 - `processed_at: string`
1164
1165 A timestamp in RFC 3339 format
1166
1167 format: date-time
1168
1169 - `type: "span.outcome_evaluation_start"`
1170
1171 - `BetaManagedAgentsSpanOutcomeEvaluationEndEvent object`
1172
1173 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.
1174
1175 - `id: string`
1176
1177 Unique identifier for this event.
1178
1179 - `explanation: string`
1180
1181 Human-readable explanation of the verdict. For `needs_revision`, describes which criteria failed and why.
1182
1183 - `iteration: number`
1184
1185 0-indexed revision cycle, matching the corresponding `span.outcome_evaluation_start`.
1186
1187 format: int32
1188
1189 - `outcome_evaluation_start_id: string`
1190
1191 The id of the corresponding `span.outcome_evaluation_start` event.
1192
1193 - `outcome_id: string`
1194
1195 The `outc_` ID of the outcome being evaluated.
1196
1197 - `processed_at: string`
1198
1199 A timestamp in RFC 3339 format
1200
1201 format: date-time
1202
1203 - `result: string`
1204
1205 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.
1206
1207 - `type: "span.outcome_evaluation_end"`
1208
1209 - `usage: BetaManagedAgentsSpanModelUsage`
1210
1211 Token usage for a single model request.
1212
1213 - `cache_creation_input_tokens: number`
1214
1215 Tokens used to create prompt cache in this request.
1216
1217 format: int32
1218
1219 - `cache_read_input_tokens: number`
1220
1221 Tokens read from prompt cache in this request.
1222
1223 format: int32
1224
1225 - `input_tokens: number`
1226
1227 Input tokens consumed by this request.
1228
1229 format: int32
1230
1231 - `output_tokens: number`
1232
1233 Output tokens generated by this request.
1234
1235 format: int32
1236
1237 - `speed: optional "standard" or "fast" or null`
1238
1239 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.
1240
1241 - `"standard"`
1242
1243 - `"fast"`
1244
1245 - `BetaManagedAgentsSpanModelRequestStartEvent object`
1246
1247 Emitted when a model request is initiated by the agent.
1248
1249 - `id: string`
1250
1251 Unique identifier for this event.
1252
1253 - `processed_at: string`
1254
1255 A timestamp in RFC 3339 format
1256
1257 format: date-time
1258
1259 - `type: "span.model_request_start"`
1260
1261 - `BetaManagedAgentsSpanModelRequestEndEvent object`
1262
1263 Emitted when a model request completes.
1264
1265 - `id: string`
1266
1267 Unique identifier for this event.
1268
1269 - `is_error: boolean or null`
1270
1271 Whether the model request resulted in an error.
1272
1273 - `model_request_start_id: string`
1274
1275 The id of the corresponding `span.model_request_start` event.
1276
1277 - `model_usage: BetaManagedAgentsSpanModelUsage`
1278
1279 Token usage for a single model request.
1280
1281 - `processed_at: string`
1282
1283 A timestamp in RFC 3339 format
1284
1285 format: date-time
1286
1287 - `type: "span.model_request_end"`
1288
1289 - `BetaManagedAgentsSpanOutcomeEvaluationOngoingEvent object`
1290
1291 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.
1292
1293 - `id: string`
1294
1295 Unique identifier for this event.
1296
1297 - `iteration: number`
1298
1299 0-indexed revision cycle, matching the corresponding `span.outcome_evaluation_start`.
1300
1301 format: int32
1302
1303 - `outcome_id: string`
1304
1305 The `outc_` ID of the outcome being evaluated.
1306
1307 - `processed_at: string`
1308
1309 A timestamp in RFC 3339 format
1310
1311 format: date-time
1312
1313 - `type: "span.outcome_evaluation_ongoing"`
1314
1315 - `BetaManagedAgentsUserDefineOutcomeEvent object`
1316
1317 Echo of a `user.define_outcome` input event. Carries the server-generated `outcome_id` that subsequent `span.outcome_evaluation_*` events reference.
1318
1319 - `id: string`
1320
1321 Unique identifier for this event.
1322
1323 - `description: string`
1324
1325 What the agent should produce. Copied from the input event.
1326
1327 - `max_iterations: number or null`
1328
1329 Evaluate-then-revise cycles before giving up. Default 3, max 20.
1330
1331 format: int32
1332
1333 - `outcome_id: string`
1334
1335 Server-generated `outc_` ID for this outcome. Referenced by `span.outcome_evaluation_*` events and the session's `outcome_evaluations` list.
1336
1337 - `processed_at: string`
1338
1339 A timestamp in RFC 3339 format
1340
1341 format: date-time
1342
1343 - `rubric: BetaManagedAgentsFileRubric or BetaManagedAgentsTextRubric`
1344
1345 Rubric for grading the quality of an outcome.
1346
1347 - `BetaManagedAgentsFileRubric object`
1348
1349 Rubric referenced by a file uploaded via the Files API.
1350
1351 - `file_id: string`
1352
1353 ID of the rubric file.
1354
1355 - `type: "file"`
1356
1357 - `BetaManagedAgentsTextRubric object`
1358
1359 Rubric content provided inline as text.
1360
1361 - `content: string`
1362
1363 Rubric content. Plain text or markdown — the grader treats it as freeform text.
1364
1365 - `type: "text"`
1366
1367 - `type: "user.define_outcome"`
1368
1369 - `BetaManagedAgentsSessionDeletedEvent object`
1370
1371 Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session.
1372
1373 - `id: string`
1374
1375 Unique identifier for this event.
1376
1377 - `processed_at: string`
1378
1379 A timestamp in RFC 3339 format
1380
1381 format: date-time
1382
1383 - `type: "session.deleted"`
1384
1385 - `BetaManagedAgentsSessionThreadStatusRunningEvent object`
1386
1387 A session thread has begun executing. Emitted on the thread's own stream and cross-posted to the primary stream for child threads.
1388
1389 - `id: string`
1390
1391 Unique identifier for this event.
1392
1393 - `agent_name: string`
1394
1395 Name of the agent the thread runs.
1396
1397 - `processed_at: string`
1398
1399 A timestamp in RFC 3339 format
1400
1401 format: date-time
1402
1403 - `session_thread_id: string`
1404
1405 Public sthr_ ID of the thread that started running.
1406
1407 - `type: "session.thread_status_running"`
1408
1409 - `BetaManagedAgentsSessionThreadStatusIdleEvent object`
1410
1411 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.
1412
1413 - `id: string`
1414
1415 Unique identifier for this event.
1416
1417 - `agent_name: string`
1418
1419 Name of the agent the thread runs.
1420
1421 - `processed_at: string`
1422
1423 A timestamp in RFC 3339 format
1424
1425 format: date-time
1426
1427 - `session_thread_id: string`
1428
1429 Public sthr_ ID of the thread that went idle.
1430
1431 - `stop_reason: BetaManagedAgentsSessionEndTurn or BetaManagedAgentsSessionRequiresAction or BetaManagedAgentsSessionRetriesExhausted or BetaManagedAgentsSessionBudgetReached`
1432
1433 The agent completed its turn naturally and is ready for the next user message.
1434
1435 - `BetaManagedAgentsSessionEndTurn object`
1436
1437 The agent completed its turn naturally and is ready for the next user message.
1438
1439 - `BetaManagedAgentsSessionRequiresAction object`
1440
1441 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.
1442
1443 - `BetaManagedAgentsSessionRetriesExhausted object`
1444
1445 The turn ended because repeated errors exhausted the retry budget or an error escalated to `retry_status: 'exhausted'`.
1446
1447 - `BetaManagedAgentsSessionBudgetReached object`
1448
1449 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.
1450
1451 - `type: "session.thread_status_idle"`
1452
1453 - `BetaManagedAgentsSessionThreadStatusTerminatedEvent object`
1454
1455 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.
1456
1457 - `id: string`
1458
1459 Unique identifier for this event.
1460
1461 - `agent_name: string`
1462
1463 Name of the agent the thread runs.
1464
1465 - `processed_at: string`
1466
1467 A timestamp in RFC 3339 format
1468
1469 format: date-time
1470
1471 - `session_thread_id: string`
1472
1473 Public sthr_ ID of the thread that terminated.
1474
1475 - `type: "session.thread_status_terminated"`
1476
1477 - `BetaManagedAgentsUserToolResultEvent object`
1478
1479 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.
1480
1481 - `id: string`
1482
1483 Unique identifier for this event.
1484
1485 - `tool_use_id: string`
1486
1487 The id of the `agent.tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field.
1488
1489 - `type: "user.tool_result"`
1490
1491 - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock`
1492
1493 The result content returned by the tool.
1494
1495 - `BetaManagedAgentsTextBlock object`
1496
1497 Regular text content.
1498
1499 - `BetaManagedAgentsImageBlock object`
1500
1501 Image content specified directly as base64 data or as a reference via a URL.
1502
1503 - `BetaManagedAgentsDocumentBlock object`
1504
1505 Document content, either specified directly as base64 data, as text, or as a reference via a URL.
1506
1507 - `BetaManagedAgentsSearchResultBlock object`
1508
1509 A block containing a web search result.
1510
1511 - `is_error: optional boolean or null`
1512
1513 Whether the tool execution resulted in an error.
1514
1515 - `processed_at: optional string or null`
1516
1517 A timestamp in RFC 3339 format
1518
1519 format: date-time
1520
1521 - `session_thread_id: optional string or null`
1522
1523 Routes this result to a subagent thread. Copy from the `agent.tool_use` event's `session_thread_id`.
1524
1525 - `BetaManagedAgentsSessionThreadStatusRescheduledEvent object`
1526
1527 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.
1528
1529 - `id: string`
1530
1531 Unique identifier for this event.
1532
1533 - `agent_name: string`
1534
1535 Name of the agent the thread runs.
1536
1537 - `processed_at: string`
1538
1539 A timestamp in RFC 3339 format
1540
1541 format: date-time
1542
1543 - `session_thread_id: string`
1544
1545 Public sthr_ ID of the thread that is retrying.
1546
1547 - `type: "session.thread_status_rescheduled"`
1548
1549 - `BetaManagedAgentsSessionUpdatedEvent object`
1550
1551 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.
1552
1553 - `id: string`
1554
1555 Unique identifier for this event.
1556
1557 - `processed_at: string`
1558
1559 A timestamp in RFC 3339 format
1560
1561 format: date-time
1562
1563 - `type: "session.updated"`
1564
1565 - `agent: optional BetaManagedAgentsSessionAgent or null`
1566
1567 Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time.
1568
1569 - `id: string`
1570
1571 - `description: string or null`
1572
1573 - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition`
1574
1575 - `name: string`
1576
1577 - `type: "url"`
1578
1579 - `url: string`
1580
1581 - `model: BetaManagedAgentsModelConfig`
1582
1583 Model identifier and configuration.
1584
1585 - `id: BetaManagedAgentsModel`
1586
1587 The model that will power your agent.
1588
1589 See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options.
1590
1591 - `"claude-fable-5-1" or "claude-sonnet-5" or "claude-fable-5" or 11 more`
1592
1593 The model that will power your agent.
1594
1595 See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options.
1596
1597 - `"claude-fable-5-1"`
1598
1599 Frontier intelligence for ambitious tasks across coding, scientific discovery, and enterprise workflows
1600
1601 - `"claude-sonnet-5"`
1602
1603 High-performance model for coding and agents
1604
1605 - `"claude-fable-5"`
1606
1607 Next generation of intelligence for the hardest knowledge work and coding problems
1608
1609 - `"claude-opus-5"`
1610
1611 Powerful intelligence for long-running agents and coding
1612
1613 - `"claude-opus-4-8"`
1614
1615 Powerful intelligence for long-running agents and coding
1616
1617 - `"claude-opus-4-7"`
1618
1619 Powerful intelligence for long-running agents and coding
1620
1621 - `"claude-opus-4-6"`
1622
1623 Powerful intelligence for long-running agents and coding
1624
1625 - `"claude-sonnet-4-6"`
1626
1627 Best combination of speed and intelligence
1628
1629 - `"claude-haiku-4-5"`
1630
1631 Fastest model with near-frontier intelligence
1632
1633 - `"claude-haiku-4-5-20251001"`
1634
1635 Fastest model with near-frontier intelligence
1636
1637 - `"claude-opus-4-5"`
1638
1639 Powerful intelligence for long-running agents and coding
1640
1641 - `"claude-opus-4-5-20251101"`
1642
1643 Powerful intelligence for long-running agents and coding
1644
1645 - `"claude-sonnet-4-5"`
1646
1647 High-performance model for agents and coding
1648
1649 - `"claude-sonnet-4-5-20250929"`
1650
1651 High-performance model for agents and coding
1652
1653 - `string`
1654
1655 - `effort: optional BetaManagedAgentsEffortLow or BetaManagedAgentsEffortMedium or BetaManagedAgentsEffortHigh or 2 more`
1656
1657 How hard Claude works on each turn. Sets `output_config.effort` on every Messages call the session makes.
1658
1659 - `BetaManagedAgentsEffortLow object`
1660
1661 Low effort. Favors latency over reasoning depth.
1662
1663 - `type: "low"`
1664
1665 - `BetaManagedAgentsEffortMedium object`
1666
1667 Medium effort. Balances latency and reasoning depth.
1668
1669 - `type: "medium"`
1670
1671 - `BetaManagedAgentsEffortHigh object`
1672
1673 High effort. Favors reasoning depth.
1674
1675 - `type: "high"`
1676
1677 - `BetaManagedAgentsEffortXhigh object`
1678
1679 Extra-high effort. Not all models accept this level.
1680
1681 - `type: "xhigh"`
1682
1683 - `BetaManagedAgentsEffortMax object`
1684
1685 Maximum effort. Favors reasoning depth over latency.
1686
1687 - `type: "max"`
1688
1689 - `inference_geo: optional string`
1690
1691 Geographic region for model inference. When unset, requests fall through to the workspace's default_inference_geo.
1692
1693 - `speed: optional "standard" or "fast"`
1694
1695 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.
1696
1697 - `"standard"`
1698
1699 - `"fast"`
1700
1701 - `multiagent: BetaManagedAgentsSessionMultiagentCoordinator or null`
1702
1703 Resolved coordinator topology with full agent definitions for each roster member.
1704
1705 - `agents: array of BetaManagedAgentsSessionThreadAgent or BetaManagedAgentsAdvisor`
1706
1707 Full `agent` definitions the coordinator may spawn as session threads.
1708
1709 - `BetaManagedAgentsSessionThreadAgent object`
1710
1711 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`.
1712
1713 - `id: string`
1714
1715 - `description: string or null`
1716
1717 - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition`
1718
1719 - `name: string`
1720
1721 - `type: "url"`
1722
1723 - `url: string`
1724
1725 - `model: BetaManagedAgentsModelConfig`
1726
1727 Model identifier and configuration.
1728
1729 - `name: string`
1730
1731 - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill`
1732
1733 - `BetaManagedAgentsAnthropicSkill object`
1734
1735 A resolved Anthropic-managed skill.
1736
1737 - `skill_id: string`
1738
1739 - `type: "anthropic"`
1740
1741 - `version: string`
1742
1743 - `BetaManagedAgentsCustomSkill object`
1744
1745 A resolved user-created custom skill.
1746
1747 - `skill_id: string`
1748
1749 - `type: "custom"`
1750
1751 - `version: string`
1752
1753 - `system: string or null`
1754
1755 - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool`
1756
1757 - `BetaManagedAgentsAgentToolset20260401 object`
1758
1759 - `configs: array of BetaManagedAgentsAgentToolConfig`
1760
1761 - `BetaManagedAgentsBashToolConfig object`
1762
1763 Configuration for the bash tool.
1764
1765 - `enabled: boolean`
1766
1767 - `name: "bash"`
1768
1769 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
1770
1771 Permission policy for tool execution.
1772
1773 - `BetaManagedAgentsAlwaysAllowPolicy object`
1774
1775 Tool calls are automatically approved without user confirmation.
1776
1777 - `type: "always_allow"`
1778
1779 - `BetaManagedAgentsAlwaysAskPolicy object`
1780
1781 Tool calls require user confirmation before execution.
1782
1783 - `type: "always_ask"`
1784
1785 - `type: "bash"`
1786
1787 - `BetaManagedAgentsEditToolConfig object`
1788
1789 Configuration for the edit tool.
1790
1791 - `enabled: boolean`
1792
1793 - `name: "edit"`
1794
1795 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
1796
1797 Permission policy for tool execution.
1798
1799 - `BetaManagedAgentsAlwaysAllowPolicy object`
1800
1801 Tool calls are automatically approved without user confirmation.
1802
1803 - `BetaManagedAgentsAlwaysAskPolicy object`
1804
1805 Tool calls require user confirmation before execution.
1806
1807 - `type: "edit"`
1808
1809 - `BetaManagedAgentsReadToolConfig object`
1810
1811 Configuration for the read tool.
1812
1813 - `enabled: boolean`
1814
1815 - `name: "read"`
1816
1817 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
1818
1819 Permission policy for tool execution.
1820
1821 - `BetaManagedAgentsAlwaysAllowPolicy object`
1822
1823 Tool calls are automatically approved without user confirmation.
1824
1825 - `BetaManagedAgentsAlwaysAskPolicy object`
1826
1827 Tool calls require user confirmation before execution.
1828
1829 - `type: "read"`
1830
1831 - `BetaManagedAgentsWriteToolConfig object`
1832
1833 Configuration for the write tool.
1834
1835 - `enabled: boolean`
1836
1837 - `name: "write"`
1838
1839 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
1840
1841 Permission policy for tool execution.
1842
1843 - `BetaManagedAgentsAlwaysAllowPolicy object`
1844
1845 Tool calls are automatically approved without user confirmation.
1846
1847 - `BetaManagedAgentsAlwaysAskPolicy object`
1848
1849 Tool calls require user confirmation before execution.
1850
1851 - `type: "write"`
1852
1853 - `BetaManagedAgentsGlobToolConfig object`
1854
1855 Configuration for the glob tool.
1856
1857 - `enabled: boolean`
1858
1859 - `name: "glob"`
1860
1861 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
1862
1863 Permission policy for tool execution.
1864
1865 - `BetaManagedAgentsAlwaysAllowPolicy object`
1866
1867 Tool calls are automatically approved without user confirmation.
1868
1869 - `BetaManagedAgentsAlwaysAskPolicy object`
1870
1871 Tool calls require user confirmation before execution.
1872
1873 - `type: "glob"`
1874
1875 - `BetaManagedAgentsGrepToolConfig object`
1876
1877 Configuration for the grep tool.
1878
1879 - `enabled: boolean`
1880
1881 - `name: "grep"`
1882
1883 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
1884
1885 Permission policy for tool execution.
1886
1887 - `BetaManagedAgentsAlwaysAllowPolicy object`
1888
1889 Tool calls are automatically approved without user confirmation.
1890
1891 - `BetaManagedAgentsAlwaysAskPolicy object`
1892
1893 Tool calls require user confirmation before execution.
1894
1895 - `type: "grep"`
1896
1897 - `BetaManagedAgentsWebFetchToolConfig object`
1898
1899 Configuration for the web_fetch tool.
1900
1901 - `enabled: boolean`
1902
1903 - `name: "web_fetch"`
1904
1905 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
1906
1907 Permission policy for tool execution.
1908
1909 - `BetaManagedAgentsAlwaysAllowPolicy object`
1910
1911 Tool calls are automatically approved without user confirmation.
1912
1913 - `BetaManagedAgentsAlwaysAskPolicy object`
1914
1915 Tool calls require user confirmation before execution.
1916
1917 - `type: "web_fetch"`
1918
1919 - `allowed_domains: optional array of string`
1920
1921 - `blocked_domains: optional array of string`
1922
1923 - `max_content_tokens: optional number or null`
1924
1925 format: int32
1926
1927 - `BetaManagedAgentsWebSearchToolConfig object`
1928
1929 Configuration for the web_search tool.
1930
1931 - `enabled: boolean`
1932
1933 - `name: "web_search"`
1934
1935 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
1936
1937 Permission policy for tool execution.
1938
1939 - `BetaManagedAgentsAlwaysAllowPolicy object`
1940
1941 Tool calls are automatically approved without user confirmation.
1942
1943 - `BetaManagedAgentsAlwaysAskPolicy object`
1944
1945 Tool calls require user confirmation before execution.
1946
1947 - `type: "web_search"`
1948
1949 - `allowed_domains: optional array of string`
1950
1951 - `blocked_domains: optional array of string`
1952
1953 - `user_location: optional BetaManagedAgentsUserLocation or null`
1954
1955 Approximate user location for search result localization.
1956
1957 - `type: "approximate"`
1958
1959 Location precision. Only "approximate" is supported.
1960
1961 - `city: optional string or null`
1962
1963 City name.
1964
1965 minLength: 1, maxLength: 255
1966
1967 - `country: optional string or null`
1968
1969 Two-letter ISO 3166-1 country code, uppercase.
1970
1971 - `region: optional string or null`
1972
1973 Region or state name.
1974
1975 minLength: 1, maxLength: 255
1976
1977 - `timezone: optional string or null`
1978
1979 IANA timezone identifier, e.g. "America/Los_Angeles".
1980
1981 minLength: 1, maxLength: 255
1982
1983 - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig`
1984
1985 Resolved default configuration for agent tools.
1986
1987 - `enabled: boolean`
1988
1989 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
1990
1991 Permission policy for tool execution.
1992
1993 - `BetaManagedAgentsAlwaysAllowPolicy object`
1994
1995 Tool calls are automatically approved without user confirmation.
1996
1997 - `BetaManagedAgentsAlwaysAskPolicy object`
1998
1999 Tool calls require user confirmation before execution.
2000
2001 - `type: "agent_toolset_20260401"`
2002
2003 - `BetaManagedAgentsMCPToolset object`
2004
2005 - `configs: array of BetaManagedAgentsMCPToolConfig`
2006
2007 - `enabled: boolean`
2008
2009 - `name: string`
2010
2011 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
2012
2013 Permission policy for tool execution.
2014
2015 - `BetaManagedAgentsAlwaysAllowPolicy object`
2016
2017 Tool calls are automatically approved without user confirmation.
2018
2019 - `BetaManagedAgentsAlwaysAskPolicy object`
2020
2021 Tool calls require user confirmation before execution.
2022
2023 - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig`
2024
2025 Resolved default configuration for all tools from an MCP server.
2026
2027 - `enabled: boolean`
2028
2029 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
2030
2031 Permission policy for tool execution.
2032
2033 - `BetaManagedAgentsAlwaysAllowPolicy object`
2034
2035 Tool calls are automatically approved without user confirmation.
2036
2037 - `BetaManagedAgentsAlwaysAskPolicy object`
2038
2039 Tool calls require user confirmation before execution.
2040
2041 - `mcp_server_name: string`
2042
2043 - `type: "mcp_toolset"`
2044
2045 - `BetaManagedAgentsCustomTool object`
2046
2047 A custom tool as returned in API responses.
2048
2049 - `description: string`
2050
2051 - `input_schema: BetaManagedAgentsCustomToolInputSchema`
2052
2053 JSON Schema for custom tool input parameters.
2054
2055 - `type: "object"`
2056
2057 - `properties: optional map[unknown] or null`
2058
2059 - `required: optional array of string or null`
2060
2061 - `name: string`
2062
2063 - `type: "custom"`
2064
2065 - `type: "agent"`
2066
2067 - `version: number`
2068
2069 format: int32
2070
2071 - `BetaManagedAgentsAdvisor object`
2072
2073 Platform advisor roster entry: a model the session's primary thread may consult mid-turn.
2074
2075 - `model: string`
2076
2077 The advisor model id.
2078
2079 - `type: "advisor"`
2080
2081 - `type: "coordinator"`
2082
2083 - `name: string`
2084
2085 - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill`
2086
2087 - `BetaManagedAgentsAnthropicSkill object`
2088
2089 A resolved Anthropic-managed skill.
2090
2091 - `BetaManagedAgentsCustomSkill object`
2092
2093 A resolved user-created custom skill.
2094
2095 - `system: string or null`
2096
2097 - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool`
2098
2099 - `BetaManagedAgentsAgentToolset20260401 object`
2100
2101 - `BetaManagedAgentsMCPToolset object`
2102
2103 - `BetaManagedAgentsCustomTool object`
2104
2105 A custom tool as returned in API responses.
2106
2107 - `type: "agent"`
2108
2109 - `version: number`
2110
2111 format: int32
2112
2113 - `budget: optional BetaManagedAgentsBudgetLimit or null`
2114
2115 A hard spend ceiling. The session stops issuing new model requests once the tracked list cost reaches `max_list_cost`.
2116
2117 - `max_list_cost: BetaMonetaryAmount`
2118
2119 A monetary amount in a specific currency.
2120
2121 - `amount: string`
2122
2123 Amount in minor units of the currency, as an integer decimal string with no leading zeros: "2500" is $25.00 and "50" is fifty cents. A string rather than a number so no float rounding is ever applied.
2124
2125 - `currency: BetaCurrency`
2126
2127 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.
2128
2129 - `type: "limit"`
2130
2131 - `metadata: optional map[string]`
2132
2133 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.
2134
2135 - `title: optional string or null`
2136
2137 The session's new title. Present only when the update changed it.
2138
2139 - `BetaManagedAgentsStartEvent object`
2140
2141 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.
2142
2143 - `event: BetaManagedAgentsStartEventPreview`
2144
2145 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.
2146
2147 - `BetaManagedAgentsAgentMessagePreview object`
2148
2149 - `id: string`
2150
2151 The id the buffered agent.message will carry if it is emitted. Matches the event_id on this preview's event_delta events.
2152
2153 - `type: "agent.message"`
2154
2155 - `BetaManagedAgentsAgentThinkingPreview object`
2156
2157 - `id: string`
2158
2159 The id the buffered agent.thinking will carry if it is emitted. Start-only — no event_delta events follow.
2160
2161 - `type: "agent.thinking"`
2162
2163 - `type: "event_start"`
2164
2165 - `BetaManagedAgentsDeltaEvent object`
2166
2167 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.
2168
2169 - `delta: BetaManagedAgentsDeltaContent`
2170
2171 One fragment of the previewed event. The delta type is named for the previewed event's field it streams into: agent.message events stream content_delta fragments, each a partial element of the content array.
2172
2173 - `content: BetaManagedAgentsTextBlock`
2174
2175 Regular text content.
2176
2177 - `type: "content_delta"`
2178
2179 - `index: optional number`
2180
2181 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.
2182
2183 format: uint32
2184
2185 - `event_id: string`
2186
2187 The id of the event being previewed. Matches event.id on the corresponding event_start and the buffered event that reconciles the preview.
2188
2189 - `type: "event_delta"`
2190
2191 - `BetaManagedAgentsSystemMessageEvent object`
2192
2193 A mid-conversation system message event. Carries system-role content that is appended to the session as a `role: "system"` turn.
2194
2195 - `id: string`
2196
2197 Unique identifier for this event.
2198
2199 - `content: array of BetaManagedAgentsSystemContentBlock`
2200
2201 System content blocks. Text-only.
2202
2203 - `text: string`
2204
2205 The text content.
2206
2207 minLength: 1
2208
2209 - `type: "text"`
2210
2211 - `type: "system.message"`
2212
2213 - `processed_at: optional string or null`
2214
2215 A timestamp in RFC 3339 format
2216
2217 format: date-time
2218
22192334 - `BetaManagedAgentsSessionUsageEvent object`
22202335
22212336 Periodic snapshot of the session's cumulative usage and tracked list cost.
22222337
2223 - `id: string`
2224
2225 Unique identifier for this event.
2226
2227 - `processed_at: string`
2228
2229 A timestamp in RFC 3339 format
2230
2231 format: date-time
2232
22332338 - `type: "session.usage"`
2339
2340 - `id: string`
2341
2342 Unique identifier for this event.
2343
2344 - `processed_at: string`
2345
2346 A timestamp in RFC 3339 format
2347
2348 format: date-time
22342349
22352350 - `usage: BetaManagedAgentsSessionUsageSnapshot`
22362351
22372352
api/beta/sessions/list Changed · +386 / -331 lines
from line 1
1---
2title: List Sessions
3url: https://platform.claude.com/docs/en/api/beta/sessions/list
4---
5
16# List Sessions
27
38**GET** `/v1/sessions`
from line 95
9095
9196 - `string`
9297
93 - `"message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 41 more`
98 - `"message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 42 more`
9499
95100 - `"message-batches-2024-09-24"`
96101
from line 143
138143
139144 - `"user-profiles-2026-08-18"`
140145
146 - `"user-profiles-2026-09-04"`
147
141148 - `"advisor-tool-2026-03-01"`
142149
143150 - `"managed-agents-2026-04-01"`
from line 187
180187
181188 - `"mid-conversation-system-clear-at-2026-08-21"`
182189
190- `"anthropic-workspace-id": optional string`
191
183192## Returns
184193
185194- `data: optional array of BetaManagedAgentsSession`
from line 195
186195
187196 List of sessions.
188197
198 - `type: "session"`
199
189200 - `id: string`
190201
191202 - `agent: BetaManagedAgentsSessionAgent`
from line 203
192203
193204 Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time.
194205
206 - `type: "agent"`
207
195208 - `id: string`
196209
197210 - `description: string or null`
from line 211
198211
199212 - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition`
200213
201 - `name: string`
202
203214 - `type: "url"`
204215
216 - `name: string`
217
205218 - `url: string`
206219
207220 - `model: BetaManagedAgentsModelConfig`
from line 341
328341
329342 Resolved coordinator topology with full agent definitions for each roster member.
330343
344 - `type: "coordinator"`
345
331346 - `agents: array of BetaManagedAgentsSessionThreadAgent or BetaManagedAgentsAdvisor`
332347
333348 Full `agent` definitions the coordinator may spawn as session threads.
from line 351
336351
337352 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`.
338353
354 - `type: "agent"`
355
339356 - `id: string`
340357
341358 - `description: string or null`
from line 359
342359
343360 - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition`
344361
345 - `name: string`
346
347362 - `type: "url"`
348363
364 - `name: string`
365
349366 - `url: string`
350367
351368 - `model: BetaManagedAgentsModelConfig`
from line 377
360377
361378 A resolved Anthropic-managed skill.
362379
363 - `skill_id: string`
364
365380 - `type: "anthropic"`
366381
382 - `skill_id: string`
383
367384 - `version: string`
368385
369386 - `BetaManagedAgentsCustomSkill object`
from line 387
370387
371388 A resolved user-created custom skill.
372389
373 - `skill_id: string`
374
375390 - `type: "custom"`
376391
392 - `skill_id: string`
393
377394 - `version: string`
378395
379396 - `system: string or null`
from line 399
382399
383400 - `BetaManagedAgentsAgentToolset20260401 object`
384401
402 - `type: "agent_toolset_20260401"`
403
385404 - `configs: array of BetaManagedAgentsAgentToolConfig`
386405
387406 - `BetaManagedAgentsBashToolConfig object`
from line 407
388407
389408 Configuration for the bash tool.
390409
410 - `type: "bash"`
411
391412 - `enabled: boolean`
392413
393414 - `name: "bash"`
394415
395 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
416 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
396417
397418 Permission policy for tool execution.
398419
from line 429
408429
409430 - `type: "always_ask"`
410431
411 - `type: "bash"`
432 - `BetaManagedAgentsAutoPolicy object`
412433
434 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
435
436 - `type: "auto"`
437
413438 - `BetaManagedAgentsEditToolConfig object`
414439
415440 Configuration for the edit tool.
416441
442 - `type: "edit"`
443
417444 - `enabled: boolean`
418445
419446 - `name: "edit"`
420447
421 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
448 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
422449
423450 Permission policy for tool execution.
424451
from line 457
430457
431458 Tool calls require user confirmation before execution.
432459
433 - `type: "edit"`
460 - `BetaManagedAgentsAutoPolicy object`
434461
462 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
463
435464 - `BetaManagedAgentsReadToolConfig object`
436465
437466 Configuration for the read tool.
438467
468 - `type: "read"`
469
439470 - `enabled: boolean`
440471
441472 - `name: "read"`
442473
443 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
474 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
444475
445476 Permission policy for tool execution.
446477
from line 483
452483
453484 Tool calls require user confirmation before execution.
454485
455 - `type: "read"`
486 - `BetaManagedAgentsAutoPolicy object`
456487
488 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
489
457490 - `BetaManagedAgentsWriteToolConfig object`
458491
459492 Configuration for the write tool.
460493
494 - `type: "write"`
495
461496 - `enabled: boolean`
462497
463498 - `name: "write"`
464499
465 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
500 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
466501
467502 Permission policy for tool execution.
468503
from line 509
474509
475510 Tool calls require user confirmation before execution.
476511
477 - `type: "write"`
512 - `BetaManagedAgentsAutoPolicy object`
478513
514 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
515
479516 - `BetaManagedAgentsGlobToolConfig object`
480517
481518 Configuration for the glob tool.
482519
520 - `type: "glob"`
521
483522 - `enabled: boolean`
484523
485524 - `name: "glob"`
486525
487 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
526 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
488527
489528 Permission policy for tool execution.
490529
from line 535
496535
497536 Tool calls require user confirmation before execution.
498537
499 - `type: "glob"`
538 - `BetaManagedAgentsAutoPolicy object`
500539
540 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
541
501542 - `BetaManagedAgentsGrepToolConfig object`
502543
503544 Configuration for the grep tool.
504545
546 - `type: "grep"`
547
505548 - `enabled: boolean`
506549
507550 - `name: "grep"`
508551
509 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
552 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
510553
511554 Permission policy for tool execution.
512555
from line 561
518561
519562 Tool calls require user confirmation before execution.
520563
521 - `type: "grep"`
564 - `BetaManagedAgentsAutoPolicy object`
522565
566 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
567
523568 - `BetaManagedAgentsWebFetchToolConfig object`
524569
525570 Configuration for the web_fetch tool.
526571
572 - `type: "web_fetch"`
573
527574 - `enabled: boolean`
528575
529576 - `name: "web_fetch"`
530577
531 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
578 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
532579
533580 Permission policy for tool execution.
534581
from line 587
540587
541588 Tool calls require user confirmation before execution.
542589
543 - `type: "web_fetch"`
590 - `BetaManagedAgentsAutoPolicy object`
544591
592 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
593
545594 - `allowed_domains: optional array of string`
546595
547596 - `blocked_domains: optional array of string`
from line 603
554603
555604 Configuration for the web_search tool.
556605
606 - `type: "web_search"`
607
557608 - `enabled: boolean`
558609
559610 - `name: "web_search"`
560611
561 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
612 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
562613
563614 Permission policy for tool execution.
564615
from line 621
570621
571622 Tool calls require user confirmation before execution.
572623
573 - `type: "web_search"`
624 - `BetaManagedAgentsAutoPolicy object`
574625
626 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
627
575628 - `allowed_domains: optional array of string`
576629
577630 - `blocked_domains: optional array of string`
from line 665
612665
613666 - `enabled: boolean`
614667
615 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
668 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
616669
617670 Permission policy for tool execution.
618671
from line 677
624677
625678 Tool calls require user confirmation before execution.
626679
627 - `type: "agent_toolset_20260401"`
680 - `BetaManagedAgentsAutoPolicy object`
628681
682 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
683
629684 - `BetaManagedAgentsMCPToolset object`
630685
686 - `type: "mcp_toolset"`
687
631688 - `configs: array of BetaManagedAgentsMCPToolConfig`
632689
633690 - `enabled: boolean`
from line 691
634691
635692 - `name: string`
636693
637 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
694 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
638695
639696 Permission policy for tool execution.
640697
from line 703
646703
647704 Tool calls require user confirmation before execution.
648705
706 - `BetaManagedAgentsAutoPolicy object`
707
708 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
709
649710 - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig`
650711
651712 Resolved default configuration for all tools from an MCP server.
from line 713
652713
653714 - `enabled: boolean`
654715
655 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
716 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
656717
657718 Permission policy for tool execution.
658719
from line 725
664725
665726 Tool calls require user confirmation before execution.
666727
667 - `mcp_server_name: string`
728 - `BetaManagedAgentsAutoPolicy object`
668729
669 - `type: "mcp_toolset"`
730 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
670731
732 - `mcp_server_name: string`
733
671734 - `BetaManagedAgentsCustomTool object`
672735
673736 A custom tool as returned in API responses.
674737
738 - `type: "custom"`
739
675740 - `description: string`
676741
677742 - `input_schema: BetaManagedAgentsCustomToolInputSchema`
from line 751
686751
687752 - `name: string`
688753
689 - `type: "custom"`
690
691 - `type: "agent"`
692
693754 - `version: number`
694755
695756 format: int32
from line 759
698759
699760 Platform advisor roster entry: a model the session's primary thread may consult mid-turn.
700761
762 - `type: "advisor"`
763
701764 - `model: string`
702765
703766 The advisor model id.
704767
705 - `type: "advisor"`
706
707 - `type: "coordinator"`
708
709768 - `name: string`
710769
711770 - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill`
from line 789
730789
731790 A custom tool as returned in API responses.
732791
733 - `type: "agent"`
734
735792 - `version: number`
736793
737794 format: int32
from line 803
746803
747804 A hard spend ceiling. The session stops issuing new model requests once the tracked list cost reaches `max_list_cost`.
748805
806 - `type: "limit"`
807
749808 - `max_list_cost: BetaMonetaryAmount`
750809
751810 A monetary amount in a specific currency.
from line 817
758817
759818 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.
760819
761 - `type: "limit"`
762
763820 - `created_at: string`
764821
765822 A timestamp in RFC 3339 format
from line 831
774831
775832 Per-outcome evaluation state. One entry per `define_outcome` event sent to the session.
776833
834 - `type: "outcome_evaluation"`
835
777836 - `completed_at: string or null`
778837
779838 A timestamp in RFC 3339 format
from line 861
802861
803862 Current evaluation state. `pending` before the agent begins work; `running` while producing or revising; `evaluating` while the grader scores; `satisfied`/`max_iterations_reached`/`failed`/`interrupted` are terminal.
804863
805 - `type: "outcome_evaluation"`
806
807864 - `resources: array of BetaManagedAgentsSessionResource`
808865
809866 - `BetaManagedAgentsGitHubRepositoryResource object`
810867
868 - `type: "github_repository"`
869
811870 - `id: string`
812871
813872 - `created_at: string`
from line 877
818877
819878 - `mount_path: string`
820879
821 - `type: "github_repository"`
822
823880 - `updated_at: string`
824881
825882 A timestamp in RFC 3339 format
from line 889
832889
833890 - `BetaManagedAgentsBranchCheckout object`
834891
892 - `type: "branch"`
893
835894 - `name: string`
836895
837896 Branch name to check out.
from line 897
838897
839898 minLength: 1, maxLength: 255
840899
841 - `type: "branch"`
842
843900 - `BetaManagedAgentsCommitCheckout object`
844901
902 - `type: "commit"`
903
845904 - `sha: string`
846905
847906 Full commit SHA to check out.
from line 907
848907
849908 minLength: 7, maxLength: 64
850909
851 - `type: "commit"`
852
853910 - `BetaManagedAgentsFileResource object`
854911
912 - `type: "file"`
913
855914 - `id: string`
856915
857916 - `created_at: string`
from line 923
864923
865924 - `mount_path: string`
866925
867 - `type: "file"`
868
869926 - `updated_at: string`
870927
871928 A timestamp in RFC 3339 format
from line 933
876933
877934 A memory store attached to an agent session.
878935
936 - `type: "memory_store"`
937
879938 - `memory_store_id: string`
880939
881940 The memory store ID (memstore_...). Must belong to the caller's organization and workspace.
882941
883 - `type: "memory_store"`
884
885942 - `access: optional "read_write" or "read_only" or null`
886943
887944 Access mode for an attached memory store.
from line 994
937994 - `"terminated"`
938995
939996 - `title: string or null`
940
941 - `type: "session"`
942997
943998 - `updated_at: string`
944999
api/beta/sessions/resources Changed · +298 / -273 lines
from line 1
1---
2title: Resources
3url: https://platform.claude.com/docs/en/api/beta/sessions/resources
4---
5
16# Resources
27
38## Add Session Resource
from line 23
1823
1924 - `string`
2025
21 - `"message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 41 more`
26 - `"message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 42 more`
2227
2328 - `"message-batches-2024-09-24"`
2429
from line 71
6671
6772 - `"user-profiles-2026-08-18"`
6873
74 - `"user-profiles-2026-09-04"`
75
6976 - `"advisor-tool-2026-03-01"`
7077
7178 - `"managed-agents-2026-04-01"`
from line 115
108115
109116 - `"mid-conversation-system-clear-at-2026-08-21"`
110117
118- `"anthropic-workspace-id": optional string`
119
111120### Body parameters
112121
113122- `file_id: string`
from line 137
128137
129138- `BetaManagedAgentsFileResource object`
130139
140 - `type: "file"`
141
131142 - `id: string`
132143
133144 - `created_at: string`
from line 151
140151
141152 - `mount_path: string`
142153
143 - `type: "file"`
144
145154 - `updated_at: string`
146155
147156 A timestamp in RFC 3339 format
from line 215
206215
207216 - `string`
208217
209 - `"message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 41 more`
218 - `"message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 42 more`
210219
211220 - `"message-batches-2024-09-24"`
212221
from line 263
254263
255264 - `"user-profiles-2026-08-18"`
256265
266 - `"user-profiles-2026-09-04"`
267
257268 - `"advisor-tool-2026-03-01"`
258269
259270 - `"managed-agents-2026-04-01"`
from line 307
296307
297308 - `"mid-conversation-system-clear-at-2026-08-21"`
298309
310- `"anthropic-workspace-id": optional string`
311
299312### Returns
300313
301314- `data: array of BetaManagedAgentsSessionResource`
from line 317
304317
305318 - `BetaManagedAgentsGitHubRepositoryResource object`
306319
320 - `type: "github_repository"`
321
307322 - `id: string`
308323
309324 - `created_at: string`
from line 329
314329
315330 - `mount_path: string`
316331
317 - `type: "github_repository"`
318
319332 - `updated_at: string`
320333
321334 A timestamp in RFC 3339 format
from line 341
328341
329342 - `BetaManagedAgentsBranchCheckout object`
330343
344 - `type: "branch"`
345
331346 - `name: string`
332347
333348 Branch name to check out.
from line 349
334349
335350 minLength: 1, maxLength: 255
336351
337 - `type: "branch"`
338
339352 - `BetaManagedAgentsCommitCheckout object`
340353
354 - `type: "commit"`
355
341356 - `sha: string`
342357
343358 Full commit SHA to check out.
from line 359
344359
345360 minLength: 7, maxLength: 64
346361
347 - `type: "commit"`
348
349362 - `BetaManagedAgentsFileResource object`
350363
364 - `type: "file"`
365
351366 - `id: string`
352367
353368 - `created_at: string`
from line 375
360375
361376 - `mount_path: string`
362377
363 - `type: "file"`
364
365378 - `updated_at: string`
366379
367380 A timestamp in RFC 3339 format
from line 385
372385
373386 A memory store attached to an agent session.
374387
388 - `type: "memory_store"`
389
375390 - `memory_store_id: string`
376391
377392 The memory store ID (memstore_...). Must belong to the caller's organization and workspace.
378393
379 - `type: "memory_store"`
380
381394 - `access: optional "read_write" or "read_only" or null`
382395
383396 Access mode for an attached memory store.
from line 480
467480
468481 - `string`
469482
470 - `"message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 41 more`
483 - `"message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 42 more`
471484
472485 - `"message-batches-2024-09-24"`
473486
from line 528
515528
516529 - `"user-profiles-2026-08-18"`
517530
531 - `"user-profiles-2026-09-04"`
532
518533 - `"advisor-tool-2026-03-01"`
519534
520535 - `"managed-agents-2026-04-01"`
from line 572
557572
558573 - `"mid-conversation-system-clear-at-2026-08-21"`
559574
575- `"anthropic-workspace-id": optional string`
576
560577### Returns
561578
562579- `BetaManagedAgentsGitHubRepositoryResource object`
563580
581 - `type: "github_repository"`
582
564583 - `id: string`
565584
566585 - `created_at: string`
from line 590
571590
572591 - `mount_path: string`
573592
574 - `type: "github_repository"`
575
576593 - `updated_at: string`
577594
578595 A timestamp in RFC 3339 format
from line 602
585602
586603 - `BetaManagedAgentsBranchCheckout object`
587604
605 - `type: "branch"`
606
588607 - `name: string`
589608
590609 Branch name to check out.
from line 610
591610
592611 minLength: 1, maxLength: 255
593612
594 - `type: "branch"`
595
596613 - `BetaManagedAgentsCommitCheckout object`
597614
615 - `type: "commit"`
616
598617 - `sha: string`
599618
600619 Full commit SHA to check out.
from line 620
601620
602621 minLength: 7, maxLength: 64
603622
604 - `type: "commit"`
605
606623- `BetaManagedAgentsFileResource object`
607624
625 - `type: "file"`
626
608627 - `id: string`
609628
610629 - `created_at: string`
from line 636
617636
618637 - `mount_path: string`
619638
620 - `type: "file"`
621
622639 - `updated_at: string`
623640
624641 A timestamp in RFC 3339 format
from line 646
629646
630647 A memory store attached to an agent session.
631648
649 - `type: "memory_store"`
650
632651 - `memory_store_id: string`
633652
634653 The memory store ID (memstore_...). Must belong to the caller's organization and workspace.
635654
636 - `type: "memory_store"`
637
638655 - `access: optional "read_write" or "read_only" or null`
639656
640657 Access mode for an attached memory store.
from line 724
707724
708725 - `string`
709726
710 - `"message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 41 more`
727 - `"message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 42 more`
711728
712729 - `"message-batches-2024-09-24"`
713730
from line 772
755772
756773 - `"user-profiles-2026-08-18"`
757774
775 - `"user-profiles-2026-09-04"`
776
758777 - `"advisor-tool-2026-03-01"`
759778
760779 - `"managed-agents-2026-04-01"`
from line 816
797816
798817 - `"mid-conversation-system-clear-at-2026-08-21"`
799818
819- `"anthropic-workspace-id": optional string`
820
800821### Body parameters
801822
802823- `authorization_token: string`
from line 830
809830
810831- `BetaManagedAgentsGitHubRepositoryResource object`
811832
833 - `type: "github_repository"`
834
812835 - `id: string`
813836
814837 - `created_at: string`
from line 842
819842
820843 - `mount_path: string`
821844
822 - `type: "github_repository"`
823
824845 - `updated_at: string`
825846
826847 A timestamp in RFC 3339 format
from line 854
833854
834855 - `BetaManagedAgentsBranchCheckout object`
835856
857 - `type: "branch"`
858
836859 - `name: string`
837860
838861 Branch name to check out.
from line 862
839862
840863 minLength: 1, maxLength: 255
841864
842 - `type: "branch"`
843
844865 - `BetaManagedAgentsCommitCheckout object`
845866
867 - `type: "commit"`
868
846869 - `sha: string`
847870
848871 Full commit SHA to check out.
from line 872
849872
850873 minLength: 7, maxLength: 64
851874
852 - `type: "commit"`
853
854875- `BetaManagedAgentsFileResource object`
855876
877 - `type: "file"`
878
856879 - `id: string`
857880
858881 - `created_at: string`
from line 888
865888
866889 - `mount_path: string`
867890
868 - `type: "file"`
869
870891 - `updated_at: string`
871892
872893 A timestamp in RFC 3339 format
from line 898
877898
878899 A memory store attached to an agent session.
879900
901 - `type: "memory_store"`
902
880903 - `memory_store_id: string`
881904
882905 The memory store ID (memstore_...). Must belong to the caller's organization and workspace.
883906
884 - `type: "memory_store"`
885
886907 - `access: optional "read_write" or "read_only" or null`
887908
888909 Access mode for an attached memory store.
from line 980
959980
960981 - `string`
961982
962 - `"message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 41 more`
983 - `"message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 42 more`
963984
964985 - `"message-batches-2024-09-24"`
965986
from line 1028
10071028
10081029 - `"user-profiles-2026-08-18"`
10091030
1031 - `"user-profiles-2026-09-04"`
1032
10101033 - `"advisor-tool-2026-03-01"`
10111034
10121035 - `"managed-agents-2026-04-01"`
from line 1072
10491072
10501073 - `"mid-conversation-system-clear-at-2026-08-21"`
10511074
1075- `"anthropic-workspace-id": optional string`
1076
10521077### Returns
10531078
10541079- `BetaManagedAgentsDeleteSessionResource object`
from line 1080
10551080
10561081 Confirmation of resource deletion.
10571082
1058 - `id: string`
1059
10601083 - `type: "session_resource_deleted"`
10611084
1085 - `id: string`
1086
10621087### Example
10631088
10641089```bash
from line 1111
10861111
10871112 Confirmation of resource deletion.
10881113
1089 - `id: string`
1090
10911114 - `type: "session_resource_deleted"`
10921115
1116 - `id: string`
1117
10931118### Beta Managed Agents File Resource
10941119
10951120- `BetaManagedAgentsFileResource object`
10961121
1122 - `type: "file"`
1123
10971124 - `id: string`
10981125
10991126 - `created_at: string`
from line 1133
11061133
11071134 - `mount_path: string`
11081135
1109 - `type: "file"`
1110
11111136 - `updated_at: string`
11121137
11131138 A timestamp in RFC 3339 format
from line 1143
11181143
11191144- `BetaManagedAgentsGitHubRepositoryResource object`
11201145
1146 - `type: "github_repository"`
1147
11211148 - `id: string`
11221149
11231150 - `created_at: string`
from line 1155
11281155
11291156 - `mount_path: string`
11301157
1131 - `type: "github_repository"`
1132
11331158 - `updated_at: string`
11341159
11351160 A timestamp in RFC 3339 format
from line 1167
11421167
11431168 - `BetaManagedAgentsBranchCheckout object`
11441169
1170 - `type: "branch"`
1171
11451172 - `name: string`
11461173
11471174 Branch name to check out.
from line 1175
11481175
11491176 minLength: 1, maxLength: 255
11501177
1151 - `type: "branch"`
1152
11531178 - `BetaManagedAgentsCommitCheckout object`
11541179
1180 - `type: "commit"`
1181
11551182 - `sha: string`
11561183
11571184 Full commit SHA to check out.
from line 1185
11581185
11591186 minLength: 7, maxLength: 64
11601187
1161 - `type: "commit"`
1162
11631188### Beta Managed Agents Memory Store Resource
11641189
11651190- `BetaManagedAgentsMemoryStoreResource object`
from line 1191
11661191
11671192 A memory store attached to an agent session.
11681193
1194 - `type: "memory_store"`
1195
11691196 - `memory_store_id: string`
11701197
11711198 The memory store ID (memstore_...). Must belong to the caller's organization and workspace.
11721199
1173 - `type: "memory_store"`
1174
11751200 - `access: optional "read_write" or "read_only" or null`
11761201
11771202 Access mode for an attached memory store.
from line 1231
12061231
12071232 - `BetaManagedAgentsGitHubRepositoryResource object`
12081233
1234 - `type: "github_repository"`
1235
12091236 - `id: string`
12101237
12111238 - `created_at: string`
from line 1243
12161243
12171244 - `mount_path: string`
12181245
1219 - `type: "github_repository"`
1220
12211246 - `updated_at: string`
12221247
12231248 A timestamp in RFC 3339 format
from line 1255
12301255
12311256 - `BetaManagedAgentsBranchCheckout object`
12321257
1258 - `type: "branch"`
1259
12331260 - `name: string`
12341261
12351262 Branch name to check out.
from line 1263
12361263
12371264 minLength: 1, maxLength: 255
12381265
1239 - `type: "branch"`
1240
12411266 - `BetaManagedAgentsCommitCheckout object`
12421267
1268 - `type: "commit"`
1269
12431270 - `sha: string`
12441271
12451272 Full commit SHA to check out.
from line 1273
12461273
12471274 minLength: 7, maxLength: 64
12481275
1249 - `type: "commit"`
1250
12511276 - `BetaManagedAgentsFileResource object`
12521277
1278 - `type: "file"`
1279
12531280 - `id: string`
12541281
12551282 - `created_at: string`
from line 1289
12621289
12631290 - `mount_path: string`
12641291
1265 - `type: "file"`
1266
12671292 - `updated_at: string`
12681293
12691294 A timestamp in RFC 3339 format
from line 1299
12741299
12751300 A memory store attached to an agent session.
12761301
1302 - `type: "memory_store"`
1303
12771304 - `memory_store_id: string`
12781305
12791306 The memory store ID (memstore_...). Must belong to the caller's organization and workspace.
12801307
1281 - `type: "memory_store"`
1282
12831308 - `access: optional "read_write" or "read_only" or null`
12841309
12851310 Access mode for an attached memory store.
from line 1339
13141339
13151340 - `BetaManagedAgentsGitHubRepositoryResource object`
13161341
1342 - `type: "github_repository"`
1343
13171344 - `id: string`
13181345
13191346 - `created_at: string`
from line 1351
13241351
13251352 - `mount_path: string`
13261353
1327 - `type: "github_repository"`
1328
13291354 - `updated_at: string`
13301355
13311356 A timestamp in RFC 3339 format
from line 1363
13381363
13391364 - `BetaManagedAgentsBranchCheckout object`
13401365
1366 - `type: "branch"`
1367
13411368 - `name: string`
13421369
13431370 Branch name to check out.
from line 1371
13441371
13451372 minLength: 1, maxLength: 255
13461373
1347 - `type: "branch"`
1348
13491374 - `BetaManagedAgentsCommitCheckout object`
13501375
1376 - `type: "commit"`
1377
13511378 - `sha: string`
13521379
13531380 Full commit SHA to check out.
from line 1381
13541381
13551382 minLength: 7, maxLength: 64
13561383
1357 - `type: "commit"`
1358
13591384 - `BetaManagedAgentsFileResource object`
13601385
1386 - `type: "file"`
1387
13611388 - `id: string`
13621389
13631390 - `created_at: string`
from line 1397
13701397
13711398 - `mount_path: string`
13721399
1373 - `type: "file"`
1374
13751400 - `updated_at: string`
13761401
13771402 A timestamp in RFC 3339 format
from line 1407
13821407
13831408 A memory store attached to an agent session.
13841409
1410 - `type: "memory_store"`
1411
13851412 - `memory_store_id: string`
13861413
13871414 The memory store ID (memstore_...). Must belong to the caller's organization and workspace.
13881415
1389 - `type: "memory_store"`
1390
13911416 - `access: optional "read_write" or "read_only" or null`
13921417
13931418 Access mode for an attached memory store.
from line 1447
14221447
14231448 - `BetaManagedAgentsGitHubRepositoryResource object`
14241449
1450 - `type: "github_repository"`
1451
14251452 - `id: string`
14261453
14271454 - `created_at: string`
from line 1459
14321459
14331460 - `mount_path: string`
14341461
1435 - `type: "github_repository"`
1436
14371462 - `updated_at: string`
14381463
14391464 A timestamp in RFC 3339 format
from line 1471
14461471
14471472 - `BetaManagedAgentsBranchCheckout object`
14481473
1474 - `type: "branch"`
1475
14491476 - `name: string`
14501477
14511478 Branch name to check out.
from line 1479
14521479
14531480 minLength: 1, maxLength: 255
14541481
1455 - `type: "branch"`
1456
14571482 - `BetaManagedAgentsCommitCheckout object`
14581483
1484 - `type: "commit"`
1485
14591486 - `sha: string`
14601487
14611488 Full commit SHA to check out.
from line 1489
14621489
14631490 minLength: 7, maxLength: 64
14641491
1465 - `type: "commit"`
1466
14671492 - `BetaManagedAgentsFileResource object`
14681493
1494 - `type: "file"`
1495
14691496 - `id: string`
14701497
14711498 - `created_at: string`
from line 1505
14781505
14791506 - `mount_path: string`
14801507
1481 - `type: "file"`
1482
14831508 - `updated_at: string`
14841509
14851510 A timestamp in RFC 3339 format
from line 1515
14901515
14911516 A memory store attached to an agent session.
14921517
1518 - `type: "memory_store"`
1519
14931520 - `memory_store_id: string`
14941521
14951522 The memory store ID (memstore_...). Must belong to the caller's organization and workspace.
1496
1497 - `type: "memory_store"`
14981523
14991524 - `access: optional "read_write" or "read_only" or null`
15001525
api/beta/sessions/resources/add Changed · +12 / -3 lines
from line 1
1---
2title: Add Session Resource
3url: https://platform.claude.com/docs/en/api/beta/sessions/resources/add
4---
5
16# Add Session Resource
27
38**POST** `/v1/sessions/{session_id}/resources`
from line 21
1621
1722 - `string`
1823
19 - `"message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 41 more`
24 - `"message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 42 more`
2025
2126 - `"message-batches-2024-09-24"`
2227
from line 69
6469
6570 - `"user-profiles-2026-08-18"`
6671
72 - `"user-profiles-2026-09-04"`
73
6774 - `"advisor-tool-2026-03-01"`
6875
6976 - `"managed-agents-2026-04-01"`
from line 113
106113
107114 - `"mid-conversation-system-clear-at-2026-08-21"`
108115
116- `"anthropic-workspace-id": optional string`
117
109118## Body parameters
110119
111120- `file_id: string`
from line 135
126135
127136- `BetaManagedAgentsFileResource object`
128137
138 - `type: "file"`
139
129140 - `id: string`
130141
131142 - `created_at: string`
from line 148
137148 - `file_id: string`
138149
139150 - `mount_path: string`
140
141 - `type: "file"`
142151
143152 - `updated_at: string`
144153
api/beta/sessions/resources/delete Changed · +12 / -3 lines
from line 1
1---
2title: Delete Session Resource
3url: https://platform.claude.com/docs/en/api/beta/sessions/resources/delete
4---
5
16# Delete Session Resource
27
38**DELETE** `/v1/sessions/{session_id}/resources/{resource_id}`
from line 23
1823
1924 - `string`
2025
21 - `"message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 41 more`
26 - `"message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 42 more`
2227
2328 - `"message-batches-2024-09-24"`
2429
from line 71
6671
6772 - `"user-profiles-2026-08-18"`
6873
74 - `"user-profiles-2026-09-04"`
75
6976 - `"advisor-tool-2026-03-01"`
7077
7178 - `"managed-agents-2026-04-01"`
from line 115
108115
109116 - `"mid-conversation-system-clear-at-2026-08-21"`
110117
118- `"anthropic-workspace-id": optional string`
119
111120## Returns
112121
113122- `BetaManagedAgentsDeleteSessionResource object`
from line 123
114123
115124 Confirmation of resource deletion.
116125
117 - `id: string`
118
119126 - `type: "session_resource_deleted"`
127
128 - `id: string`
120129
121130## Example
122131
api/beta/sessions/resources/list Changed · +20 / -11 lines
from line 1
1---
2title: List Session Resources
3url: https://platform.claude.com/docs/en/api/beta/sessions/resources/list
4---
5
16# List Session Resources
27
38**GET** `/v1/sessions/{session_id}/resources`
from line 33
2833
2934 - `string`
3035
31 - `"message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 41 more`
36 - `"message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 42 more`
3237
3338 - `"message-batches-2024-09-24"`
3439
from line 81
7681
7782 - `"user-profiles-2026-08-18"`
7883
84 - `"user-profiles-2026-09-04"`
85
7986 - `"advisor-tool-2026-03-01"`
8087
8188 - `"managed-agents-2026-04-01"`
from line 125
118125
119126 - `"mid-conversation-system-clear-at-2026-08-21"`
120127
128- `"anthropic-workspace-id": optional string`
129
121130## Returns
122131
123132- `data: array of BetaManagedAgentsSessionResource`
from line 135
126135
127136 - `BetaManagedAgentsGitHubRepositoryResource object`
128137
138 - `type: "github_repository"`
139
129140 - `id: string`
130141
131142 - `created_at: string`
from line 147
136147
137148 - `mount_path: string`
138149
139 - `type: "github_repository"`
140
141150 - `updated_at: string`
142151
143152 A timestamp in RFC 3339 format
from line 159
150159
151160 - `BetaManagedAgentsBranchCheckout object`
152161
162 - `type: "branch"`
163
153164 - `name: string`
154165
155166 Branch name to check out.
from line 167
156167
157168 minLength: 1, maxLength: 255
158169
159 - `type: "branch"`
160
161170 - `BetaManagedAgentsCommitCheckout object`
162171
172 - `type: "commit"`
173
163174 - `sha: string`
164175
165176 Full commit SHA to check out.
from line 177
166177
167178 minLength: 7, maxLength: 64
168179
169 - `type: "commit"`
170
171180 - `BetaManagedAgentsFileResource object`
172181
182 - `type: "file"`
183
173184 - `id: string`
174185
175186 - `created_at: string`
from line 193
182193
183194 - `mount_path: string`
184195
185 - `type: "file"`
186
187196 - `updated_at: string`
188197
189198 A timestamp in RFC 3339 format
from line 203
194203
195204 A memory store attached to an agent session.
196205
206 - `type: "memory_store"`
207
197208 - `memory_store_id: string`
198209
199210 The memory store ID (memstore_...). Must belong to the caller's organization and workspace.
200
201 - `type: "memory_store"`
202211
203212 - `access: optional "read_write" or "read_only" or null`
204213
api/beta/sessions/resources/retrieve Changed · +20 / -11 lines
from line 1
1---
2title: Get Session Resource
3url: https://platform.claude.com/docs/en/api/beta/sessions/resources/retrieve
4---
5
16# Get Session Resource
27
38**GET** `/v1/sessions/{session_id}/resources/{resource_id}`
from line 23
1823
1924 - `string`
2025
21 - `"message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 41 more`
26 - `"message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 42 more`
2227
2328 - `"message-batches-2024-09-24"`
2429
from line 71
6671
6772 - `"user-profiles-2026-08-18"`
6873
74 - `"user-profiles-2026-09-04"`
75
6976 - `"advisor-tool-2026-03-01"`
7077
7178 - `"managed-agents-2026-04-01"`
from line 115
108115
109116 - `"mid-conversation-system-clear-at-2026-08-21"`
110117
118- `"anthropic-workspace-id": optional string`
119
111120## Returns
112121
113122- `BetaManagedAgentsGitHubRepositoryResource object`
114123
124 - `type: "github_repository"`
125
115126 - `id: string`
116127
117128 - `created_at: string`
from line 133
122133
123134 - `mount_path: string`
124135
125 - `type: "github_repository"`
126
127136 - `updated_at: string`
128137
129138 A timestamp in RFC 3339 format
from line 145
136145
137146 - `BetaManagedAgentsBranchCheckout object`
138147
148 - `type: "branch"`
149
139150 - `name: string`
140151
141152 Branch name to check out.
from line 153
142153
143154 minLength: 1, maxLength: 255
144155
145 - `type: "branch"`
146
147156 - `BetaManagedAgentsCommitCheckout object`
148157
158 - `type: "commit"`
159
149160 - `sha: string`
150161
151162 Full commit SHA to check out.
from line 163
152163
153164 minLength: 7, maxLength: 64
154165
155 - `type: "commit"`
156
157166- `BetaManagedAgentsFileResource object`
158167
168 - `type: "file"`
169
159170 - `id: string`
160171
161172 - `created_at: string`
from line 179
168179
169180 - `mount_path: string`
170181
171 - `type: "file"`
172
173182 - `updated_at: string`
174183
175184 A timestamp in RFC 3339 format
from line 189
180189
181190 A memory store attached to an agent session.
182191
192 - `type: "memory_store"`
193
183194 - `memory_store_id: string`
184195
185196 The memory store ID (memstore_...). Must belong to the caller's organization and workspace.
186
187 - `type: "memory_store"`
188197
189198 - `access: optional "read_write" or "read_only" or null`
190199
api/beta/sessions/resources/update Changed · +20 / -11 lines
from line 1
1---
2title: Update Session Resource
3url: https://platform.claude.com/docs/en/api/beta/sessions/resources/update
4---
5
16# Update Session Resource
27
38**POST** `/v1/sessions/{session_id}/resources/{resource_id}`
from line 23
1823
1924 - `string`
2025
21 - `"message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 41 more`
26 - `"message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 42 more`
2227
2328 - `"message-batches-2024-09-24"`
2429
from line 71
6671
6772 - `"user-profiles-2026-08-18"`
6873
74 - `"user-profiles-2026-09-04"`
75
6976 - `"advisor-tool-2026-03-01"`
7077
7178 - `"managed-agents-2026-04-01"`
from line 115
108115
109116 - `"mid-conversation-system-clear-at-2026-08-21"`
110117
118- `"anthropic-workspace-id": optional string`
119
111120## Body parameters
112121
113122- `authorization_token: string`
from line 129
120129
121130- `BetaManagedAgentsGitHubRepositoryResource object`
122131
132 - `type: "github_repository"`
133
123134 - `id: string`
124135
125136 - `created_at: string`
from line 141
130141
131142 - `mount_path: string`
132143
133 - `type: "github_repository"`
134
135144 - `updated_at: string`
136145
137146 A timestamp in RFC 3339 format
from line 153
144153
145154 - `BetaManagedAgentsBranchCheckout object`
146155
156 - `type: "branch"`
157
147158 - `name: string`
148159
149160 Branch name to check out.
from line 161
150161
151162 minLength: 1, maxLength: 255
152163
153 - `type: "branch"`
154
155164 - `BetaManagedAgentsCommitCheckout object`
156165
166 - `type: "commit"`
167
157168 - `sha: string`
158169
159170 Full commit SHA to check out.
from line 171
160171
161172 minLength: 7, maxLength: 64
162173
163 - `type: "commit"`
164
165174- `BetaManagedAgentsFileResource object`
166175
176 - `type: "file"`
177
167178 - `id: string`
168179
169180 - `created_at: string`
from line 187
176187
177188 - `mount_path: string`
178189
179 - `type: "file"`
180
181190 - `updated_at: string`
182191
183192 A timestamp in RFC 3339 format
from line 197
188197
189198 A memory store attached to an agent session.
190199
200 - `type: "memory_store"`
201
191202 - `memory_store_id: string`
192203
193204 The memory store ID (memstore_...). Must belong to the caller's organization and workspace.
194
195 - `type: "memory_store"`
196205
197206 - `access: optional "read_write" or "read_only" or null`
198207
api/beta/sessions/retrieve Changed · +386 / -331 lines
from line 1
1---
2title: Get Session
3url: https://platform.claude.com/docs/en/api/beta/sessions/retrieve
4---
5
16# Get Session
27
38**GET** `/v1/sessions/{session_id}`
from line 21
1621
1722 - `string`
1823
19 - `"message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 41 more`
24 - `"message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 42 more`
2025
2126 - `"message-batches-2024-09-24"`
2227
from line 69
6469
6570 - `"user-profiles-2026-08-18"`
6671
72 - `"user-profiles-2026-09-04"`
73
6774 - `"advisor-tool-2026-03-01"`
6875
6976 - `"managed-agents-2026-04-01"`
from line 113
106113
107114 - `"mid-conversation-system-clear-at-2026-08-21"`
108115
116- `"anthropic-workspace-id": optional string`
117
109118## Returns
110119
111120- `BetaManagedAgentsSession object`
from line 121
112121
113122 A Managed Agents `session`.
114123
124 - `type: "session"`
125
115126 - `id: string`
116127
117128 - `agent: BetaManagedAgentsSessionAgent`
from line 129
118129
119130 Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time.
120131
132 - `type: "agent"`
133
121134 - `id: string`
122135
123136 - `description: string or null`
from line 137
124137
125138 - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition`
126139
127 - `name: string`
128
129140 - `type: "url"`
130141
142 - `name: string`
143
131144 - `url: string`
132145
133146 - `model: BetaManagedAgentsModelConfig`
from line 267
254267
255268 Resolved coordinator topology with full agent definitions for each roster member.
256269
270 - `type: "coordinator"`
271
257272 - `agents: array of BetaManagedAgentsSessionThreadAgent or BetaManagedAgentsAdvisor`
258273
259274 Full `agent` definitions the coordinator may spawn as session threads.
from line 277
262277
263278 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`.
264279
280 - `type: "agent"`
281
265282 - `id: string`
266283
267284 - `description: string or null`
from line 285
268285
269286 - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition`
270287
271 - `name: string`
272
273288 - `type: "url"`
274289
290 - `name: string`
291
275292 - `url: string`
276293
277294 - `model: BetaManagedAgentsModelConfig`
from line 303
286303
287304 A resolved Anthropic-managed skill.
288305
289 - `skill_id: string`
290
291306 - `type: "anthropic"`
292307
308 - `skill_id: string`
309
293310 - `version: string`
294311
295312 - `BetaManagedAgentsCustomSkill object`
from line 313
296313
297314 A resolved user-created custom skill.
298315
299 - `skill_id: string`
300
301316 - `type: "custom"`
302317
318 - `skill_id: string`
319
303320 - `version: string`
304321
305322 - `system: string or null`
from line 325
308325
309326 - `BetaManagedAgentsAgentToolset20260401 object`
310327
328 - `type: "agent_toolset_20260401"`
329
311330 - `configs: array of BetaManagedAgentsAgentToolConfig`
312331
313332 - `BetaManagedAgentsBashToolConfig object`
from line 333
314333
315334 Configuration for the bash tool.
316335
336 - `type: "bash"`
337
317338 - `enabled: boolean`
318339
319340 - `name: "bash"`
320341
321 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
342 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
322343
323344 Permission policy for tool execution.
324345
from line 355
334355
335356 - `type: "always_ask"`
336357
337 - `type: "bash"`
358 - `BetaManagedAgentsAutoPolicy object`
338359
360 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
361
362 - `type: "auto"`
363
339364 - `BetaManagedAgentsEditToolConfig object`
340365
341366 Configuration for the edit tool.
342367
368 - `type: "edit"`
369
343370 - `enabled: boolean`
344371
345372 - `name: "edit"`
346373
347 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
374 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
348375
349376 Permission policy for tool execution.
350377
from line 383
356383
357384 Tool calls require user confirmation before execution.
358385
359 - `type: "edit"`
386 - `BetaManagedAgentsAutoPolicy object`
360387
388 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
389
361390 - `BetaManagedAgentsReadToolConfig object`
362391
363392 Configuration for the read tool.
364393
394 - `type: "read"`
395
365396 - `enabled: boolean`
366397
367398 - `name: "read"`
368399
369 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
400 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
370401
371402 Permission policy for tool execution.
372403
from line 409
378409
379410 Tool calls require user confirmation before execution.
380411
381 - `type: "read"`
412 - `BetaManagedAgentsAutoPolicy object`
382413
414 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
415
383416 - `BetaManagedAgentsWriteToolConfig object`
384417
385418 Configuration for the write tool.
386419
420 - `type: "write"`
421
387422 - `enabled: boolean`
388423
389424 - `name: "write"`
390425
391 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
426 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
392427
393428 Permission policy for tool execution.
394429
from line 435
400435
401436 Tool calls require user confirmation before execution.
402437
403 - `type: "write"`
438 - `BetaManagedAgentsAutoPolicy object`
404439
440 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
441
405442 - `BetaManagedAgentsGlobToolConfig object`
406443
407444 Configuration for the glob tool.
408445
446 - `type: "glob"`
447
409448 - `enabled: boolean`
410449
411450 - `name: "glob"`
412451
413 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
452 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
414453
415454 Permission policy for tool execution.
416455
from line 461
422461
423462 Tool calls require user confirmation before execution.
424463
425 - `type: "glob"`
464 - `BetaManagedAgentsAutoPolicy object`
426465
466 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
467
427468 - `BetaManagedAgentsGrepToolConfig object`
428469
429470 Configuration for the grep tool.
430471
472 - `type: "grep"`
473
431474 - `enabled: boolean`
432475
433476 - `name: "grep"`
434477
435 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
478 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
436479
437480 Permission policy for tool execution.
438481
from line 487
444487
445488 Tool calls require user confirmation before execution.
446489
447 - `type: "grep"`
490 - `BetaManagedAgentsAutoPolicy object`
448491
492 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
493
449494 - `BetaManagedAgentsWebFetchToolConfig object`
450495
451496 Configuration for the web_fetch tool.
452497
498 - `type: "web_fetch"`
499
453500 - `enabled: boolean`
454501
455502 - `name: "web_fetch"`
456503
457 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
504 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
458505
459506 Permission policy for tool execution.
460507
from line 513
466513
467514 Tool calls require user confirmation before execution.
468515
469 - `type: "web_fetch"`
516 - `BetaManagedAgentsAutoPolicy object`
470517
518 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
519
471520 - `allowed_domains: optional array of string`
472521
473522 - `blocked_domains: optional array of string`
from line 529
480529
481530 Configuration for the web_search tool.
482531
532 - `type: "web_search"`
533
483534 - `enabled: boolean`
484535
485536 - `name: "web_search"`
486537
487 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
538 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
488539
489540 Permission policy for tool execution.
490541
from line 547
496547
497548 Tool calls require user confirmation before execution.
498549
499 - `type: "web_search"`
550 - `BetaManagedAgentsAutoPolicy object`
500551
552 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
553
501554 - `allowed_domains: optional array of string`
502555
503556 - `blocked_domains: optional array of string`
from line 591
538591
539592 - `enabled: boolean`
540593
541 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
594 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
542595
543596 Permission policy for tool execution.
544597
from line 603
550603
551604 Tool calls require user confirmation before execution.
552605
553 - `type: "agent_toolset_20260401"`
606 - `BetaManagedAgentsAutoPolicy object`
554607
608 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
609
555610 - `BetaManagedAgentsMCPToolset object`
556611
612 - `type: "mcp_toolset"`
613
557614 - `configs: array of BetaManagedAgentsMCPToolConfig`
558615
559616 - `enabled: boolean`
from line 617
560617
561618 - `name: string`
562619
563 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
620 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
564621
565622 Permission policy for tool execution.
566623
from line 629
572629
573630 Tool calls require user confirmation before execution.
574631
632 - `BetaManagedAgentsAutoPolicy object`
633
634 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
635
575636 - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig`
576637
577638 Resolved default configuration for all tools from an MCP server.
from line 639
578639
579640 - `enabled: boolean`
580641
581 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
642 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
582643
583644 Permission policy for tool execution.
584645
from line 651
590651
591652 Tool calls require user confirmation before execution.
592653
593 - `mcp_server_name: string`
654 - `BetaManagedAgentsAutoPolicy object`
594655
595 - `type: "mcp_toolset"`
656 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
596657
658 - `mcp_server_name: string`
659
597660 - `BetaManagedAgentsCustomTool object`
598661
599662 A custom tool as returned in API responses.
600663
664 - `type: "custom"`
665
601666 - `description: string`
602667
603668 - `input_schema: BetaManagedAgentsCustomToolInputSchema`
from line 677
612677
613678 - `name: string`
614679
615 - `type: "custom"`
616
617 - `type: "agent"`
618
619680 - `version: number`
620681
621682 format: int32
from line 685
624685
625686 Platform advisor roster entry: a model the session's primary thread may consult mid-turn.
626687
688 - `type: "advisor"`
689
627690 - `model: string`
628691
629692 The advisor model id.
630693
631 - `type: "advisor"`
632
633 - `type: "coordinator"`
634
635694 - `name: string`
636695
637696 - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill`
from line 715
656715
657716 A custom tool as returned in API responses.
658717
659 - `type: "agent"`
660
661718 - `version: number`
662719
663720 format: int32
from line 729
672729
673730 A hard spend ceiling. The session stops issuing new model requests once the tracked list cost reaches `max_list_cost`.
674731
732 - `type: "limit"`
733
675734 - `max_list_cost: BetaMonetaryAmount`
676735
677736 A monetary amount in a specific currency.
from line 743
684743
685744 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.
686745
687 - `type: "limit"`
688
689746 - `created_at: string`
690747
691748 A timestamp in RFC 3339 format
from line 757
700757
701758 Per-outcome evaluation state. One entry per `define_outcome` event sent to the session.
702759
760 - `type: "outcome_evaluation"`
761
703762 - `completed_at: string or null`
704763
705764 A timestamp in RFC 3339 format
from line 787
728787
729788 Current evaluation state. `pending` before the agent begins work; `running` while producing or revising; `evaluating` while the grader scores; `satisfied`/`max_iterations_reached`/`failed`/`interrupted` are terminal.
730789
731 - `type: "outcome_evaluation"`
732
733790 - `resources: array of BetaManagedAgentsSessionResource`
734791
735792 - `BetaManagedAgentsGitHubRepositoryResource object`
736793
794 - `type: "github_repository"`
795
737796 - `id: string`
738797
739798 - `created_at: string`
from line 803
744803
745804 - `mount_path: string`
746805
747 - `type: "github_repository"`
748
749806 - `updated_at: string`
750807
751808 A timestamp in RFC 3339 format
from line 815
758815
759816 - `BetaManagedAgentsBranchCheckout object`
760817
818 - `type: "branch"`
819
761820 - `name: string`
762821
763822 Branch name to check out.
from line 823
764823
765824 minLength: 1, maxLength: 255
766825
767 - `type: "branch"`
768
769826 - `BetaManagedAgentsCommitCheckout object`
770827
828 - `type: "commit"`
829
771830 - `sha: string`
772831
773832 Full commit SHA to check out.
from line 833
774833
775834 minLength: 7, maxLength: 64
776835
777 - `type: "commit"`
778
779836 - `BetaManagedAgentsFileResource object`
780837
838 - `type: "file"`
839
781840 - `id: string`
782841
783842 - `created_at: string`
from line 849
790849
791850 - `mount_path: string`
792851
793 - `type: "file"`
794
795852 - `updated_at: string`
796853
797854 A timestamp in RFC 3339 format
from line 859
802859
803860 A memory store attached to an agent session.
804861
862 - `type: "memory_store"`
863
805864 - `memory_store_id: string`
806865
807866 The memory store ID (memstore_...). Must belong to the caller's organization and workspace.
808867
809 - `type: "memory_store"`
810
811868 - `access: optional "read_write" or "read_only" or null`
812869
813870 Access mode for an attached memory store.
from line 920
863920 - `"terminated"`
864921
865922 - `title: string or null`
866
867 - `type: "session"`
868923
869924 - `updated_at: string`
870925
api/beta/sessions/threads Changed · +8426 / -7899 lines
This page is larger than the 256 KiB this site keeps, so one side of the diff below stops where the stored text does.
Nothing in the body moved in this read. What changed is above.
api/beta/sessions/threads/archive Changed · +366 / -311 lines
from line 1
1---
2title: Archive Session Thread
3url: https://platform.claude.com/docs/en/api/beta/sessions/threads/archive
4---
5
16# Archive Session Thread
27
38**POST** `/v1/sessions/{session_id}/threads/{thread_id}/archive`
from line 23
1823
1924 - `string`
2025
21 - `"message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 41 more`
26 - `"message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 42 more`
2227
2328 - `"message-batches-2024-09-24"`
2429
from line 71
6671
6772 - `"user-profiles-2026-08-18"`
6873
74 - `"user-profiles-2026-09-04"`
75
6976 - `"advisor-tool-2026-03-01"`
7077
7178 - `"managed-agents-2026-04-01"`
from line 115
108115
109116 - `"mid-conversation-system-clear-at-2026-08-21"`
110117
118- `"anthropic-workspace-id": optional string`
119
111120## Returns
112121
113122- `BetaManagedAgentsSessionThread object`
from line 123
114123
115124 An execution thread within a `session`. Each session has one primary thread plus zero or more child threads spawned by the coordinator.
116125
126 - `type: "session_thread"`
127
117128 - `id: string`
118129
119130 Unique identifier for this thread.
from line 137
126137
127138 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`.
128139
140 - `type: "agent"`
141
129142 - `id: string`
130143
131144 - `description: string or null`
from line 145
132145
133146 - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition`
134147
135 - `name: string`
136
137148 - `type: "url"`
138149
150 - `name: string`
151
139152 - `url: string`
140153
141154 - `model: BetaManagedAgentsModelConfig`
from line 279
266279
267280 A resolved Anthropic-managed skill.
268281
269 - `skill_id: string`
270
271282 - `type: "anthropic"`
272283
284 - `skill_id: string`
285
273286 - `version: string`
274287
275288 - `BetaManagedAgentsCustomSkill object`
from line 289
276289
277290 A resolved user-created custom skill.
278291
279 - `skill_id: string`
280
281292 - `type: "custom"`
282293
294 - `skill_id: string`
295
283296 - `version: string`
284297
285298 - `system: string or null`
from line 301
288301
289302 - `BetaManagedAgentsAgentToolset20260401 object`
290303
304 - `type: "agent_toolset_20260401"`
305
291306 - `configs: array of BetaManagedAgentsAgentToolConfig`
292307
293308 - `BetaManagedAgentsBashToolConfig object`
from line 309
294309
295310 Configuration for the bash tool.
296311
312 - `type: "bash"`
313
297314 - `enabled: boolean`
298315
299316 - `name: "bash"`
300317
301 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
318 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
302319
303320 Permission policy for tool execution.
304321
from line 331
314331
315332 - `type: "always_ask"`
316333
317 - `type: "bash"`
334 - `BetaManagedAgentsAutoPolicy object`
318335
336 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
337
338 - `type: "auto"`
339
319340 - `BetaManagedAgentsEditToolConfig object`
320341
321342 Configuration for the edit tool.
322343
344 - `type: "edit"`
345
323346 - `enabled: boolean`
324347
325348 - `name: "edit"`
326349
327 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
350 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
328351
329352 Permission policy for tool execution.
330353
from line 359
336359
337360 Tool calls require user confirmation before execution.
338361
339 - `type: "edit"`
362 - `BetaManagedAgentsAutoPolicy object`
340363
364 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
365
341366 - `BetaManagedAgentsReadToolConfig object`
342367
343368 Configuration for the read tool.
344369
370 - `type: "read"`
371
345372 - `enabled: boolean`
346373
347374 - `name: "read"`
348375
349 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
376 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
350377
351378 Permission policy for tool execution.
352379
from line 385
358385
359386 Tool calls require user confirmation before execution.
360387
361 - `type: "read"`
388 - `BetaManagedAgentsAutoPolicy object`
362389
390 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
391
363392 - `BetaManagedAgentsWriteToolConfig object`
364393
365394 Configuration for the write tool.
366395
396 - `type: "write"`
397
367398 - `enabled: boolean`
368399
369400 - `name: "write"`
370401
371 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
402 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
372403
373404 Permission policy for tool execution.
374405
from line 411
380411
381412 Tool calls require user confirmation before execution.
382413
383 - `type: "write"`
414 - `BetaManagedAgentsAutoPolicy object`
384415
416 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
417
385418 - `BetaManagedAgentsGlobToolConfig object`
386419
387420 Configuration for the glob tool.
388421
422 - `type: "glob"`
423
389424 - `enabled: boolean`
390425
391426 - `name: "glob"`
392427
393 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
428 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
394429
395430 Permission policy for tool execution.
396431
from line 437
402437
403438 Tool calls require user confirmation before execution.
404439
405 - `type: "glob"`
440 - `BetaManagedAgentsAutoPolicy object`
406441
442 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
443
407444 - `BetaManagedAgentsGrepToolConfig object`
408445
409446 Configuration for the grep tool.
410447
448 - `type: "grep"`
449
411450 - `enabled: boolean`
412451
413452 - `name: "grep"`
414453
415 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
454 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
416455
417456 Permission policy for tool execution.
418457
from line 463
424463
425464 Tool calls require user confirmation before execution.
426465
427 - `type: "grep"`
466 - `BetaManagedAgentsAutoPolicy object`
428467
468 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
469
429470 - `BetaManagedAgentsWebFetchToolConfig object`
430471
431472 Configuration for the web_fetch tool.
432473
474 - `type: "web_fetch"`
475
433476 - `enabled: boolean`
434477
435478 - `name: "web_fetch"`
436479
437 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
480 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
438481
439482 Permission policy for tool execution.
440483
from line 489
446489
447490 Tool calls require user confirmation before execution.
448491
449 - `type: "web_fetch"`
492 - `BetaManagedAgentsAutoPolicy object`
450493
494 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
495
451496 - `allowed_domains: optional array of string`
452497
453498 - `blocked_domains: optional array of string`
from line 505
460505
461506 Configuration for the web_search tool.
462507
508 - `type: "web_search"`
509
463510 - `enabled: boolean`
464511
465512 - `name: "web_search"`
466513
467 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
514 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
468515
469516 Permission policy for tool execution.
470517
from line 523
476523
477524 Tool calls require user confirmation before execution.
478525
479 - `type: "web_search"`
526 - `BetaManagedAgentsAutoPolicy object`
480527
528 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
529
481530 - `allowed_domains: optional array of string`
482531
483532 - `blocked_domains: optional array of string`
from line 567
518567
519568 - `enabled: boolean`
520569
521 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
570 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
522571
523572 Permission policy for tool execution.
524573
from line 579
530579
531580 Tool calls require user confirmation before execution.
532581
533 - `type: "agent_toolset_20260401"`
582 - `BetaManagedAgentsAutoPolicy object`
534583
584 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
585
535586 - `BetaManagedAgentsMCPToolset object`
536587
588 - `type: "mcp_toolset"`
589
537590 - `configs: array of BetaManagedAgentsMCPToolConfig`
538591
539592 - `enabled: boolean`
from line 593
540593
541594 - `name: string`
542595
543 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
596 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
544597
545598 Permission policy for tool execution.
546599
from line 605
552605
553606 Tool calls require user confirmation before execution.
554607
608 - `BetaManagedAgentsAutoPolicy object`
609
610 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
611
555612 - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig`
556613
557614 Resolved default configuration for all tools from an MCP server.
from line 615
558615
559616 - `enabled: boolean`
560617
561 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
618 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
562619
563620 Permission policy for tool execution.
564621
from line 627
570627
571628 Tool calls require user confirmation before execution.
572629
573 - `mcp_server_name: string`
630 - `BetaManagedAgentsAutoPolicy object`
574631
575 - `type: "mcp_toolset"`
632 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
576633
634 - `mcp_server_name: string`
635
577636 - `BetaManagedAgentsCustomTool object`
578637
579638 A custom tool as returned in API responses.
580639
640 - `type: "custom"`
641
581642 - `description: string`
582643
583644 - `input_schema: BetaManagedAgentsCustomToolInputSchema`
from line 653
592653
593654 - `name: string`
594655
595 - `type: "custom"`
596
597 - `type: "agent"`
598
599656 - `version: number`
600657
601658 format: int32
from line 661
604661
605662 Platform advisor roster entry: a model the session's primary thread may consult mid-turn.
606663
664 - `type: "advisor"`
665
607666 - `model: string`
608667
609668 The advisor model id.
610669
611 - `type: "advisor"`
612
613670 - `archived_at: string or null`
614671
615672 A timestamp in RFC 3339 format
from line 720
663720 - `"rescheduling"`
664721
665722 - `"terminated"`
666
667 - `type: "session_thread"`
668723
669724 - `updated_at: string`
670725
api/beta/sessions/threads/events Changed · +4291 / -4066 lines
Nothing in the body moved in this read. What changed is above.
api/beta/sessions/threads/events/list Changed · +2122 / -2007 lines
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: List Session Thread Events
3url: https://platform.claude.com/docs/en/api/beta/sessions/threads/events/list
4---
5
16# List Session Thread Events
27
38**GET** `/v1/sessions/{session_id}/threads/{thread_id}/events`
from line 35
3035
3136 - `string`
3237
33 - `"message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 41 more`
38 - `"message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 42 more`
3439
3540 - `"message-batches-2024-09-24"`
3641
from line 83
7883
7984 - `"user-profiles-2026-08-18"`
8085
86 - `"user-profiles-2026-09-04"`
87
8188 - `"advisor-tool-2026-03-01"`
8289
8390 - `"managed-agents-2026-04-01"`
from line 127
120127
121128 - `"mid-conversation-system-clear-at-2026-08-21"`
122129
130- `"anthropic-workspace-id": optional string`
131
123132## Returns
124133
125134- `data: optional array of BetaManagedAgentsSessionEvent`
from line 139
130139
131140 A user message event in the session conversation.
132141
142 - `type: "user.message"`
143
133144 - `id: string`
134145
135146 Unique identifier for this event.
from line 153
142153
143154 Regular text content.
144155
156 - `type: "text"`
157
145158 - `text: string`
146159
147160 The text content.
148161
149162 minLength: 1
150163
164 - `BetaManagedAgentsImageBlock object`
165
166 Image content specified directly as base64 data or as a reference via a URL.
167
168 - `type: "image"`
169
170 - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource`
171
172 Union type for image source variants.
173
174 - `BetaManagedAgentsBase64ImageSource object`
175
176 Base64-encoded image data.
177
178 - `type: "base64"`
179
180 - `data: string`
181
182 Base64-encoded image data.
183
184 minLength: 1
185
186 - `media_type: string`
187
188 MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp").
189
190 minLength: 1
191
192 - `BetaManagedAgentsURLImageSource object`
193
194 Image referenced by URL.
195
196 - `type: "url"`
197
198 - `url: string`
199
200 URL of the image to fetch.
201
202 minLength: 1
203
204 - `BetaManagedAgentsFileImageSource object`
205
206 Image referenced by file ID.
207
208 - `type: "file"`
209
210 - `file_id: string`
211
212 ID of a previously uploaded file.
213
214 minLength: 1
215
216 - `BetaManagedAgentsDocumentBlock object`
217
218 Document content, either specified directly as base64 data, as text, or as a reference via a URL.
219
220 - `type: "document"`
221
222 - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource`
223
224 Union type for document source variants.
225
226 - `BetaManagedAgentsBase64DocumentSource object`
227
228 Base64-encoded document data.
229
230 - `type: "base64"`
231
232 - `data: string`
233
234 Base64-encoded document data.
235
236 minLength: 1
237
238 - `media_type: string`
239
240 MIME type of the document (e.g., "application/pdf").
241
242 minLength: 1
243
244 - `BetaManagedAgentsPlainTextDocumentSource object`
245
246 Plain text document content.
247
248 - `type: "text"`
249
250 - `data: string`
251
252 The plain text content.
253
254 minLength: 1
255
256 - `media_type: "text/plain"`
257
258 MIME type of the text content. Must be "text/plain".
259
260 - `BetaManagedAgentsURLDocumentSource object`
261
262 Document referenced by URL.
263
264 - `type: "url"`
265
266 - `url: string`
267
268 URL of the document to fetch.
269
270 minLength: 1
271
272 - `BetaManagedAgentsFileDocumentSource object`
273
274 Document referenced by file ID.
275
276 - `type: "file"`
277
278 - `file_id: string`
279
280 ID of a previously uploaded file.
281
282 minLength: 1
283
284 - `context: optional string or null`
285
286 Additional context about the document for the model.
287
288 - `title: optional string or null`
289
290 The title of the document.
291
292 - `BetaManagedAgentsRedactedBlock object`
293
294 Placeholder for content withheld by Anthropic model policy.
295
296 - `type: "redacted"`
297
298 - `processed_at: optional string or null`
299
300 A timestamp in RFC 3339 format
301
302 format: date-time
303
304 - `BetaManagedAgentsUserInterruptEvent object`
305
306 An interrupt event that pauses agent execution and returns control to the user.
307
308 - `type: "user.interrupt"`
309
310 - `id: string`
311
312 Unique identifier for this event.
313
314 - `processed_at: optional string or null`
315
316 A timestamp in RFC 3339 format
317
318 format: date-time
319
320 - `session_thread_id: optional string or null`
321
322 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.
323
324 - `BetaManagedAgentsUserToolConfirmationEvent object`
325
326 A tool confirmation event that approves or denies a pending tool execution.
327
328 - `type: "user.tool_confirmation"`
329
330 - `id: string`
331
332 Unique identifier for this event.
333
334 - `result: "allow" or "deny"`
335
336 UserToolConfirmationResult enum
337
338 - `"allow"`
339
340 - `"deny"`
341
342 - `tool_use_id: string`
343
344 The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field.
345
346 - `deny_message: optional string or null`
347
348 Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'.
349
350 maxLength: 10000
351
352 - `processed_at: optional string or null`
353
354 A timestamp in RFC 3339 format
355
356 format: date-time
357
358 - `session_thread_id: optional string or null`
359
360 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.
361
362 - `BetaManagedAgentsUserCustomToolResultEvent object`
363
364 Event sent by the client providing the result of a custom tool execution.
365
366 - `type: "user.custom_tool_result"`
367
368 - `id: string`
369
370 Unique identifier for this event.
371
372 - `custom_tool_use_id: string`
373
374 The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field.
375
376 - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock`
377
378 The result content returned by the tool.
379
380 - `BetaManagedAgentsTextBlock object`
381
382 Regular text content.
383
384 - `BetaManagedAgentsImageBlock object`
385
386 Image content specified directly as base64 data or as a reference via a URL.
387
388 - `BetaManagedAgentsDocumentBlock object`
389
390 Document content, either specified directly as base64 data, as text, or as a reference via a URL.
391
392 - `BetaManagedAgentsSearchResultBlock object`
393
394 A block containing a web search result.
395
396 - `type: "search_result"`
397
398 - `citations: BetaManagedAgentsSearchResultCitations`
399
400 Citation settings for a search result.
401
402 - `enabled: boolean`
403
404 Whether citations are enabled for this search result.
405
406 - `content: array of BetaManagedAgentsSearchResultContent`
407
408 Array of text content blocks from the search result.
409
410 - `type: "text"`
411
412 - `text: string`
413
414 The text content.
415
416 minLength: 1
417
418 - `source: string`
419
420 The URL source of the search result.
421
422 minLength: 1
423
424 - `title: string`
425
426 The title of the search result.
427
428 minLength: 1
429
430 - `is_error: optional boolean or null`
431
432 Whether the tool execution resulted in an error.
433
434 - `processed_at: optional string or null`
435
436 A timestamp in RFC 3339 format
437
438 format: date-time
439
440 - `session_thread_id: optional string or null`
441
442 Routes this result to a subagent thread. Copy from the `agent.custom_tool_use` event's `session_thread_id`.
443
444 - `BetaManagedAgentsAgentCustomToolUseEvent object`
445
446 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.
447
448 - `type: "agent.custom_tool_use"`
449
450 - `id: string`
451
452 Unique identifier for this event.
453
454 - `input: map[unknown]`
455
456 Input parameters for the tool call.
457
458 - `name: string`
459
460 Name of the custom tool being called.
461
462 - `processed_at: string`
463
464 A timestamp in RFC 3339 format
465
466 format: date-time
467
468 - `session_thread_id: optional string or null`
469
470 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.
471
472 - `BetaManagedAgentsAgentMessageEvent object`
473
474 An agent response event in the session conversation.
475
476 - `type: "agent.message"`
477
478 - `id: string`
479
480 Unique identifier for this event.
481
482 - `content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsRedactedBlock`
483
484 Array of text blocks comprising the agent response.
485
486 - `BetaManagedAgentsTextBlock object`
487
488 Regular text content.
489
490 - `BetaManagedAgentsRedactedBlock object`
491
492 Placeholder for content withheld by Anthropic model policy.
493
494 - `processed_at: string`
495
496 A timestamp in RFC 3339 format
497
498 format: date-time
499
500 - `BetaManagedAgentsAgentThinkingEvent object`
501
502 Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier.
503
504 - `type: "agent.thinking"`
505
506 - `id: string`
507
508 Unique identifier for this event.
509
510 - `processed_at: string`
511
512 A timestamp in RFC 3339 format
513
514 format: date-time
515
516 - `BetaManagedAgentsAgentMCPToolUseEvent object`
517
518 Event emitted when the agent invokes a tool provided by an MCP server.
519
520 - `type: "agent.mcp_tool_use"`
521
522 - `id: string`
523
524 Unique identifier for this event.
525
526 - `input: map[unknown]`
527
528 Input parameters for the tool call.
529
530 - `mcp_server_name: string`
531
532 Name of the MCP server providing the tool.
533
534 - `name: string`
535
536 Name of the MCP tool being used.
537
538 - `processed_at: string`
539
540 A timestamp in RFC 3339 format
541
542 format: date-time
543
544 - `evaluated_permission: optional "allow" or "ask" or "deny"`
545
546 AgentEvaluatedPermission enum
547
548 - `"allow"`
549
550 - `"ask"`
551
552 - `"deny"`
553
554 - `evaluation: optional BetaManagedAgentsAgentToolEvaluation`
555
556 Names the resolved permission_policy that produced evaluated_permission, and under auto carries the judgement. Open union: clients must tolerate unknown variants.
557
558 - `BetaManagedAgentsAgentToolEvaluationAlwaysAllow object`
559
560 The resolved permission_policy was always_allow; accompanies evaluated_permission "allow".
561
562 - `type: "always_allow"`
563
564 - `BetaManagedAgentsAgentToolEvaluationAlwaysAsk object`
565
566 The resolved permission_policy was always_ask; accompanies evaluated_permission "ask".
567
568 - `type: "always_ask"`
569
570 - `BetaManagedAgentsAgentToolEvaluationAuto object`
571
572 The resolved permission_policy was auto: the server judged this invocation individually.
573
574 - `type: "auto"`
575
576 - `evaluated_permission: BetaManagedAgentsAgentAutoEvaluatedPermission`
577
578 The server's per-invocation judgement under the auto permission policy. Its type always equals the event's top-level evaluated_permission. Open union: clients must tolerate unknown variants.
579
580 - `BetaManagedAgentsAgentAutoEvaluatedPermissionAllow object`
581
582 The server judged the invocation safe to execute without client approval.
583
584 - `type: "allow"`
585
586 - `BetaManagedAgentsAgentAutoEvaluatedPermissionAsk object`
587
588 The server reached no judgement; the invocation is held for client approval.
589
590 - `type: "ask"`
591
592 - `reason_code: string`
593
594 The judgement's grounds in registry-bound terms, for client branching and audit rather than end-user display. Open registry; currently "indeterminate" (no judgement was reached). Clients must tolerate values outside this set.
595
596 maxLength: 64
597
598 - `BetaManagedAgentsAgentAutoEvaluatedPermissionDeny object`
599
600 The server judged the invocation high-risk; it does not execute and a synthetic error tool result is appended.
601
602 - `type: "deny"`
603
604 - `reason_code: string`
605
606 The judgement's grounds in registry-bound terms. Open registry; currently "high_risk" (judged high-risk; the call does not run). Clients must tolerate values outside this set.
607
608 maxLength: 64
609
610 - `session_thread_id: optional string or null`
611
612 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.
613
614 - `BetaManagedAgentsAgentMCPToolResultEvent object`
615
616 Event representing the result of an MCP tool execution.
617
618 - `type: "agent.mcp_tool_result"`
619
620 - `id: string`
621
622 Unique identifier for this event.
623
624 - `mcp_tool_use_id: string`
625
626 The id of the `agent.mcp_tool_use` event this result corresponds to.
627
628 - `processed_at: string`
629
630 A timestamp in RFC 3339 format
631
632 format: date-time
633
634 - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock`
635
636 The result content returned by the tool.
637
638 - `BetaManagedAgentsTextBlock object`
639
640 Regular text content.
641
642 - `BetaManagedAgentsImageBlock object`
643
644 Image content specified directly as base64 data or as a reference via a URL.
645
646 - `BetaManagedAgentsDocumentBlock object`
647
648 Document content, either specified directly as base64 data, as text, or as a reference via a URL.
649
650 - `BetaManagedAgentsSearchResultBlock object`
651
652 A block containing a web search result.
653
654 - `is_error: optional boolean or null`
655
656 Whether the tool execution resulted in an error.
657
658 - `BetaManagedAgentsAgentToolUseEvent object`
659
660 Event emitted when the agent invokes a built-in agent tool.
661
662 - `type: "agent.tool_use"`
663
664 - `id: string`
665
666 Unique identifier for this event.
667
668 - `input: map[unknown]`
669
670 Input parameters for the tool call.
671
672 - `name: string`
673
674 Name of the agent tool being used.
675
676 - `processed_at: string`
677
678 A timestamp in RFC 3339 format
679
680 format: date-time
681
682 - `evaluated_permission: optional "allow" or "ask" or "deny"`
683
684 AgentEvaluatedPermission enum
685
686 - `"allow"`
687
688 - `"ask"`
689
690 - `"deny"`
691
692 - `evaluation: optional BetaManagedAgentsAgentToolEvaluation`
693
694 Names the resolved permission_policy that produced evaluated_permission, and under auto carries the judgement. Open union: clients must tolerate unknown variants.
695
696 - `session_thread_id: optional string or null`
697
698 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.
699
700 - `BetaManagedAgentsAgentToolResultEvent object`
701
702 Event representing the result of an agent tool execution.
703
704 - `type: "agent.tool_result"`
705
706 - `id: string`
707
708 Unique identifier for this event.
709
710 - `processed_at: string`
711
712 A timestamp in RFC 3339 format
713
714 format: date-time
715
716 - `tool_use_id: string`
717
718 The id of the `agent.tool_use` event this result corresponds to.
719
720 - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock`
721
722 The result content returned by the tool.
723
724 - `BetaManagedAgentsTextBlock object`
725
726 Regular text content.
727
728 - `BetaManagedAgentsImageBlock object`
729
730 Image content specified directly as base64 data or as a reference via a URL.
731
732 - `BetaManagedAgentsDocumentBlock object`
733
734 Document content, either specified directly as base64 data, as text, or as a reference via a URL.
735
736 - `BetaManagedAgentsSearchResultBlock object`
737
738 A block containing a web search result.
739
740 - `is_error: optional boolean or null`
741
742 Whether the tool execution resulted in an error.
743
744 - `BetaManagedAgentsAgentThreadMessageReceivedEvent object`
745
746 Delivery event written to the target thread's input stream when an agent-to-agent message arrives.
747
748 - `type: "agent.thread_message_received"`
749
750 - `id: string`
751
752 Unique identifier for this event.
753
754 - `content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsRedactedBlock`
755
756 Message content blocks.
757
758 - `BetaManagedAgentsTextBlock object`
759
760 Regular text content.
761
762 - `BetaManagedAgentsImageBlock object`
763
764 Image content specified directly as base64 data or as a reference via a URL.
765
766 - `BetaManagedAgentsDocumentBlock object`
767
768 Document content, either specified directly as base64 data, as text, or as a reference via a URL.
769
770 - `BetaManagedAgentsRedactedBlock object`
771
772 Placeholder for content withheld by Anthropic model policy.
773
774 - `from_session_thread_id: string`
775
776 Public `sthr_` ID of the thread that sent the message.
777
778 - `processed_at: string`
779
780 A timestamp in RFC 3339 format
781
782 format: date-time
783
784 - `from_agent_name: optional string or null`
785
786 Name of the callable agent this message came from. Absent when received from the primary agent.
787
788 - `BetaManagedAgentsAgentThreadMessageSentEvent object`
789
790 Observability event emitted to the sender's output stream when an agent-to-agent message is sent.
791
792 - `type: "agent.thread_message_sent"`
793
794 - `id: string`
795
796 Unique identifier for this event.
797
798 - `content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsRedactedBlock`
799
800 Message content blocks.
801
802 - `BetaManagedAgentsTextBlock object`
803
804 Regular text content.
805
806 - `BetaManagedAgentsImageBlock object`
807
808 Image content specified directly as base64 data or as a reference via a URL.
809
810 - `BetaManagedAgentsDocumentBlock object`
811
812 Document content, either specified directly as base64 data, as text, or as a reference via a URL.
813
814 - `BetaManagedAgentsRedactedBlock object`
815
816 Placeholder for content withheld by Anthropic model policy.
817
818 - `processed_at: string`
819
820 A timestamp in RFC 3339 format
821
822 format: date-time
823
824 - `to_session_thread_id: string`
825
826 Public `sthr_` ID of the thread the message was sent to.
827
828 - `to_agent_name: optional string or null`
829
830 Name of the callable agent this message was sent to. Absent when sent to the primary agent.
831
832 - `BetaManagedAgentsAgentThreadContextCompactedEvent object`
833
834 Indicates that context compaction (summarization) occurred during the session.
835
836 - `type: "agent.thread_context_compacted"`
837
838 - `id: string`
839
840 Unique identifier for this event.
841
842 - `processed_at: string`
843
844 A timestamp in RFC 3339 format
845
846 format: date-time
847
848 - `BetaManagedAgentsSessionErrorEvent object`
849
850 An error event indicating a problem occurred during session execution.
851
852 - `type: "session.error"`
853
854 - `id: string`
855
856 Unique identifier for this event.
857
858 - `error: BetaManagedAgentsUnknownError or BetaManagedAgentsModelOverloadedError or BetaManagedAgentsModelRateLimitedError or 5 more`
859
860 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.
861
862 - `BetaManagedAgentsUnknownError object`
863
864 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.
865
866 - `type: "unknown_error"`
867
868 - `message: string`
869
870 Human-readable error description.
871
872 - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal`
873
874 What the client should do next in response to this error.
875
876 - `BetaManagedAgentsRetryStatusRetrying object`
877
878 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.
879
880 - `type: "retrying"`
881
882 - `BetaManagedAgentsRetryStatusExhausted object`
883
884 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
885
886 - `type: "exhausted"`
887
888 - `BetaManagedAgentsRetryStatusTerminal object`
889
890 The session encountered a terminal error and will transition to `terminated` state.
891
892 - `type: "terminal"`
893
894 - `BetaManagedAgentsModelOverloadedError object`
895
896 The model is currently overloaded. Emitted after automatic retries are exhausted.
897
898 - `type: "model_overloaded_error"`
899
900 - `message: string`
901
902 Human-readable error description.
903
904 - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal`
905
906 What the client should do next in response to this error.
907
908 - `BetaManagedAgentsRetryStatusRetrying object`
909
910 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.
911
912 - `BetaManagedAgentsRetryStatusExhausted object`
913
914 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
915
916 - `BetaManagedAgentsRetryStatusTerminal object`
917
918 The session encountered a terminal error and will transition to `terminated` state.
919
920 - `BetaManagedAgentsModelRateLimitedError object`
921
922 The model request was rate-limited.
923
924 - `type: "model_rate_limited_error"`
925
926 - `message: string`
927
928 Human-readable error description.
929
930 - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal`
931
932 What the client should do next in response to this error.
933
934 - `BetaManagedAgentsRetryStatusRetrying object`
935
936 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.
937
938 - `BetaManagedAgentsRetryStatusExhausted object`
939
940 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
941
942 - `BetaManagedAgentsRetryStatusTerminal object`
943
944 The session encountered a terminal error and will transition to `terminated` state.
945
946 - `BetaManagedAgentsModelRequestFailedError object`
947
948 A model request failed for a reason other than overload or rate-limiting.
949
950 - `type: "model_request_failed_error"`
951
952 - `message: string`
953
954 Human-readable error description.
955
956 - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal`
957
958 What the client should do next in response to this error.
959
960 - `BetaManagedAgentsRetryStatusRetrying object`
961
962 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.
963
964 - `BetaManagedAgentsRetryStatusExhausted object`
965
966 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
967
968 - `BetaManagedAgentsRetryStatusTerminal object`
969
970 The session encountered a terminal error and will transition to `terminated` state.
971
972 - `BetaManagedAgentsMCPConnectionFailedError object`
973
974 Failed to connect to an MCP server.
975
976 - `type: "mcp_connection_failed_error"`
977
978 - `mcp_server_name: string`
979
980 Name of the MCP server that failed to connect.
981
982 - `message: string`
983
984 Human-readable error description.
985
986 - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal`
987
988 What the client should do next in response to this error.
989
990 - `BetaManagedAgentsRetryStatusRetrying object`
991
992 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.
993
994 - `BetaManagedAgentsRetryStatusExhausted object`
995
996 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
997
998 - `BetaManagedAgentsRetryStatusTerminal object`
999
1000 The session encountered a terminal error and will transition to `terminated` state.
1001
1002 - `BetaManagedAgentsMCPAuthenticationFailedError object`
1003
1004 Authentication to an MCP server failed.
1005
1006 - `type: "mcp_authentication_failed_error"`
1007
1008 - `mcp_server_name: string`
1009
1010 Name of the MCP server that failed authentication.
1011
1012 - `message: string`
1013
1014 Human-readable error description.
1015
1016 - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal`
1017
1018 What the client should do next in response to this error.
1019
1020 - `BetaManagedAgentsRetryStatusRetrying object`
1021
1022 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.
1023
1024 - `BetaManagedAgentsRetryStatusExhausted object`
1025
1026 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
1027
1028 - `BetaManagedAgentsRetryStatusTerminal object`
1029
1030 The session encountered a terminal error and will transition to `terminated` state.
1031
1032 - `BetaManagedAgentsBillingError object`
1033
1034 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.
1035
1036 - `type: "billing_error"`
1037
1038 - `message: string`
1039
1040 Human-readable error description.
1041
1042 - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal`
1043
1044 What the client should do next in response to this error.
1045
1046 - `BetaManagedAgentsRetryStatusRetrying object`
1047
1048 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.
1049
1050 - `BetaManagedAgentsRetryStatusExhausted object`
1051
1052 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
1053
1054 - `BetaManagedAgentsRetryStatusTerminal object`
1055
1056 The session encountered a terminal error and will transition to `terminated` state.
1057
1058 - `BetaManagedAgentsCredentialHostUnreachableError object`
1059
1060 An `environment_variable` credential's `auth.networking.allowed_hosts` includes a host the environment's network policy does not permit.
1061
1062 - `type: "credential_host_unreachable_error"`
1063
1064 - `credential_id: string`
1065
1066 ID of the affected credential.
1067
1068 - `message: string`
1069
1070 Human-readable error description.
1071
1072 - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal`
1073
1074 What the client should do next in response to this error.
1075
1076 - `BetaManagedAgentsRetryStatusRetrying object`
1077
1078 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.
1079
1080 - `BetaManagedAgentsRetryStatusExhausted object`
1081
1082 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
1083
1084 - `BetaManagedAgentsRetryStatusTerminal object`
1085
1086 The session encountered a terminal error and will transition to `terminated` state.
1087
1088 - `vault_id: string`
1089
1090 ID of the vault containing the affected credential.
1091
1092 - `processed_at: string`
1093
1094 A timestamp in RFC 3339 format
1095
1096 format: date-time
1097
1098 - `BetaManagedAgentsSessionStatusRescheduledEvent object`
1099
1100 Indicates the session is recovering from an error state and is rescheduled for execution.
1101
1102 - `type: "session.status_rescheduled"`
1103
1104 - `id: string`
1105
1106 Unique identifier for this event.
1107
1108 - `processed_at: string`
1109
1110 A timestamp in RFC 3339 format
1111
1112 format: date-time
1113
1114 - `BetaManagedAgentsSessionStatusRunningEvent object`
1115
1116 Indicates the session is actively running and the agent is working.
1117
1118 - `type: "session.status_running"`
1119
1120 - `id: string`
1121
1122 Unique identifier for this event.
1123
1124 - `processed_at: string`
1125
1126 A timestamp in RFC 3339 format
1127
1128 format: date-time
1129
1130 - `BetaManagedAgentsSessionStatusIdleEvent object`
1131
1132 Indicates the agent has paused and is awaiting user input.
1133
1134 - `type: "session.status_idle"`
1135
1136 - `id: string`
1137
1138 Unique identifier for this event.
1139
1140 - `processed_at: string`
1141
1142 A timestamp in RFC 3339 format
1143
1144 format: date-time
1145
1146 - `stop_reason: BetaManagedAgentsSessionEndTurn or BetaManagedAgentsSessionRequiresAction or BetaManagedAgentsSessionRetriesExhausted or BetaManagedAgentsSessionBudgetReached`
1147
1148 The agent completed its turn naturally and is ready for the next user message.
1149
1150 - `BetaManagedAgentsSessionEndTurn object`
1151
1152 The agent completed its turn naturally and is ready for the next user message.
1153
1154 - `type: "end_turn"`
1155
1156 - `BetaManagedAgentsSessionRequiresAction object`
1157
1158 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.
1159
1160 - `type: "requires_action"`
1161
1162 - `event_ids: array of string`
1163
1164 The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder.
1165
1166 - `BetaManagedAgentsSessionRetriesExhausted object`
1167
1168 The turn ended because repeated errors exhausted the retry budget or an error escalated to `retry_status: 'exhausted'`.
1169
1170 - `type: "retries_exhausted"`
1171
1172 - `BetaManagedAgentsSessionBudgetReached object`
1173
1174 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.
1175
1176 - `type: "budget_reached"`
1177
1178 - `BetaManagedAgentsSessionStatusTerminatedEvent object`
1179
1180 Indicates the session has terminated, either due to an error or completion.
1181
1182 - `type: "session.status_terminated"`
1183
1184 - `id: string`
1185
1186 Unique identifier for this event.
1187
1188 - `processed_at: string`
1189
1190 A timestamp in RFC 3339 format
1191
1192 format: date-time
1193
1194 - `BetaManagedAgentsSessionThreadCreatedEvent object`
1195
1196 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.
1197
1198 - `type: "session.thread_created"`
1199
1200 - `id: string`
1201
1202 Unique identifier for this event.
1203
1204 - `agent_name: string`
1205
1206 Name of the callable agent the thread runs.
1207
1208 - `processed_at: string`
1209
1210 A timestamp in RFC 3339 format
1211
1212 format: date-time
1213
1214 - `session_thread_id: string`
1215
1216 Public `sthr_` ID of the newly created thread.
1217
1218 - `BetaManagedAgentsSpanOutcomeEvaluationStartEvent object`
1219
1220 Emitted when an outcome evaluation cycle begins.
1221
1222 - `type: "span.outcome_evaluation_start"`
1223
1224 - `id: string`
1225
1226 Unique identifier for this event.
1227
1228 - `iteration: number`
1229
1230 0-indexed revision cycle. 0 is the first evaluation; 1 is the re-evaluation after the first revision; etc.
1231
1232 format: int32
1233
1234 - `outcome_id: string`
1235
1236 The `outc_` ID of the outcome being evaluated.
1237
1238 - `processed_at: string`
1239
1240 A timestamp in RFC 3339 format
1241
1242 format: date-time
1243
1244 - `BetaManagedAgentsSpanOutcomeEvaluationEndEvent object`
1245
1246 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.
1247
1248 - `type: "span.outcome_evaluation_end"`
1249
1250 - `id: string`
1251
1252 Unique identifier for this event.
1253
1254 - `explanation: string`
1255
1256 Human-readable explanation of the verdict. For `needs_revision`, describes which criteria failed and why.
1257
1258 - `iteration: number`
1259
1260 0-indexed revision cycle, matching the corresponding `span.outcome_evaluation_start`.
1261
1262 format: int32
1263
1264 - `outcome_evaluation_start_id: string`
1265
1266 The id of the corresponding `span.outcome_evaluation_start` event.
1267
1268 - `outcome_id: string`
1269
1270 The `outc_` ID of the outcome being evaluated.
1271
1272 - `processed_at: string`
1273
1274 A timestamp in RFC 3339 format
1275
1276 format: date-time
1277
1278 - `result: string`
1279
1280 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.
1281
1282 - `usage: BetaManagedAgentsSpanModelUsage`
1283
1284 Token usage for a single model request.
1285
1286 - `cache_creation_input_tokens: number`
1287
1288 Tokens used to create prompt cache in this request.
1289
1290 format: int32
1291
1292 - `cache_read_input_tokens: number`
1293
1294 Tokens read from prompt cache in this request.
1295
1296 format: int32
1297
1298 - `input_tokens: number`
1299
1300 Input tokens consumed by this request.
1301
1302 format: int32
1303
1304 - `output_tokens: number`
1305
1306 Output tokens generated by this request.
1307
1308 format: int32
1309
1310 - `speed: optional "standard" or "fast" or null`
1311
1312 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.
1313
1314 - `"standard"`
1315
1316 - `"fast"`
1317
1318 - `BetaManagedAgentsSpanModelRequestStartEvent object`
1319
1320 Emitted when a model request is initiated by the agent.
1321
1322 - `type: "span.model_request_start"`
1323
1324 - `id: string`
1325
1326 Unique identifier for this event.
1327
1328 - `processed_at: string`
1329
1330 A timestamp in RFC 3339 format
1331
1332 format: date-time
1333
1334 - `BetaManagedAgentsSpanModelRequestEndEvent object`
1335
1336 Emitted when a model request completes.
1337
1338 - `type: "span.model_request_end"`
1339
1340 - `id: string`
1341
1342 Unique identifier for this event.
1343
1344 - `is_error: boolean or null`
1345
1346 Whether the model request resulted in an error.
1347
1348 - `model_request_start_id: string`
1349
1350 The id of the corresponding `span.model_request_start` event.
1351
1352 - `model_usage: BetaManagedAgentsSpanModelUsage`
1353
1354 Token usage for a single model request.
1355
1356 - `processed_at: string`
1357
1358 A timestamp in RFC 3339 format
1359
1360 format: date-time
1361
1362 - `BetaManagedAgentsSpanOutcomeEvaluationOngoingEvent object`
1363
1364 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.
1365
1366 - `type: "span.outcome_evaluation_ongoing"`
1367
1368 - `id: string`
1369
1370 Unique identifier for this event.
1371
1372 - `iteration: number`
1373
1374 0-indexed revision cycle, matching the corresponding `span.outcome_evaluation_start`.
1375
1376 format: int32
1377
1378 - `outcome_id: string`
1379
1380 The `outc_` ID of the outcome being evaluated.
1381
1382 - `processed_at: string`
1383
1384 A timestamp in RFC 3339 format
1385
1386 format: date-time
1387
1388 - `BetaManagedAgentsUserDefineOutcomeEvent object`
1389
1390 Echo of a `user.define_outcome` input event. Carries the server-generated `outcome_id` that subsequent `span.outcome_evaluation_*` events reference.
1391
1392 - `type: "user.define_outcome"`
1393
1394 - `id: string`
1395
1396 Unique identifier for this event.
1397
1398 - `description: string`
1399
1400 What the agent should produce. Copied from the input event.
1401
1402 - `max_iterations: number or null`
1403
1404 Evaluate-then-revise cycles before giving up. Default 3, max 20.
1405
1406 format: int32
1407
1408 - `outcome_id: string`
1409
1410 Server-generated `outc_` ID for this outcome. Referenced by `span.outcome_evaluation_*` events and the session's `outcome_evaluations` list.
1411
1412 - `processed_at: string`
1413
1414 A timestamp in RFC 3339 format
1415
1416 format: date-time
1417
1418 - `rubric: BetaManagedAgentsFileRubric or BetaManagedAgentsTextRubric`
1419
1420 Rubric for grading the quality of an outcome.
1421
1422 - `BetaManagedAgentsFileRubric object`
1423
1424 Rubric referenced by a file uploaded via the Files API.
1425
1426 - `type: "file"`
1427
1428 - `file_id: string`
1429
1430 ID of the rubric file.
1431
1432 - `BetaManagedAgentsTextRubric object`
1433
1434 Rubric content provided inline as text.
1435
1511436 - `type: "text"`
1521437
1438 - `content: string`
1439
1440 Rubric content. Plain text or markdown — the grader treats it as freeform text.
1441
1442 - `BetaManagedAgentsSessionDeletedEvent object`
1443
1444 Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session.
1445
1446 - `type: "session.deleted"`
1447
1448 - `id: string`
1449
1450 Unique identifier for this event.
1451
1452 - `processed_at: string`
1453
1454 A timestamp in RFC 3339 format
1455
1456 format: date-time
1457
1458 - `BetaManagedAgentsSessionThreadStatusRunningEvent object`
1459
1460 A session thread has begun executing. Emitted on the thread's own stream and cross-posted to the primary stream for child threads.
1461
1462 - `type: "session.thread_status_running"`
1463
1464 - `id: string`
1465
1466 Unique identifier for this event.
1467
1468 - `agent_name: string`
1469
1470 Name of the agent the thread runs.
1471
1472 - `processed_at: string`
1473
1474 A timestamp in RFC 3339 format
1475
1476 format: date-time
1477
1478 - `session_thread_id: string`
1479
1480 Public sthr_ ID of the thread that started running.
1481
1482 - `BetaManagedAgentsSessionThreadStatusIdleEvent object`
1483
1484 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.
1485
1486 - `type: "session.thread_status_idle"`
1487
1488 - `id: string`
1489
1490 Unique identifier for this event.
1491
1492 - `agent_name: string`
1493
1494 Name of the agent the thread runs.
1495
1496 - `processed_at: string`
1497
1498 A timestamp in RFC 3339 format
1499
1500 format: date-time
1501
1502 - `session_thread_id: string`
1503
1504 Public sthr_ ID of the thread that went idle.
1505
1506 - `stop_reason: BetaManagedAgentsSessionEndTurn or BetaManagedAgentsSessionRequiresAction or BetaManagedAgentsSessionRetriesExhausted or BetaManagedAgentsSessionBudgetReached`
1507
1508 The agent completed its turn naturally and is ready for the next user message.
1509
1510 - `BetaManagedAgentsSessionEndTurn object`
1511
1512 The agent completed its turn naturally and is ready for the next user message.
1513
1514 - `BetaManagedAgentsSessionRequiresAction object`
1515
1516 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.
1517
1518 - `BetaManagedAgentsSessionRetriesExhausted object`
1519
1520 The turn ended because repeated errors exhausted the retry budget or an error escalated to `retry_status: 'exhausted'`.
1521
1522 - `BetaManagedAgentsSessionBudgetReached object`
1523
1524 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.
1525
1526 - `BetaManagedAgentsSessionThreadStatusTerminatedEvent object`
1527
1528 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.
1529
1530 - `type: "session.thread_status_terminated"`
1531
1532 - `id: string`
1533
1534 Unique identifier for this event.
1535
1536 - `agent_name: string`
1537
1538 Name of the agent the thread runs.
1539
1540 - `processed_at: string`
1541
1542 A timestamp in RFC 3339 format
1543
1544 format: date-time
1545
1546 - `session_thread_id: string`
1547
1548 Public sthr_ ID of the thread that terminated.
1549
1550 - `BetaManagedAgentsUserToolResultEvent object`
1551
1552 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.
1553
1554 - `type: "user.tool_result"`
1555
1556 - `id: string`
1557
1558 Unique identifier for this event.
1559
1560 - `tool_use_id: string`
1561
1562 The id of the `agent.tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field.
1563
1564 - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock`
1565
1566 The result content returned by the tool.
1567
1568 - `BetaManagedAgentsTextBlock object`
1569
1570 Regular text content.
1571
1531572 - `BetaManagedAgentsImageBlock object`
1541573
1551574 Image content specified directly as base64 data or as a reference via a URL.
1561575
157 - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource`
158
159 Union type for image source variants.
160
161 - `BetaManagedAgentsBase64ImageSource object`
162
163 Base64-encoded image data.
164
165 - `data: string`
166
167 Base64-encoded image data.
168
169 minLength: 1
170
171 - `media_type: string`
172
173 MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp").
174
175 minLength: 1
176
177 - `type: "base64"`
178
179 - `BetaManagedAgentsURLImageSource object`
180
181 Image referenced by URL.
182
183 - `type: "url"`
184
185 - `url: string`
186
187 URL of the image to fetch.
188
189 minLength: 1
190
191 - `BetaManagedAgentsFileImageSource object`
192
193 Image referenced by file ID.
194
195 - `file_id: string`
196
197 ID of a previously uploaded file.
198
199 minLength: 1
200
201 - `type: "file"`
202
203 - `type: "image"`
204
2051576 - `BetaManagedAgentsDocumentBlock object`
2061577
2071578 Document content, either specified directly as base64 data, as text, or as a reference via a URL.
2081579
209 - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource`
210
211 Union type for document source variants.
212
213 - `BetaManagedAgentsBase64DocumentSource object`
214
215 Base64-encoded document data.
216
217 - `data: string`
218
219 Base64-encoded document data.
220
221 minLength: 1
222
223 - `media_type: string`
224
225 MIME type of the document (e.g., "application/pdf").
226
227 minLength: 1
228
229 - `type: "base64"`
230
231 - `BetaManagedAgentsPlainTextDocumentSource object`
232
233 Plain text document content.
234
235 - `data: string`
236
237 The plain text content.
238
239 minLength: 1
240
241 - `media_type: "text/plain"`
242
243 MIME type of the text content. Must be "text/plain".
244
245 - `type: "text"`
246
247 - `BetaManagedAgentsURLDocumentSource object`
248
249 Document referenced by URL.
250
251 - `type: "url"`
252
253 - `url: string`
254
255 URL of the document to fetch.
256
257 minLength: 1
258
259 - `BetaManagedAgentsFileDocumentSource object`
260
261 Document referenced by file ID.
262
263 - `file_id: string`
264
265 ID of a previously uploaded file.
266
267 minLength: 1
268
269 - `type: "file"`
270
271 - `type: "document"`
272
273 - `context: optional string or null`
274
275 Additional context about the document for the model.
276
277 - `title: optional string or null`
278
279 The title of the document.
280
281 - `BetaManagedAgentsRedactedBlock object`
282
283 Placeholder for content withheld by Anthropic model policy.
284
285 - `type: "redacted"`
286
287 - `type: "user.message"`
1580 - `BetaManagedAgentsSearchResultBlock object`
1581
1582 A block containing a web search result.
1583
1584 - `is_error: optional boolean or null`
1585
1586 Whether the tool execution resulted in an error.
2881587
2891588 - `processed_at: optional string or null`
2901589
from line 1591
2921591
2931592 format: date-time
2941593
295 - `BetaManagedAgentsUserInterruptEvent object`
296
297 An interrupt event that pauses agent execution and returns control to the user.
298
299 - `id: string`
300
301 Unique identifier for this event.
302
303 - `type: "user.interrupt"`
1594 - `session_thread_id: optional string or null`
1595
1596 Routes this result to a subagent thread. Copy from the `agent.tool_use` event's `session_thread_id`.
1597
1598 - `BetaManagedAgentsSessionThreadStatusRescheduledEvent object`
1599
1600 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.
1601
1602 - `type: "session.thread_status_rescheduled"`
1603
1604 - `id: string`
1605
1606 Unique identifier for this event.
1607
1608 - `agent_name: string`
1609
1610 Name of the agent the thread runs.
1611
1612 - `processed_at: string`
1613
1614 A timestamp in RFC 3339 format
1615
1616 format: date-time
1617
1618 - `session_thread_id: string`
1619
1620 Public sthr_ ID of the thread that is retrying.
1621
1622 - `BetaManagedAgentsSessionUpdatedEvent object`
1623
1624 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.
1625
1626 - `type: "session.updated"`
1627
1628 - `id: string`
1629
1630 Unique identifier for this event.
1631
1632 - `processed_at: string`
1633
1634 A timestamp in RFC 3339 format
1635
1636 format: date-time
1637
1638 - `agent: optional BetaManagedAgentsSessionAgent or null`
1639
1640 Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time.
1641
1642 - `type: "agent"`
1643
1644 - `id: string`
1645
1646 - `description: string or null`
1647
1648 - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition`
1649
1650 - `type: "url"`
1651
1652 - `name: string`
1653
1654 - `url: string`
1655
1656 - `model: BetaManagedAgentsModelConfig`
1657
1658 Model identifier and configuration.
1659
1660 - `id: BetaManagedAgentsModel`
1661
1662 The model that will power your agent.
1663
1664 See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options.
1665
1666 - `"claude-fable-5-1" or "claude-sonnet-5" or "claude-fable-5" or 11 more`
1667
1668 The model that will power your agent.
1669
1670 See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options.
1671
1672 - `"claude-fable-5-1"`
1673
1674 Frontier intelligence for ambitious tasks across coding, scientific discovery, and enterprise workflows
1675
1676 - `"claude-sonnet-5"`
1677
1678 High-performance model for coding and agents
1679
1680 - `"claude-fable-5"`
1681
1682 Next generation of intelligence for the hardest knowledge work and coding problems
1683
1684 - `"claude-opus-5"`
1685
1686 Powerful intelligence for long-running agents and coding
1687
1688 - `"claude-opus-4-8"`
1689
1690 Powerful intelligence for long-running agents and coding
1691
1692 - `"claude-opus-4-7"`
1693
1694 Powerful intelligence for long-running agents and coding
1695
1696 - `"claude-opus-4-6"`
1697
1698 Powerful intelligence for long-running agents and coding
1699
1700 - `"claude-sonnet-4-6"`
1701
1702 Best combination of speed and intelligence
1703
1704 - `"claude-haiku-4-5"`
1705
1706 Fastest model with near-frontier intelligence
1707
1708 - `"claude-haiku-4-5-20251001"`
1709
1710 Fastest model with near-frontier intelligence
1711
1712 - `"claude-opus-4-5"`
1713
1714 Powerful intelligence for long-running agents and coding
1715
1716 - `"claude-opus-4-5-20251101"`
1717
1718 Powerful intelligence for long-running agents and coding
1719
1720 - `"claude-sonnet-4-5"`
1721
1722 High-performance model for agents and coding
1723
1724 - `"claude-sonnet-4-5-20250929"`
1725
1726 High-performance model for agents and coding
1727
1728 - `string`
1729
1730 - `effort: optional BetaManagedAgentsEffortLow or BetaManagedAgentsEffortMedium or BetaManagedAgentsEffortHigh or 2 more`
1731
1732 How hard Claude works on each turn. Sets `output_config.effort` on every Messages call the session makes.
1733
1734 - `BetaManagedAgentsEffortLow object`
1735
1736 Low effort. Favors latency over reasoning depth.
1737
1738 - `type: "low"`
1739
1740 - `BetaManagedAgentsEffortMedium object`
1741
1742 Medium effort. Balances latency and reasoning depth.
1743
1744 - `type: "medium"`
1745
1746 - `BetaManagedAgentsEffortHigh object`
1747
1748 High effort. Favors reasoning depth.
1749
1750 - `type: "high"`
1751
1752 - `BetaManagedAgentsEffortXhigh object`
1753
1754 Extra-high effort. Not all models accept this level.
1755
1756 - `type: "xhigh"`
1757
1758 - `BetaManagedAgentsEffortMax object`
1759
1760 Maximum effort. Favors reasoning depth over latency.
1761
1762 - `type: "max"`
1763
1764 - `inference_geo: optional string`
1765
1766 Geographic region for model inference. When unset, requests fall through to the workspace's default_inference_geo.
1767
1768 - `speed: optional "standard" or "fast"`
1769
1770 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.
1771
1772 - `"standard"`
1773
1774 - `"fast"`
1775
1776 - `multiagent: BetaManagedAgentsSessionMultiagentCoordinator or null`
1777
1778 Resolved coordinator topology with full agent definitions for each roster member.
1779
1780 - `type: "coordinator"`
1781
1782 - `agents: array of BetaManagedAgentsSessionThreadAgent or BetaManagedAgentsAdvisor`
1783
1784 Full `agent` definitions the coordinator may spawn as session threads.
1785
1786 - `BetaManagedAgentsSessionThreadAgent object`
1787
1788 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`.
1789
1790 - `type: "agent"`
1791
1792 - `id: string`
1793
1794 - `description: string or null`
1795
1796 - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition`
1797
1798 - `type: "url"`
1799
1800 - `name: string`
1801
1802 - `url: string`
1803
1804 - `model: BetaManagedAgentsModelConfig`
1805
1806 Model identifier and configuration.
1807
1808 - `name: string`
1809
1810 - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill`
1811
1812 - `BetaManagedAgentsAnthropicSkill object`
1813
1814 A resolved Anthropic-managed skill.
1815
1816 - `type: "anthropic"`
1817
1818 - `skill_id: string`
1819
1820 - `version: string`
1821
1822 - `BetaManagedAgentsCustomSkill object`
1823
1824 A resolved user-created custom skill.
1825
1826 - `type: "custom"`
1827
1828 - `skill_id: string`
1829
1830 - `version: string`
1831
1832 - `system: string or null`
1833
1834 - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool`
1835
1836 - `BetaManagedAgentsAgentToolset20260401 object`
1837
1838 - `type: "agent_toolset_20260401"`
1839
1840 - `configs: array of BetaManagedAgentsAgentToolConfig`
1841
1842 - `BetaManagedAgentsBashToolConfig object`
1843
1844 Configuration for the bash tool.
1845
1846 - `type: "bash"`
1847
1848 - `enabled: boolean`
1849
1850 - `name: "bash"`
1851
1852 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
1853
1854 Permission policy for tool execution.
1855
1856 - `BetaManagedAgentsAlwaysAllowPolicy object`
1857
1858 Tool calls are automatically approved without user confirmation.
1859
1860 - `type: "always_allow"`
1861
1862 - `BetaManagedAgentsAlwaysAskPolicy object`
1863
1864 Tool calls require user confirmation before execution.
1865
1866 - `type: "always_ask"`
1867
1868 - `BetaManagedAgentsAutoPolicy object`
1869
1870 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
1871
1872 - `type: "auto"`
1873
1874 - `BetaManagedAgentsEditToolConfig object`
1875
1876 Configuration for the edit tool.
1877
1878 - `type: "edit"`
1879
1880 - `enabled: boolean`
1881
1882 - `name: "edit"`
1883
1884 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
1885
1886 Permission policy for tool execution.
1887
1888 - `BetaManagedAgentsAlwaysAllowPolicy object`
1889
1890 Tool calls are automatically approved without user confirmation.
1891
1892 - `BetaManagedAgentsAlwaysAskPolicy object`
1893
1894 Tool calls require user confirmation before execution.
1895
1896 - `BetaManagedAgentsAutoPolicy object`
1897
1898 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
1899
1900 - `BetaManagedAgentsReadToolConfig object`
1901
1902 Configuration for the read tool.
1903
1904 - `type: "read"`
1905
1906 - `enabled: boolean`
1907
1908 - `name: "read"`
1909
1910 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
1911
1912 Permission policy for tool execution.
1913
1914 - `BetaManagedAgentsAlwaysAllowPolicy object`
1915
1916 Tool calls are automatically approved without user confirmation.
1917
1918 - `BetaManagedAgentsAlwaysAskPolicy object`
1919
1920 Tool calls require user confirmation before execution.
1921
1922 - `BetaManagedAgentsAutoPolicy object`
1923
1924 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
1925
1926 - `BetaManagedAgentsWriteToolConfig object`
1927
1928 Configuration for the write tool.
1929
1930 - `type: "write"`
1931
1932 - `enabled: boolean`
1933
1934 - `name: "write"`
1935
1936 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
1937
1938 Permission policy for tool execution.
1939
1940 - `BetaManagedAgentsAlwaysAllowPolicy object`
1941
1942 Tool calls are automatically approved without user confirmation.
1943
1944 - `BetaManagedAgentsAlwaysAskPolicy object`
1945
1946 Tool calls require user confirmation before execution.
1947
1948 - `BetaManagedAgentsAutoPolicy object`
1949
1950 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
1951
1952 - `BetaManagedAgentsGlobToolConfig object`
1953
1954 Configuration for the glob tool.
1955
1956 - `type: "glob"`
1957
1958 - `enabled: boolean`
1959
1960 - `name: "glob"`
1961
1962 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
1963
1964 Permission policy for tool execution.
1965
1966 - `BetaManagedAgentsAlwaysAllowPolicy object`
1967
1968 Tool calls are automatically approved without user confirmation.
1969
1970 - `BetaManagedAgentsAlwaysAskPolicy object`
1971
1972 Tool calls require user confirmation before execution.
1973
1974 - `BetaManagedAgentsAutoPolicy object`
1975
1976 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
1977
1978 - `BetaManagedAgentsGrepToolConfig object`
1979
1980 Configuration for the grep tool.
1981
1982 - `type: "grep"`
1983
1984 - `enabled: boolean`
1985
1986 - `name: "grep"`
1987
1988 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
1989
1990 Permission policy for tool execution.
1991
1992 - `BetaManagedAgentsAlwaysAllowPolicy object`
1993
1994 Tool calls are automatically approved without user confirmation.
1995
1996 - `BetaManagedAgentsAlwaysAskPolicy object`
1997
1998 Tool calls require user confirmation before execution.
1999
2000 - `BetaManagedAgentsAutoPolicy object`
2001
2002 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
2003
2004 - `BetaManagedAgentsWebFetchToolConfig object`
2005
2006 Configuration for the web_fetch tool.
2007
2008 - `type: "web_fetch"`
2009
2010 - `enabled: boolean`
2011
2012 - `name: "web_fetch"`
2013
2014 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
2015
2016 Permission policy for tool execution.
2017
2018 - `BetaManagedAgentsAlwaysAllowPolicy object`
2019
2020 Tool calls are automatically approved without user confirmation.
2021
2022 - `BetaManagedAgentsAlwaysAskPolicy object`
2023
2024 Tool calls require user confirmation before execution.
2025
2026 - `BetaManagedAgentsAutoPolicy object`
2027
2028 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
2029
2030 - `allowed_domains: optional array of string`
2031
2032 - `blocked_domains: optional array of string`
2033
2034 - `max_content_tokens: optional number or null`
2035
2036 format: int32
2037
2038 - `BetaManagedAgentsWebSearchToolConfig object`
2039
2040 Configuration for the web_search tool.
2041
2042 - `type: "web_search"`
2043
2044 - `enabled: boolean`
2045
2046 - `name: "web_search"`
2047
2048 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
2049
2050 Permission policy for tool execution.
2051
2052 - `BetaManagedAgentsAlwaysAllowPolicy object`
2053
2054 Tool calls are automatically approved without user confirmation.
2055
2056 - `BetaManagedAgentsAlwaysAskPolicy object`
2057
2058 Tool calls require user confirmation before execution.
2059
2060 - `BetaManagedAgentsAutoPolicy object`
2061
2062 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
2063
2064 - `allowed_domains: optional array of string`
2065
2066 - `blocked_domains: optional array of string`
2067
2068 - `user_location: optional BetaManagedAgentsUserLocation or null`
2069
2070 Approximate user location for search result localization.
2071
2072 - `type: "approximate"`
2073
2074 Location precision. Only "approximate" is supported.
2075
2076 - `city: optional string or null`
2077
2078 City name.
2079
2080 minLength: 1, maxLength: 255
2081
2082 - `country: optional string or null`
2083
2084 Two-letter ISO 3166-1 country code, uppercase.
2085
2086 - `region: optional string or null`
2087
2088 Region or state name.
2089
2090 minLength: 1, maxLength: 255
2091
2092 - `timezone: optional string or null`
2093
2094 IANA timezone identifier, e.g. "America/Los_Angeles".
2095
2096 minLength: 1, maxLength: 255
2097
2098 - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig`
2099
2100 Resolved default configuration for agent tools.
2101
2102 - `enabled: boolean`
2103
2104 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
2105
2106 Permission policy for tool execution.
2107
2108 - `BetaManagedAgentsAlwaysAllowPolicy object`
2109
2110 Tool calls are automatically approved without user confirmation.
2111
2112 - `BetaManagedAgentsAlwaysAskPolicy object`
2113
2114 Tool calls require user confirmation before execution.
2115
2116 - `BetaManagedAgentsAutoPolicy object`
2117
2118 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
2119
2120 - `BetaManagedAgentsMCPToolset object`
2121
2122 - `type: "mcp_toolset"`
2123
2124 - `configs: array of BetaManagedAgentsMCPToolConfig`
2125
2126 - `enabled: boolean`
2127
2128 - `name: string`
2129
2130 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
2131
2132 Permission policy for tool execution.
2133
2134 - `BetaManagedAgentsAlwaysAllowPolicy object`
2135
2136 Tool calls are automatically approved without user confirmation.
2137
2138 - `BetaManagedAgentsAlwaysAskPolicy object`
2139
2140 Tool calls require user confirmation before execution.
2141
2142 - `BetaManagedAgentsAutoPolicy object`
2143
2144 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
2145
2146 - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig`
2147
2148 Resolved default configuration for all tools from an MCP server.
2149
2150 - `enabled: boolean`
2151
2152 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
2153
2154 Permission policy for tool execution.
2155
2156 - `BetaManagedAgentsAlwaysAllowPolicy object`
2157
2158 Tool calls are automatically approved without user confirmation.
2159
2160 - `BetaManagedAgentsAlwaysAskPolicy object`
2161
2162 Tool calls require user confirmation before execution.
2163
2164 - `BetaManagedAgentsAutoPolicy object`
2165
2166 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
2167
2168 - `mcp_server_name: string`
2169
2170 - `BetaManagedAgentsCustomTool object`
2171
2172 A custom tool as returned in API responses.
2173
2174 - `type: "custom"`
2175
2176 - `description: string`
2177
2178 - `input_schema: BetaManagedAgentsCustomToolInputSchema`
2179
2180 JSON Schema for custom tool input parameters.
2181
2182 - `type: "object"`
2183
2184 - `properties: optional map[unknown] or null`
2185
2186 - `required: optional array of string or null`
2187
2188 - `name: string`
2189
2190 - `version: number`
2191
2192 format: int32
2193
2194 - `BetaManagedAgentsAdvisor object`
2195
2196 Platform advisor roster entry: a model the session's primary thread may consult mid-turn.
2197
2198 - `type: "advisor"`
2199
2200 - `model: string`
2201
2202 The advisor model id.
2203
2204 - `name: string`
2205
2206 - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill`
2207
2208 - `BetaManagedAgentsAnthropicSkill object`
2209
2210 A resolved Anthropic-managed skill.
2211
2212 - `BetaManagedAgentsCustomSkill object`
2213
2214 A resolved user-created custom skill.
2215
2216 - `system: string or null`
2217
2218 - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool`
2219
2220 - `BetaManagedAgentsAgentToolset20260401 object`
2221
2222 - `BetaManagedAgentsMCPToolset object`
2223
2224 - `BetaManagedAgentsCustomTool object`
2225
2226 A custom tool as returned in API responses.
2227
2228 - `version: number`
2229
2230 format: int32
2231
2232 - `budget: optional BetaManagedAgentsBudgetLimit or null`
2233
2234 A hard spend ceiling. The session stops issuing new model requests once the tracked list cost reaches `max_list_cost`.
2235
2236 - `type: "limit"`
2237
2238 - `max_list_cost: BetaMonetaryAmount`
2239
2240 A monetary amount in a specific currency.
2241
2242 - `amount: string`
2243
2244 Amount in minor units of the currency, as an integer decimal string with no leading zeros: "2500" is $25.00 and "50" is fifty cents. A string rather than a number so no float rounding is ever applied.
2245
2246 - `currency: BetaCurrency`
2247
2248 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.
2249
2250 - `metadata: optional map[string]`
2251
2252 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.
2253
2254 - `title: optional string or null`
2255
2256 The session's new title. Present only when the update changed it.
2257
2258 - `BetaManagedAgentsSystemMessageEvent object`
2259
2260 A mid-conversation system message event. Carries system-role content that is appended to the session as a `role: "system"` turn.
2261
2262 - `type: "system.message"`
2263
2264 - `id: string`
2265
2266 Unique identifier for this event.
2267
2268 - `content: array of BetaManagedAgentsSystemContentBlock`
2269
2270 System content blocks. Text-only.
2271
2272 - `type: "text"`
2273
2274 - `text: string`
2275
2276 The text content.
2277
2278 minLength: 1
3042279
3052280 - `processed_at: optional string or null`
3062281
from line 2283
3082283
3092284 format: date-time
3102285
311 - `session_thread_id: optional string or null`
312
313 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.
314
315 - `BetaManagedAgentsUserToolConfirmationEvent object`
316
317 A tool confirmation event that approves or denies a pending tool execution.
318
319 - `id: string`
320
321 Unique identifier for this event.
322
323 - `result: "allow" or "deny"`
324
325 UserToolConfirmationResult enum
326
327 - `"allow"`
328
329 - `"deny"`
330
331 - `tool_use_id: string`
332
333 The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field.
334
335 - `type: "user.tool_confirmation"`
336
337 - `deny_message: optional string or null`
338
339 Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'.
340
341 maxLength: 10000
342
343 - `processed_at: optional string or null`
344
345 A timestamp in RFC 3339 format
346
347 format: date-time
348
349 - `session_thread_id: optional string or null`
350
351 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.
352
353 - `BetaManagedAgentsUserCustomToolResultEvent object`
354
355 Event sent by the client providing the result of a custom tool execution.
356
357 - `id: string`
358
359 Unique identifier for this event.
360
361 - `custom_tool_use_id: string`
362
363 The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field.
364
365 - `type: "user.custom_tool_result"`
366
367 - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock`
368
369 The result content returned by the tool.
370
371 - `BetaManagedAgentsTextBlock object`
372
373 Regular text content.
374
375 - `BetaManagedAgentsImageBlock object`
376
377 Image content specified directly as base64 data or as a reference via a URL.
378
379 - `BetaManagedAgentsDocumentBlock object`
380
381 Document content, either specified directly as base64 data, as text, or as a reference via a URL.
382
383 - `BetaManagedAgentsSearchResultBlock object`
384
385 A block containing a web search result.
386
387 - `citations: BetaManagedAgentsSearchResultCitations`
388
389 Citation settings for a search result.
390
391 - `enabled: boolean`
392
393 Whether citations are enabled for this search result.
394
395 - `content: array of BetaManagedAgentsSearchResultContent`
396
397 Array of text content blocks from the search result.
398
399 - `text: string`
400
401 The text content.
402
403 minLength: 1
404
405 - `type: "text"`
406
407 - `source: string`
408
409 The URL source of the search result.
410
411 minLength: 1
412
413 - `title: string`
414
415 The title of the search result.
416
417 minLength: 1
418
419 - `type: "search_result"`
420
421 - `is_error: optional boolean or null`
422
423 Whether the tool execution resulted in an error.
424
425 - `processed_at: optional string or null`
426
427 A timestamp in RFC 3339 format
428
429 format: date-time
430
431 - `session_thread_id: optional string or null`
432
433 Routes this result to a subagent thread. Copy from the `agent.custom_tool_use` event's `session_thread_id`.
434
435 - `BetaManagedAgentsAgentCustomToolUseEvent object`
436
437 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.
438
439 - `id: string`
440
441 Unique identifier for this event.
442
443 - `input: map[unknown]`
444
445 Input parameters for the tool call.
446
447 - `name: string`
448
449 Name of the custom tool being called.
450
451 - `processed_at: string`
452
453 A timestamp in RFC 3339 format
454
455 format: date-time
456
457 - `type: "agent.custom_tool_use"`
458
459 - `session_thread_id: optional string or null`
460
461 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.
462
463 - `BetaManagedAgentsAgentMessageEvent object`
464
465 An agent response event in the session conversation.
466
467 - `id: string`
468
469 Unique identifier for this event.
470
471 - `content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsRedactedBlock`
472
473 Array of text blocks comprising the agent response.
474
475 - `BetaManagedAgentsTextBlock object`
476
477 Regular text content.
478
479 - `BetaManagedAgentsRedactedBlock object`
480
481 Placeholder for content withheld by Anthropic model policy.
482
483 - `processed_at: string`
484
485 A timestamp in RFC 3339 format
486
487 format: date-time
488
489 - `type: "agent.message"`
490
491 - `BetaManagedAgentsAgentThinkingEvent object`
492
493 Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier.
494
495 - `id: string`
496
497 Unique identifier for this event.
498
499 - `processed_at: string`
500
501 A timestamp in RFC 3339 format
502
503 format: date-time
504
505 - `type: "agent.thinking"`
506
507 - `BetaManagedAgentsAgentMCPToolUseEvent object`
508
509 Event emitted when the agent invokes a tool provided by an MCP server.
510
511 - `id: string`
512
513 Unique identifier for this event.
514
515 - `input: map[unknown]`
516
517 Input parameters for the tool call.
518
519 - `mcp_server_name: string`
520
521 Name of the MCP server providing the tool.
522
523 - `name: string`
524
525 Name of the MCP tool being used.
526
527 - `processed_at: string`
528
529 A timestamp in RFC 3339 format
530
531 format: date-time
532
533 - `type: "agent.mcp_tool_use"`
534
535 - `evaluated_permission: optional "allow" or "ask" or "deny"`
536
537 AgentEvaluatedPermission enum
538
539 - `"allow"`
540
541 - `"ask"`
542
543 - `"deny"`
544
545 - `session_thread_id: optional string or null`
546
547 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.
548
549 - `BetaManagedAgentsAgentMCPToolResultEvent object`
550
551 Event representing the result of an MCP tool execution.
552
553 - `id: string`
554
555 Unique identifier for this event.
556
557 - `mcp_tool_use_id: string`
558
559 The id of the `agent.mcp_tool_use` event this result corresponds to.
560
561 - `processed_at: string`
562
563 A timestamp in RFC 3339 format
564
565 format: date-time
566
567 - `type: "agent.mcp_tool_result"`
568
569 - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock`
570
571 The result content returned by the tool.
572
573 - `BetaManagedAgentsTextBlock object`
574
575 Regular text content.
576
577 - `BetaManagedAgentsImageBlock object`
578
579 Image content specified directly as base64 data or as a reference via a URL.
580
581 - `BetaManagedAgentsDocumentBlock object`
582
583 Document content, either specified directly as base64 data, as text, or as a reference via a URL.
584
585 - `BetaManagedAgentsSearchResultBlock object`
586
587 A block containing a web search result.
588
589 - `is_error: optional boolean or null`
590
591 Whether the tool execution resulted in an error.
592
593 - `BetaManagedAgentsAgentToolUseEvent object`
594
595 Event emitted when the agent invokes a built-in agent tool.
596
597 - `id: string`
598
599 Unique identifier for this event.
600
601 - `input: map[unknown]`
602
603 Input parameters for the tool call.
604
605 - `name: string`
606
607 Name of the agent tool being used.
608
609 - `processed_at: string`
610
611 A timestamp in RFC 3339 format
612
613 format: date-time
614
615 - `type: "agent.tool_use"`
616
617 - `evaluated_permission: optional "allow" or "ask" or "deny"`
618
619 AgentEvaluatedPermission enum
620
621 - `"allow"`
622
623 - `"ask"`
624
625 - `"deny"`
626
627 - `session_thread_id: optional string or null`
628
629 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.
630
631 - `BetaManagedAgentsAgentToolResultEvent object`
632
633 Event representing the result of an agent tool execution.
634
635 - `id: string`
636
637 Unique identifier for this event.
638
639 - `processed_at: string`
640
641 A timestamp in RFC 3339 format
642
643 format: date-time
644
645 - `tool_use_id: string`
646
647 The id of the `agent.tool_use` event this result corresponds to.
648
649 - `type: "agent.tool_result"`
650
651 - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock`
652
653 The result content returned by the tool.
654
655 - `BetaManagedAgentsTextBlock object`
656
657 Regular text content.
658
659 - `BetaManagedAgentsImageBlock object`
660
661 Image content specified directly as base64 data or as a reference via a URL.
662
663 - `BetaManagedAgentsDocumentBlock object`
664
665 Document content, either specified directly as base64 data, as text, or as a reference via a URL.
666
667 - `BetaManagedAgentsSearchResultBlock object`
668
669 A block containing a web search result.
670
671 - `is_error: optional boolean or null`
672
673 Whether the tool execution resulted in an error.
674
675 - `BetaManagedAgentsAgentThreadMessageReceivedEvent object`
676
677 Delivery event written to the target thread's input stream when an agent-to-agent message arrives.
678
679 - `id: string`
680
681 Unique identifier for this event.
682
683 - `content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsRedactedBlock`
684
685 Message content blocks.
686
687 - `BetaManagedAgentsTextBlock object`
688
689 Regular text content.
690
691 - `BetaManagedAgentsImageBlock object`
692
693 Image content specified directly as base64 data or as a reference via a URL.
694
695 - `BetaManagedAgentsDocumentBlock object`
696
697 Document content, either specified directly as base64 data, as text, or as a reference via a URL.
698
699 - `BetaManagedAgentsRedactedBlock object`
700
701 Placeholder for content withheld by Anthropic model policy.
702
703 - `from_session_thread_id: string`
704
705 Public `sthr_` ID of the thread that sent the message.
706
707 - `processed_at: string`
708
709 A timestamp in RFC 3339 format
710
711 format: date-time
712
713 - `type: "agent.thread_message_received"`
714
715 - `from_agent_name: optional string or null`
716
717 Name of the callable agent this message came from. Absent when received from the primary agent.
718
719 - `BetaManagedAgentsAgentThreadMessageSentEvent object`
720
721 Observability event emitted to the sender's output stream when an agent-to-agent message is sent.
722
723 - `id: string`
724
725 Unique identifier for this event.
726
727 - `content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsRedactedBlock`
728
729 Message content blocks.
730
731 - `BetaManagedAgentsTextBlock object`
732
733 Regular text content.
734
735 - `BetaManagedAgentsImageBlock object`
736
737 Image content specified directly as base64 data or as a reference via a URL.
738
739 - `BetaManagedAgentsDocumentBlock object`
740
741 Document content, either specified directly as base64 data, as text, or as a reference via a URL.
742
743 - `BetaManagedAgentsRedactedBlock object`
744
745 Placeholder for content withheld by Anthropic model policy.
746
747 - `processed_at: string`
748
749 A timestamp in RFC 3339 format
750
751 format: date-time
752
753 - `to_session_thread_id: string`
754
755 Public `sthr_` ID of the thread the message was sent to.
756
757 - `type: "agent.thread_message_sent"`
758
759 - `to_agent_name: optional string or null`
760
761 Name of the callable agent this message was sent to. Absent when sent to the primary agent.
762
763 - `BetaManagedAgentsAgentThreadContextCompactedEvent object`
764
765 Indicates that context compaction (summarization) occurred during the session.
766
767 - `id: string`
768
769 Unique identifier for this event.
770
771 - `processed_at: string`
772
773 A timestamp in RFC 3339 format
774
775 format: date-time
776
777 - `type: "agent.thread_context_compacted"`
778
779 - `BetaManagedAgentsSessionErrorEvent object`
780
781 An error event indicating a problem occurred during session execution.
782
783 - `id: string`
784
785 Unique identifier for this event.
786
787 - `error: BetaManagedAgentsUnknownError or BetaManagedAgentsModelOverloadedError or BetaManagedAgentsModelRateLimitedError or 5 more`
788
789 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.
790
791 - `BetaManagedAgentsUnknownError object`
792
793 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.
794
795 - `message: string`
796
797 Human-readable error description.
798
799 - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal`
800
801 What the client should do next in response to this error.
802
803 - `BetaManagedAgentsRetryStatusRetrying object`
804
805 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.
806
807 - `type: "retrying"`
808
809 - `BetaManagedAgentsRetryStatusExhausted object`
810
811 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
812
813 - `type: "exhausted"`
814
815 - `BetaManagedAgentsRetryStatusTerminal object`
816
817 The session encountered a terminal error and will transition to `terminated` state.
818
819 - `type: "terminal"`
820
821 - `type: "unknown_error"`
822
823 - `BetaManagedAgentsModelOverloadedError object`
824
825 The model is currently overloaded. Emitted after automatic retries are exhausted.
826
827 - `message: string`
828
829 Human-readable error description.
830
831 - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal`
832
833 What the client should do next in response to this error.
834
835 - `BetaManagedAgentsRetryStatusRetrying object`
836
837 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.
838
839 - `BetaManagedAgentsRetryStatusExhausted object`
840
841 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
842
843 - `BetaManagedAgentsRetryStatusTerminal object`
844
845 The session encountered a terminal error and will transition to `terminated` state.
846
847 - `type: "model_overloaded_error"`
848
849 - `BetaManagedAgentsModelRateLimitedError object`
850
851 The model request was rate-limited.
852
853 - `message: string`
854
855 Human-readable error description.
856
857 - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal`
858
859 What the client should do next in response to this error.
860
861 - `BetaManagedAgentsRetryStatusRetrying object`
862
863 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.
864
865 - `BetaManagedAgentsRetryStatusExhausted object`
866
867 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
868
869 - `BetaManagedAgentsRetryStatusTerminal object`
870
871 The session encountered a terminal error and will transition to `terminated` state.
872
873 - `type: "model_rate_limited_error"`
874
875 - `BetaManagedAgentsModelRequestFailedError object`
876
877 A model request failed for a reason other than overload or rate-limiting.
878
879 - `message: string`
880
881 Human-readable error description.
882
883 - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal`
884
885 What the client should do next in response to this error.
886
887 - `BetaManagedAgentsRetryStatusRetrying object`
888
889 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.
890
891 - `BetaManagedAgentsRetryStatusExhausted object`
892
893 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
894
895 - `BetaManagedAgentsRetryStatusTerminal object`
896
897 The session encountered a terminal error and will transition to `terminated` state.
898
899 - `type: "model_request_failed_error"`
900
901 - `BetaManagedAgentsMCPConnectionFailedError object`
902
903 Failed to connect to an MCP server.
904
905 - `mcp_server_name: string`
906
907 Name of the MCP server that failed to connect.
908
909 - `message: string`
910
911 Human-readable error description.
912
913 - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal`
914
915 What the client should do next in response to this error.
916
917 - `BetaManagedAgentsRetryStatusRetrying object`
918
919 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.
920
921 - `BetaManagedAgentsRetryStatusExhausted object`
922
923 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
924
925 - `BetaManagedAgentsRetryStatusTerminal object`
926
927 The session encountered a terminal error and will transition to `terminated` state.
928
929 - `type: "mcp_connection_failed_error"`
930
931 - `BetaManagedAgentsMCPAuthenticationFailedError object`
932
933 Authentication to an MCP server failed.
934
935 - `mcp_server_name: string`
936
937 Name of the MCP server that failed authentication.
938
939 - `message: string`
940
941 Human-readable error description.
942
943 - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal`
944
945 What the client should do next in response to this error.
946
947 - `BetaManagedAgentsRetryStatusRetrying object`
948
949 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.
950
951 - `BetaManagedAgentsRetryStatusExhausted object`
952
953 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
954
955 - `BetaManagedAgentsRetryStatusTerminal object`
956
957 The session encountered a terminal error and will transition to `terminated` state.
958
959 - `type: "mcp_authentication_failed_error"`
960
961 - `BetaManagedAgentsBillingError object`
962
963 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.
964
965 - `message: string`
966
967 Human-readable error description.
968
969 - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal`
970
971 What the client should do next in response to this error.
972
973 - `BetaManagedAgentsRetryStatusRetrying object`
974
975 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.
976
977 - `BetaManagedAgentsRetryStatusExhausted object`
978
979 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
980
981 - `BetaManagedAgentsRetryStatusTerminal object`
982
983 The session encountered a terminal error and will transition to `terminated` state.
984
985 - `type: "billing_error"`
986
987 - `BetaManagedAgentsCredentialHostUnreachableError object`
988
989 An `environment_variable` credential's `auth.networking.allowed_hosts` includes a host the environment's network policy does not permit.
990
991 - `credential_id: string`
992
993 ID of the affected credential.
994
995 - `message: string`
996
997 Human-readable error description.
998
999 - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal`
1000
1001 What the client should do next in response to this error.
1002
1003 - `BetaManagedAgentsRetryStatusRetrying object`
1004
1005 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.
1006
1007 - `BetaManagedAgentsRetryStatusExhausted object`
1008
1009 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
1010
1011 - `BetaManagedAgentsRetryStatusTerminal object`
1012
1013 The session encountered a terminal error and will transition to `terminated` state.
1014
1015 - `type: "credential_host_unreachable_error"`
1016
1017 - `vault_id: string`
1018
1019 ID of the vault containing the affected credential.
1020
1021 - `processed_at: string`
1022
1023 A timestamp in RFC 3339 format
1024
1025 format: date-time
1026
1027 - `type: "session.error"`
1028
1029 - `BetaManagedAgentsSessionStatusRescheduledEvent object`
1030
1031 Indicates the session is recovering from an error state and is rescheduled for execution.
1032
1033 - `id: string`
1034
1035 Unique identifier for this event.
1036
1037 - `processed_at: string`
1038
1039 A timestamp in RFC 3339 format
1040
1041 format: date-time
1042
1043 - `type: "session.status_rescheduled"`
1044
1045 - `BetaManagedAgentsSessionStatusRunningEvent object`
1046
1047 Indicates the session is actively running and the agent is working.
1048
1049 - `id: string`
1050
1051 Unique identifier for this event.
1052
1053 - `processed_at: string`
1054
1055 A timestamp in RFC 3339 format
1056
1057 format: date-time
1058
1059 - `type: "session.status_running"`
1060
1061 - `BetaManagedAgentsSessionStatusIdleEvent object`
1062
1063 Indicates the agent has paused and is awaiting user input.
1064
1065 - `id: string`
1066
1067 Unique identifier for this event.
1068
1069 - `processed_at: string`
1070
1071 A timestamp in RFC 3339 format
1072
1073 format: date-time
1074
1075 - `stop_reason: BetaManagedAgentsSessionEndTurn or BetaManagedAgentsSessionRequiresAction or BetaManagedAgentsSessionRetriesExhausted or BetaManagedAgentsSessionBudgetReached`
1076
1077 The agent completed its turn naturally and is ready for the next user message.
1078
1079 - `BetaManagedAgentsSessionEndTurn object`
1080
1081 The agent completed its turn naturally and is ready for the next user message.
1082
1083 - `type: "end_turn"`
1084
1085 - `BetaManagedAgentsSessionRequiresAction object`
1086
1087 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.
1088
1089 - `event_ids: array of string`
1090
1091 The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder.
1092
1093 - `type: "requires_action"`
1094
1095 - `BetaManagedAgentsSessionRetriesExhausted object`
1096
1097 The turn ended because repeated errors exhausted the retry budget or an error escalated to `retry_status: 'exhausted'`.
1098
1099 - `type: "retries_exhausted"`
1100
1101 - `BetaManagedAgentsSessionBudgetReached object`
1102
1103 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.
1104
1105 - `type: "budget_reached"`
1106
1107 - `type: "session.status_idle"`
1108
1109 - `BetaManagedAgentsSessionStatusTerminatedEvent object`
1110
1111 Indicates the session has terminated, either due to an error or completion.
1112
1113 - `id: string`
1114
1115 Unique identifier for this event.
1116
1117 - `processed_at: string`
1118
1119 A timestamp in RFC 3339 format
1120
1121 format: date-time
1122
1123 - `type: "session.status_terminated"`
1124
1125 - `BetaManagedAgentsSessionThreadCreatedEvent object`
1126
1127 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.
1128
1129 - `id: string`
1130
1131 Unique identifier for this event.
1132
1133 - `agent_name: string`
1134
1135 Name of the callable agent the thread runs.
1136
1137 - `processed_at: string`
1138
1139 A timestamp in RFC 3339 format
1140
1141 format: date-time
1142
1143 - `session_thread_id: string`
1144
1145 Public `sthr_` ID of the newly created thread.
1146
1147 - `type: "session.thread_created"`
1148
1149 - `BetaManagedAgentsSpanOutcomeEvaluationStartEvent object`
1150
1151 Emitted when an outcome evaluation cycle begins.
1152
1153 - `id: string`
1154
1155 Unique identifier for this event.
1156
1157 - `iteration: number`
1158
1159 0-indexed revision cycle. 0 is the first evaluation; 1 is the re-evaluation after the first revision; etc.
1160
1161 format: int32
1162
1163 - `outcome_id: string`
1164
1165 The `outc_` ID of the outcome being evaluated.
1166
1167 - `processed_at: string`
1168
1169 A timestamp in RFC 3339 format
1170
1171 format: date-time
1172
1173 - `type: "span.outcome_evaluation_start"`
1174
1175 - `BetaManagedAgentsSpanOutcomeEvaluationEndEvent object`
1176
1177 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.
1178
1179 - `id: string`
1180
1181 Unique identifier for this event.
1182
1183 - `explanation: string`
1184
1185 Human-readable explanation of the verdict. For `needs_revision`, describes which criteria failed and why.
1186
1187 - `iteration: number`
1188
1189 0-indexed revision cycle, matching the corresponding `span.outcome_evaluation_start`.
1190
1191 format: int32
1192
1193 - `outcome_evaluation_start_id: string`
1194
1195 The id of the corresponding `span.outcome_evaluation_start` event.
1196
1197 - `outcome_id: string`
1198
1199 The `outc_` ID of the outcome being evaluated.
1200
1201 - `processed_at: string`
1202
1203 A timestamp in RFC 3339 format
1204
1205 format: date-time
1206
1207 - `result: string`
1208
1209 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.
1210
1211 - `type: "span.outcome_evaluation_end"`
1212
1213 - `usage: BetaManagedAgentsSpanModelUsage`
1214
1215 Token usage for a single model request.
1216
1217 - `cache_creation_input_tokens: number`
1218
1219 Tokens used to create prompt cache in this request.
1220
1221 format: int32
1222
1223 - `cache_read_input_tokens: number`
1224
1225 Tokens read from prompt cache in this request.
1226
1227 format: int32
1228
1229 - `input_tokens: number`
1230
1231 Input tokens consumed by this request.
1232
1233 format: int32
1234
1235 - `output_tokens: number`
1236
1237 Output tokens generated by this request.
1238
1239 format: int32
1240
1241 - `speed: optional "standard" or "fast" or null`
1242
1243 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.
1244
1245 - `"standard"`
1246
1247 - `"fast"`
1248
1249 - `BetaManagedAgentsSpanModelRequestStartEvent object`
1250
1251 Emitted when a model request is initiated by the agent.
1252
1253 - `id: string`
1254
1255 Unique identifier for this event.
1256
1257 - `processed_at: string`
1258
1259 A timestamp in RFC 3339 format
1260
1261 format: date-time
1262
1263 - `type: "span.model_request_start"`
1264
1265 - `BetaManagedAgentsSpanModelRequestEndEvent object`
1266
1267 Emitted when a model request completes.
1268
1269 - `id: string`
1270
1271 Unique identifier for this event.
1272
1273 - `is_error: boolean or null`
1274
1275 Whether the model request resulted in an error.
1276
1277 - `model_request_start_id: string`
1278
1279 The id of the corresponding `span.model_request_start` event.
1280
1281 - `model_usage: BetaManagedAgentsSpanModelUsage`
1282
1283 Token usage for a single model request.
1284
1285 - `processed_at: string`
1286
1287 A timestamp in RFC 3339 format
1288
1289 format: date-time
1290
1291 - `type: "span.model_request_end"`
1292
1293 - `BetaManagedAgentsSpanOutcomeEvaluationOngoingEvent object`
1294
1295 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.
1296
1297 - `id: string`
1298
1299 Unique identifier for this event.
1300
1301 - `iteration: number`
1302
1303 0-indexed revision cycle, matching the corresponding `span.outcome_evaluation_start`.
1304
1305 format: int32
1306
1307 - `outcome_id: string`
1308
1309 The `outc_` ID of the outcome being evaluated.
1310
1311 - `processed_at: string`
1312
1313 A timestamp in RFC 3339 format
1314
1315 format: date-time
1316
1317 - `type: "span.outcome_evaluation_ongoing"`
1318
1319 - `BetaManagedAgentsUserDefineOutcomeEvent object`
1320
1321 Echo of a `user.define_outcome` input event. Carries the server-generated `outcome_id` that subsequent `span.outcome_evaluation_*` events reference.
1322
1323 - `id: string`
1324
1325 Unique identifier for this event.
1326
1327 - `description: string`
1328
1329 What the agent should produce. Copied from the input event.
1330
1331 - `max_iterations: number or null`
1332
1333 Evaluate-then-revise cycles before giving up. Default 3, max 20.
1334
1335 format: int32
1336
1337 - `outcome_id: string`
1338
1339 Server-generated `outc_` ID for this outcome. Referenced by `span.outcome_evaluation_*` events and the session's `outcome_evaluations` list.
1340
1341 - `processed_at: string`
1342
1343 A timestamp in RFC 3339 format
1344
1345 format: date-time
1346
1347 - `rubric: BetaManagedAgentsFileRubric or BetaManagedAgentsTextRubric`
1348
1349 Rubric for grading the quality of an outcome.
1350
1351 - `BetaManagedAgentsFileRubric object`
1352
1353 Rubric referenced by a file uploaded via the Files API.
1354
1355 - `file_id: string`
1356
1357 ID of the rubric file.
1358
1359 - `type: "file"`
1360
1361 - `BetaManagedAgentsTextRubric object`
1362
1363 Rubric content provided inline as text.
1364
1365 - `content: string`
1366
1367 Rubric content. Plain text or markdown — the grader treats it as freeform text.
1368
1369 - `type: "text"`
1370
1371 - `type: "user.define_outcome"`
1372
1373 - `BetaManagedAgentsSessionDeletedEvent object`
1374
1375 Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session.
1376
1377 - `id: string`
1378
1379 Unique identifier for this event.
1380
1381 - `processed_at: string`
1382
1383 A timestamp in RFC 3339 format
1384
1385 format: date-time
1386
1387 - `type: "session.deleted"`
1388
1389 - `BetaManagedAgentsSessionThreadStatusRunningEvent object`
1390
1391 A session thread has begun executing. Emitted on the thread's own stream and cross-posted to the primary stream for child threads.
1392
1393 - `id: string`
1394
1395 Unique identifier for this event.
1396
1397 - `agent_name: string`
1398
1399 Name of the agent the thread runs.
1400
1401 - `processed_at: string`
1402
1403 A timestamp in RFC 3339 format
1404
1405 format: date-time
1406
1407 - `session_thread_id: string`
1408
1409 Public sthr_ ID of the thread that started running.
1410
1411 - `type: "session.thread_status_running"`
1412
1413 - `BetaManagedAgentsSessionThreadStatusIdleEvent object`
1414
1415 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.
1416
1417 - `id: string`
1418
1419 Unique identifier for this event.
1420
1421 - `agent_name: string`
1422
1423 Name of the agent the thread runs.
1424
1425 - `processed_at: string`
1426
1427 A timestamp in RFC 3339 format
1428
1429 format: date-time
1430
1431 - `session_thread_id: string`
1432
1433 Public sthr_ ID of the thread that went idle.
1434
1435 - `stop_reason: BetaManagedAgentsSessionEndTurn or BetaManagedAgentsSessionRequiresAction or BetaManagedAgentsSessionRetriesExhausted or BetaManagedAgentsSessionBudgetReached`
1436
1437 The agent completed its turn naturally and is ready for the next user message.
1438
1439 - `BetaManagedAgentsSessionEndTurn object`
1440
1441 The agent completed its turn naturally and is ready for the next user message.
1442
1443 - `BetaManagedAgentsSessionRequiresAction object`
1444
1445 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.
1446
1447 - `BetaManagedAgentsSessionRetriesExhausted object`
1448
1449 The turn ended because repeated errors exhausted the retry budget or an error escalated to `retry_status: 'exhausted'`.
1450
1451 - `BetaManagedAgentsSessionBudgetReached object`
1452
1453 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.
1454
1455 - `type: "session.thread_status_idle"`
1456
1457 - `BetaManagedAgentsSessionThreadStatusTerminatedEvent object`
1458
1459 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.
1460
1461 - `id: string`
1462
1463 Unique identifier for this event.
1464
1465 - `agent_name: string`
1466
1467 Name of the agent the thread runs.
1468
1469 - `processed_at: string`
1470
1471 A timestamp in RFC 3339 format
1472
1473 format: date-time
1474
1475 - `session_thread_id: string`
1476
1477 Public sthr_ ID of the thread that terminated.
1478
1479 - `type: "session.thread_status_terminated"`
1480
1481 - `BetaManagedAgentsUserToolResultEvent object`
1482
1483 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.
1484
1485 - `id: string`
1486
1487 Unique identifier for this event.
1488
1489 - `tool_use_id: string`
1490
1491 The id of the `agent.tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field.
1492
1493 - `type: "user.tool_result"`
1494
1495 - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock`
1496
1497 The result content returned by the tool.
1498
1499 - `BetaManagedAgentsTextBlock object`
1500
1501 Regular text content.
1502
1503 - `BetaManagedAgentsImageBlock object`
1504
1505 Image content specified directly as base64 data or as a reference via a URL.
1506
1507 - `BetaManagedAgentsDocumentBlock object`
1508
1509 Document content, either specified directly as base64 data, as text, or as a reference via a URL.
1510
1511 - `BetaManagedAgentsSearchResultBlock object`
1512
1513 A block containing a web search result.
1514
1515 - `is_error: optional boolean or null`
1516
1517 Whether the tool execution resulted in an error.
1518
1519 - `processed_at: optional string or null`
1520
1521 A timestamp in RFC 3339 format
1522
1523 format: date-time
1524
1525 - `session_thread_id: optional string or null`
1526
1527 Routes this result to a subagent thread. Copy from the `agent.tool_use` event's `session_thread_id`.
1528
1529 - `BetaManagedAgentsSessionThreadStatusRescheduledEvent object`
1530
1531 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.
1532
1533 - `id: string`
1534
1535 Unique identifier for this event.
1536
1537 - `agent_name: string`
1538
1539 Name of the agent the thread runs.
1540
1541 - `processed_at: string`
1542
1543 A timestamp in RFC 3339 format
1544
1545 format: date-time
1546
1547 - `session_thread_id: string`
1548
1549 Public sthr_ ID of the thread that is retrying.
1550
1551 - `type: "session.thread_status_rescheduled"`
1552
1553 - `BetaManagedAgentsSessionUpdatedEvent object`
1554
1555 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.
1556
1557 - `id: string`
1558
1559 Unique identifier for this event.
1560
1561 - `processed_at: string`
1562
1563 A timestamp in RFC 3339 format
1564
1565 format: date-time
1566
1567 - `type: "session.updated"`
1568
1569 - `agent: optional BetaManagedAgentsSessionAgent or null`
1570
1571 Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time.
1572
1573 - `id: string`
1574
1575 - `description: string or null`
1576
1577 - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition`
1578
1579 - `name: string`
1580
1581 - `type: "url"`
1582
1583 - `url: string`
1584
1585 - `model: BetaManagedAgentsModelConfig`
1586
1587 Model identifier and configuration.
1588
1589 - `id: BetaManagedAgentsModel`
1590
1591 The model that will power your agent.
1592
1593 See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options.
1594
1595 - `"claude-fable-5-1" or "claude-sonnet-5" or "claude-fable-5" or 11 more`
1596
1597 The model that will power your agent.
1598
1599 See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options.
1600
1601 - `"claude-fable-5-1"`
1602
1603 Frontier intelligence for ambitious tasks across coding, scientific discovery, and enterprise workflows
1604
1605 - `"claude-sonnet-5"`
1606
1607 High-performance model for coding and agents
1608
1609 - `"claude-fable-5"`
1610
1611 Next generation of intelligence for the hardest knowledge work and coding problems
1612
1613 - `"claude-opus-5"`
1614
1615 Powerful intelligence for long-running agents and coding
1616
1617 - `"claude-opus-4-8"`
1618
1619 Powerful intelligence for long-running agents and coding
1620
1621 - `"claude-opus-4-7"`
1622
1623 Powerful intelligence for long-running agents and coding
1624
1625 - `"claude-opus-4-6"`
1626
1627 Powerful intelligence for long-running agents and coding
1628
1629 - `"claude-sonnet-4-6"`
1630
1631 Best combination of speed and intelligence
1632
1633 - `"claude-haiku-4-5"`
1634
1635 Fastest model with near-frontier intelligence
1636
1637 - `"claude-haiku-4-5-20251001"`
1638
1639 Fastest model with near-frontier intelligence
1640
1641 - `"claude-opus-4-5"`
1642
1643 Powerful intelligence for long-running agents and coding
1644
1645 - `"claude-opus-4-5-20251101"`
1646
1647 Powerful intelligence for long-running agents and coding
1648
1649 - `"claude-sonnet-4-5"`
1650
1651 High-performance model for agents and coding
1652
1653 - `"claude-sonnet-4-5-20250929"`
1654
1655 High-performance model for agents and coding
1656
1657 - `string`
1658
1659 - `effort: optional BetaManagedAgentsEffortLow or BetaManagedAgentsEffortMedium or BetaManagedAgentsEffortHigh or 2 more`
1660
1661 How hard Claude works on each turn. Sets `output_config.effort` on every Messages call the session makes.
1662
1663 - `BetaManagedAgentsEffortLow object`
1664
1665 Low effort. Favors latency over reasoning depth.
1666
1667 - `type: "low"`
1668
1669 - `BetaManagedAgentsEffortMedium object`
1670
1671 Medium effort. Balances latency and reasoning depth.
1672
1673 - `type: "medium"`
1674
1675 - `BetaManagedAgentsEffortHigh object`
1676
1677 High effort. Favors reasoning depth.
1678
1679 - `type: "high"`
1680
1681 - `BetaManagedAgentsEffortXhigh object`
1682
1683 Extra-high effort. Not all models accept this level.
1684
1685 - `type: "xhigh"`
1686
1687 - `BetaManagedAgentsEffortMax object`
1688
1689 Maximum effort. Favors reasoning depth over latency.
1690
1691 - `type: "max"`
1692
1693 - `inference_geo: optional string`
1694
1695 Geographic region for model inference. When unset, requests fall through to the workspace's default_inference_geo.
1696
1697 - `speed: optional "standard" or "fast"`
1698
1699 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.
1700
1701 - `"standard"`
1702
1703 - `"fast"`
1704
1705 - `multiagent: BetaManagedAgentsSessionMultiagentCoordinator or null`
1706
1707 Resolved coordinator topology with full agent definitions for each roster member.
1708
1709 - `agents: array of BetaManagedAgentsSessionThreadAgent or BetaManagedAgentsAdvisor`
1710
1711 Full `agent` definitions the coordinator may spawn as session threads.
1712
1713 - `BetaManagedAgentsSessionThreadAgent object`
1714
1715 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`.
1716
1717 - `id: string`
1718
1719 - `description: string or null`
1720
1721 - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition`
1722
1723 - `name: string`
1724
1725 - `type: "url"`
1726
1727 - `url: string`
1728
1729 - `model: BetaManagedAgentsModelConfig`
1730
1731 Model identifier and configuration.
1732
1733 - `name: string`
1734
1735 - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill`
1736
1737 - `BetaManagedAgentsAnthropicSkill object`
1738
1739 A resolved Anthropic-managed skill.
1740
1741 - `skill_id: string`
1742
1743 - `type: "anthropic"`
1744
1745 - `version: string`
1746
1747 - `BetaManagedAgentsCustomSkill object`
1748
1749 A resolved user-created custom skill.
1750
1751 - `skill_id: string`
1752
1753 - `type: "custom"`
1754
1755 - `version: string`
1756
1757 - `system: string or null`
1758
1759 - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool`
1760
1761 - `BetaManagedAgentsAgentToolset20260401 object`
1762
1763 - `configs: array of BetaManagedAgentsAgentToolConfig`
1764
1765 - `BetaManagedAgentsBashToolConfig object`
1766
1767 Configuration for the bash tool.
1768
1769 - `enabled: boolean`
1770
1771 - `name: "bash"`
1772
1773 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
1774
1775 Permission policy for tool execution.
1776
1777 - `BetaManagedAgentsAlwaysAllowPolicy object`
1778
1779 Tool calls are automatically approved without user confirmation.
1780
1781 - `type: "always_allow"`
1782
1783 - `BetaManagedAgentsAlwaysAskPolicy object`
1784
1785 Tool calls require user confirmation before execution.
1786
1787 - `type: "always_ask"`
1788
1789 - `type: "bash"`
1790
1791 - `BetaManagedAgentsEditToolConfig object`
1792
1793 Configuration for the edit tool.
1794
1795 - `enabled: boolean`
1796
1797 - `name: "edit"`
1798
1799 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
1800
1801 Permission policy for tool execution.
1802
1803 - `BetaManagedAgentsAlwaysAllowPolicy object`
1804
1805 Tool calls are automatically approved without user confirmation.
1806
1807 - `BetaManagedAgentsAlwaysAskPolicy object`
1808
1809 Tool calls require user confirmation before execution.
1810
1811 - `type: "edit"`
1812
1813 - `BetaManagedAgentsReadToolConfig object`
1814
1815 Configuration for the read tool.
1816
1817 - `enabled: boolean`
1818
1819 - `name: "read"`
1820
1821 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
1822
1823 Permission policy for tool execution.
1824
1825 - `BetaManagedAgentsAlwaysAllowPolicy object`
1826
1827 Tool calls are automatically approved without user confirmation.
1828
1829 - `BetaManagedAgentsAlwaysAskPolicy object`
1830
1831 Tool calls require user confirmation before execution.
1832
1833 - `type: "read"`
1834
1835 - `BetaManagedAgentsWriteToolConfig object`
1836
1837 Configuration for the write tool.
1838
1839 - `enabled: boolean`
1840
1841 - `name: "write"`
1842
1843 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
1844
1845 Permission policy for tool execution.
1846
1847 - `BetaManagedAgentsAlwaysAllowPolicy object`
1848
1849 Tool calls are automatically approved without user confirmation.
1850
1851 - `BetaManagedAgentsAlwaysAskPolicy object`
1852
1853 Tool calls require user confirmation before execution.
1854
1855 - `type: "write"`
1856
1857 - `BetaManagedAgentsGlobToolConfig object`
1858
1859 Configuration for the glob tool.
1860
1861 - `enabled: boolean`
1862
1863 - `name: "glob"`
1864
1865 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
1866
1867 Permission policy for tool execution.
1868
1869 - `BetaManagedAgentsAlwaysAllowPolicy object`
1870
1871 Tool calls are automatically approved without user confirmation.
1872
1873 - `BetaManagedAgentsAlwaysAskPolicy object`
1874
1875 Tool calls require user confirmation before execution.
1876
1877 - `type: "glob"`
1878
1879 - `BetaManagedAgentsGrepToolConfig object`
1880
1881 Configuration for the grep tool.
1882
1883 - `enabled: boolean`
1884
1885 - `name: "grep"`
1886
1887 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
1888
1889 Permission policy for tool execution.
1890
1891 - `BetaManagedAgentsAlwaysAllowPolicy object`
1892
1893 Tool calls are automatically approved without user confirmation.
1894
1895 - `BetaManagedAgentsAlwaysAskPolicy object`
1896
1897 Tool calls require user confirmation before execution.
1898
1899 - `type: "grep"`
1900
1901 - `BetaManagedAgentsWebFetchToolConfig object`
1902
1903 Configuration for the web_fetch tool.
1904
1905 - `enabled: boolean`
1906
1907 - `name: "web_fetch"`
1908
1909 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
1910
1911 Permission policy for tool execution.
1912
1913 - `BetaManagedAgentsAlwaysAllowPolicy object`
1914
1915 Tool calls are automatically approved without user confirmation.
1916
1917 - `BetaManagedAgentsAlwaysAskPolicy object`
1918
1919 Tool calls require user confirmation before execution.
1920
1921 - `type: "web_fetch"`
1922
1923 - `allowed_domains: optional array of string`
1924
1925 - `blocked_domains: optional array of string`
1926
1927 - `max_content_tokens: optional number or null`
1928
1929 format: int32
1930
1931 - `BetaManagedAgentsWebSearchToolConfig object`
1932
1933 Configuration for the web_search tool.
1934
1935 - `enabled: boolean`
1936
1937 - `name: "web_search"`
1938
1939 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
1940
1941 Permission policy for tool execution.
1942
1943 - `BetaManagedAgentsAlwaysAllowPolicy object`
1944
1945 Tool calls are automatically approved without user confirmation.
1946
1947 - `BetaManagedAgentsAlwaysAskPolicy object`
1948
1949 Tool calls require user confirmation before execution.
1950
1951 - `type: "web_search"`
1952
1953 - `allowed_domains: optional array of string`
1954
1955 - `blocked_domains: optional array of string`
1956
1957 - `user_location: optional BetaManagedAgentsUserLocation or null`
1958
1959 Approximate user location for search result localization.
1960
1961 - `type: "approximate"`
1962
1963 Location precision. Only "approximate" is supported.
1964
1965 - `city: optional string or null`
1966
1967 City name.
1968
1969 minLength: 1, maxLength: 255
1970
1971 - `country: optional string or null`
1972
1973 Two-letter ISO 3166-1 country code, uppercase.
1974
1975 - `region: optional string or null`
1976
1977 Region or state name.
1978
1979 minLength: 1, maxLength: 255
1980
1981 - `timezone: optional string or null`
1982
1983 IANA timezone identifier, e.g. "America/Los_Angeles".
1984
1985 minLength: 1, maxLength: 255
1986
1987 - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig`
1988
1989 Resolved default configuration for agent tools.
1990
1991 - `enabled: boolean`
1992
1993 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
1994
1995 Permission policy for tool execution.
1996
1997 - `BetaManagedAgentsAlwaysAllowPolicy object`
1998
1999 Tool calls are automatically approved without user confirmation.
2000
2001 - `BetaManagedAgentsAlwaysAskPolicy object`
2002
2003 Tool calls require user confirmation before execution.
2004
2005 - `type: "agent_toolset_20260401"`
2006
2007 - `BetaManagedAgentsMCPToolset object`
2008
2009 - `configs: array of BetaManagedAgentsMCPToolConfig`
2010
2011 - `enabled: boolean`
2012
2013 - `name: string`
2014
2015 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
2016
2017 Permission policy for tool execution.
2018
2019 - `BetaManagedAgentsAlwaysAllowPolicy object`
2020
2021 Tool calls are automatically approved without user confirmation.
2022
2023 - `BetaManagedAgentsAlwaysAskPolicy object`
2024
2025 Tool calls require user confirmation before execution.
2026
2027 - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig`
2028
2029 Resolved default configuration for all tools from an MCP server.
2030
2031 - `enabled: boolean`
2032
2033 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
2034
2035 Permission policy for tool execution.
2036
2037 - `BetaManagedAgentsAlwaysAllowPolicy object`
2038
2039 Tool calls are automatically approved without user confirmation.
2040
2041 - `BetaManagedAgentsAlwaysAskPolicy object`
2042
2043 Tool calls require user confirmation before execution.
2044
2045 - `mcp_server_name: string`
2046
2047 - `type: "mcp_toolset"`
2048
2049 - `BetaManagedAgentsCustomTool object`
2050
2051 A custom tool as returned in API responses.
2052
2053 - `description: string`
2054
2055 - `input_schema: BetaManagedAgentsCustomToolInputSchema`
2056
2057 JSON Schema for custom tool input parameters.
2058
2059 - `type: "object"`
2060
2061 - `properties: optional map[unknown] or null`
2062
2063 - `required: optional array of string or null`
2064
2065 - `name: string`
2066
2067 - `type: "custom"`
2068
2069 - `type: "agent"`
2070
2071 - `version: number`
2072
2073 format: int32
2074
2075 - `BetaManagedAgentsAdvisor object`
2076
2077 Platform advisor roster entry: a model the session's primary thread may consult mid-turn.
2078
2079 - `model: string`
2080
2081 The advisor model id.
2082
2083 - `type: "advisor"`
2084
2085 - `type: "coordinator"`
2086
2087 - `name: string`
2088
2089 - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill`
2090
2091 - `BetaManagedAgentsAnthropicSkill object`
2092
2093 A resolved Anthropic-managed skill.
2094
2095 - `BetaManagedAgentsCustomSkill object`
2096
2097 A resolved user-created custom skill.
2098
2099 - `system: string or null`
2100
2101 - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool`
2102
2103 - `BetaManagedAgentsAgentToolset20260401 object`
2104
2105 - `BetaManagedAgentsMCPToolset object`
2106
2107 - `BetaManagedAgentsCustomTool object`
2108
2109 A custom tool as returned in API responses.
2110
2111 - `type: "agent"`
2112
2113 - `version: number`
2114
2115 format: int32
2116
2117 - `budget: optional BetaManagedAgentsBudgetLimit or null`
2118
2119 A hard spend ceiling. The session stops issuing new model requests once the tracked list cost reaches `max_list_cost`.
2120
2121 - `max_list_cost: BetaMonetaryAmount`
2122
2123 A monetary amount in a specific currency.
2124
2125 - `amount: string`
2126
2127 Amount in minor units of the currency, as an integer decimal string with no leading zeros: "2500" is $25.00 and "50" is fifty cents. A string rather than a number so no float rounding is ever applied.
2128
2129 - `currency: BetaCurrency`
2130
2131 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.
2132
2133 - `type: "limit"`
2134
2135 - `metadata: optional map[string]`
2136
2137 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.
2138
2139 - `title: optional string or null`
2140
2141 The session's new title. Present only when the update changed it.
2142
2143 - `BetaManagedAgentsSystemMessageEvent object`
2144
2145 A mid-conversation system message event. Carries system-role content that is appended to the session as a `role: "system"` turn.
2146
2147 - `id: string`
2148
2149 Unique identifier for this event.
2150
2151 - `content: array of BetaManagedAgentsSystemContentBlock`
2152
2153 System content blocks. Text-only.
2154
2155 - `text: string`
2156
2157 The text content.
2158
2159 minLength: 1
2160
2161 - `type: "text"`
2162
2163 - `type: "system.message"`
2164
2165 - `processed_at: optional string or null`
2166
2167 A timestamp in RFC 3339 format
2168
2169 format: date-time
2170
21712286 - `BetaManagedAgentsSessionUsageEvent object`
21722287
21732288 Periodic snapshot of the session's cumulative usage and tracked list cost.
21742289
2175 - `id: string`
2176
2177 Unique identifier for this event.
2178
2179 - `processed_at: string`
2180
2181 A timestamp in RFC 3339 format
2182
2183 format: date-time
2184
21852290 - `type: "session.usage"`
2291
2292 - `id: string`
2293
2294 Unique identifier for this event.
2295
2296 - `processed_at: string`
2297
2298 A timestamp in RFC 3339 format
2299
2300 format: date-time
21862301
21872302 - `usage: BetaManagedAgentsSessionUsageSnapshot`
21882303
21892304
api/beta/sessions/threads/events/stream Changed · +2174 / -2059 lines
The two sides of this change are more than 400 edits apart, too far apart to line up, so this is the differ's own diff of it and the words inside a line are not marked.
from line 1
1---
2title: Stream Session Thread Events
3url: https://platform.claude.com/docs/en/api/beta/sessions/threads/events/stream
4---
5
16# Stream Session Thread Events
27
38**GET** `/v1/sessions/{session_id}/threads/{thread_id}/stream`
from line 33
2833
2934 - `string`
3035
31 - `"message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 41 more`
36 - `"message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 42 more`
3237
3338 - `"message-batches-2024-09-24"`
3439
from line 81
7681
7782 - `"user-profiles-2026-08-18"`
7883
84 - `"user-profiles-2026-09-04"`
85
7986 - `"advisor-tool-2026-03-01"`
8087
8188 - `"managed-agents-2026-04-01"`
from line 125
118125
119126 - `"mid-conversation-system-clear-at-2026-08-21"`
120127
128- `"anthropic-workspace-id": optional string`
129
121130## Returns
122131
123132- `BetaManagedAgentsStreamSessionThreadEvents = BetaManagedAgentsUserMessageEvent or BetaManagedAgentsUserInterruptEvent or BetaManagedAgentsUserToolConfirmationEvent or 34 more`
from line 137
128137
129138 A user message event in the session conversation.
130139
140 - `type: "user.message"`
141
131142 - `id: string`
132143
133144 Unique identifier for this event.
from line 151
140151
141152 Regular text content.
142153
154 - `type: "text"`
155
143156 - `text: string`
144157
145158 The text content.
146159
147160 minLength: 1
148161
162 - `BetaManagedAgentsImageBlock object`
163
164 Image content specified directly as base64 data or as a reference via a URL.
165
166 - `type: "image"`
167
168 - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource`
169
170 Union type for image source variants.
171
172 - `BetaManagedAgentsBase64ImageSource object`
173
174 Base64-encoded image data.
175
176 - `type: "base64"`
177
178 - `data: string`
179
180 Base64-encoded image data.
181
182 minLength: 1
183
184 - `media_type: string`
185
186 MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp").
187
188 minLength: 1
189
190 - `BetaManagedAgentsURLImageSource object`
191
192 Image referenced by URL.
193
194 - `type: "url"`
195
196 - `url: string`
197
198 URL of the image to fetch.
199
200 minLength: 1
201
202 - `BetaManagedAgentsFileImageSource object`
203
204 Image referenced by file ID.
205
206 - `type: "file"`
207
208 - `file_id: string`
209
210 ID of a previously uploaded file.
211
212 minLength: 1
213
214 - `BetaManagedAgentsDocumentBlock object`
215
216 Document content, either specified directly as base64 data, as text, or as a reference via a URL.
217
218 - `type: "document"`
219
220 - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource`
221
222 Union type for document source variants.
223
224 - `BetaManagedAgentsBase64DocumentSource object`
225
226 Base64-encoded document data.
227
228 - `type: "base64"`
229
230 - `data: string`
231
232 Base64-encoded document data.
233
234 minLength: 1
235
236 - `media_type: string`
237
238 MIME type of the document (e.g., "application/pdf").
239
240 minLength: 1
241
242 - `BetaManagedAgentsPlainTextDocumentSource object`
243
244 Plain text document content.
245
246 - `type: "text"`
247
248 - `data: string`
249
250 The plain text content.
251
252 minLength: 1
253
254 - `media_type: "text/plain"`
255
256 MIME type of the text content. Must be "text/plain".
257
258 - `BetaManagedAgentsURLDocumentSource object`
259
260 Document referenced by URL.
261
262 - `type: "url"`
263
264 - `url: string`
265
266 URL of the document to fetch.
267
268 minLength: 1
269
270 - `BetaManagedAgentsFileDocumentSource object`
271
272 Document referenced by file ID.
273
274 - `type: "file"`
275
276 - `file_id: string`
277
278 ID of a previously uploaded file.
279
280 minLength: 1
281
282 - `context: optional string or null`
283
284 Additional context about the document for the model.
285
286 - `title: optional string or null`
287
288 The title of the document.
289
290 - `BetaManagedAgentsRedactedBlock object`
291
292 Placeholder for content withheld by Anthropic model policy.
293
294 - `type: "redacted"`
295
296 - `processed_at: optional string or null`
297
298 A timestamp in RFC 3339 format
299
300 format: date-time
301
302 - `BetaManagedAgentsUserInterruptEvent object`
303
304 An interrupt event that pauses agent execution and returns control to the user.
305
306 - `type: "user.interrupt"`
307
308 - `id: string`
309
310 Unique identifier for this event.
311
312 - `processed_at: optional string or null`
313
314 A timestamp in RFC 3339 format
315
316 format: date-time
317
318 - `session_thread_id: optional string or null`
319
320 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.
321
322 - `BetaManagedAgentsUserToolConfirmationEvent object`
323
324 A tool confirmation event that approves or denies a pending tool execution.
325
326 - `type: "user.tool_confirmation"`
327
328 - `id: string`
329
330 Unique identifier for this event.
331
332 - `result: "allow" or "deny"`
333
334 UserToolConfirmationResult enum
335
336 - `"allow"`
337
338 - `"deny"`
339
340 - `tool_use_id: string`
341
342 The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field.
343
344 - `deny_message: optional string or null`
345
346 Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'.
347
348 maxLength: 10000
349
350 - `processed_at: optional string or null`
351
352 A timestamp in RFC 3339 format
353
354 format: date-time
355
356 - `session_thread_id: optional string or null`
357
358 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.
359
360 - `BetaManagedAgentsUserCustomToolResultEvent object`
361
362 Event sent by the client providing the result of a custom tool execution.
363
364 - `type: "user.custom_tool_result"`
365
366 - `id: string`
367
368 Unique identifier for this event.
369
370 - `custom_tool_use_id: string`
371
372 The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field.
373
374 - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock`
375
376 The result content returned by the tool.
377
378 - `BetaManagedAgentsTextBlock object`
379
380 Regular text content.
381
382 - `BetaManagedAgentsImageBlock object`
383
384 Image content specified directly as base64 data or as a reference via a URL.
385
386 - `BetaManagedAgentsDocumentBlock object`
387
388 Document content, either specified directly as base64 data, as text, or as a reference via a URL.
389
390 - `BetaManagedAgentsSearchResultBlock object`
391
392 A block containing a web search result.
393
394 - `type: "search_result"`
395
396 - `citations: BetaManagedAgentsSearchResultCitations`
397
398 Citation settings for a search result.
399
400 - `enabled: boolean`
401
402 Whether citations are enabled for this search result.
403
404 - `content: array of BetaManagedAgentsSearchResultContent`
405
406 Array of text content blocks from the search result.
407
408 - `type: "text"`
409
410 - `text: string`
411
412 The text content.
413
414 minLength: 1
415
416 - `source: string`
417
418 The URL source of the search result.
419
420 minLength: 1
421
422 - `title: string`
423
424 The title of the search result.
425
426 minLength: 1
427
428 - `is_error: optional boolean or null`
429
430 Whether the tool execution resulted in an error.
431
432 - `processed_at: optional string or null`
433
434 A timestamp in RFC 3339 format
435
436 format: date-time
437
438 - `session_thread_id: optional string or null`
439
440 Routes this result to a subagent thread. Copy from the `agent.custom_tool_use` event's `session_thread_id`.
441
442 - `BetaManagedAgentsAgentCustomToolUseEvent object`
443
444 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.
445
446 - `type: "agent.custom_tool_use"`
447
448 - `id: string`
449
450 Unique identifier for this event.
451
452 - `input: map[unknown]`
453
454 Input parameters for the tool call.
455
456 - `name: string`
457
458 Name of the custom tool being called.
459
460 - `processed_at: string`
461
462 A timestamp in RFC 3339 format
463
464 format: date-time
465
466 - `session_thread_id: optional string or null`
467
468 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.
469
470 - `BetaManagedAgentsAgentMessageEvent object`
471
472 An agent response event in the session conversation.
473
474 - `type: "agent.message"`
475
476 - `id: string`
477
478 Unique identifier for this event.
479
480 - `content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsRedactedBlock`
481
482 Array of text blocks comprising the agent response.
483
484 - `BetaManagedAgentsTextBlock object`
485
486 Regular text content.
487
488 - `BetaManagedAgentsRedactedBlock object`
489
490 Placeholder for content withheld by Anthropic model policy.
491
492 - `processed_at: string`
493
494 A timestamp in RFC 3339 format
495
496 format: date-time
497
498 - `BetaManagedAgentsAgentThinkingEvent object`
499
500 Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier.
501
502 - `type: "agent.thinking"`
503
504 - `id: string`
505
506 Unique identifier for this event.
507
508 - `processed_at: string`
509
510 A timestamp in RFC 3339 format
511
512 format: date-time
513
514 - `BetaManagedAgentsAgentMCPToolUseEvent object`
515
516 Event emitted when the agent invokes a tool provided by an MCP server.
517
518 - `type: "agent.mcp_tool_use"`
519
520 - `id: string`
521
522 Unique identifier for this event.
523
524 - `input: map[unknown]`
525
526 Input parameters for the tool call.
527
528 - `mcp_server_name: string`
529
530 Name of the MCP server providing the tool.
531
532 - `name: string`
533
534 Name of the MCP tool being used.
535
536 - `processed_at: string`
537
538 A timestamp in RFC 3339 format
539
540 format: date-time
541
542 - `evaluated_permission: optional "allow" or "ask" or "deny"`
543
544 AgentEvaluatedPermission enum
545
546 - `"allow"`
547
548 - `"ask"`
549
550 - `"deny"`
551
552 - `evaluation: optional BetaManagedAgentsAgentToolEvaluation`
553
554 Names the resolved permission_policy that produced evaluated_permission, and under auto carries the judgement. Open union: clients must tolerate unknown variants.
555
556 - `BetaManagedAgentsAgentToolEvaluationAlwaysAllow object`
557
558 The resolved permission_policy was always_allow; accompanies evaluated_permission "allow".
559
560 - `type: "always_allow"`
561
562 - `BetaManagedAgentsAgentToolEvaluationAlwaysAsk object`
563
564 The resolved permission_policy was always_ask; accompanies evaluated_permission "ask".
565
566 - `type: "always_ask"`
567
568 - `BetaManagedAgentsAgentToolEvaluationAuto object`
569
570 The resolved permission_policy was auto: the server judged this invocation individually.
571
572 - `type: "auto"`
573
574 - `evaluated_permission: BetaManagedAgentsAgentAutoEvaluatedPermission`
575
576 The server's per-invocation judgement under the auto permission policy. Its type always equals the event's top-level evaluated_permission. Open union: clients must tolerate unknown variants.
577
578 - `BetaManagedAgentsAgentAutoEvaluatedPermissionAllow object`
579
580 The server judged the invocation safe to execute without client approval.
581
582 - `type: "allow"`
583
584 - `BetaManagedAgentsAgentAutoEvaluatedPermissionAsk object`
585
586 The server reached no judgement; the invocation is held for client approval.
587
588 - `type: "ask"`
589
590 - `reason_code: string`
591
592 The judgement's grounds in registry-bound terms, for client branching and audit rather than end-user display. Open registry; currently "indeterminate" (no judgement was reached). Clients must tolerate values outside this set.
593
594 maxLength: 64
595
596 - `BetaManagedAgentsAgentAutoEvaluatedPermissionDeny object`
597
598 The server judged the invocation high-risk; it does not execute and a synthetic error tool result is appended.
599
600 - `type: "deny"`
601
602 - `reason_code: string`
603
604 The judgement's grounds in registry-bound terms. Open registry; currently "high_risk" (judged high-risk; the call does not run). Clients must tolerate values outside this set.
605
606 maxLength: 64
607
608 - `session_thread_id: optional string or null`
609
610 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.
611
612 - `BetaManagedAgentsAgentMCPToolResultEvent object`
613
614 Event representing the result of an MCP tool execution.
615
616 - `type: "agent.mcp_tool_result"`
617
618 - `id: string`
619
620 Unique identifier for this event.
621
622 - `mcp_tool_use_id: string`
623
624 The id of the `agent.mcp_tool_use` event this result corresponds to.
625
626 - `processed_at: string`
627
628 A timestamp in RFC 3339 format
629
630 format: date-time
631
632 - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock`
633
634 The result content returned by the tool.
635
636 - `BetaManagedAgentsTextBlock object`
637
638 Regular text content.
639
640 - `BetaManagedAgentsImageBlock object`
641
642 Image content specified directly as base64 data or as a reference via a URL.
643
644 - `BetaManagedAgentsDocumentBlock object`
645
646 Document content, either specified directly as base64 data, as text, or as a reference via a URL.
647
648 - `BetaManagedAgentsSearchResultBlock object`
649
650 A block containing a web search result.
651
652 - `is_error: optional boolean or null`
653
654 Whether the tool execution resulted in an error.
655
656 - `BetaManagedAgentsAgentToolUseEvent object`
657
658 Event emitted when the agent invokes a built-in agent tool.
659
660 - `type: "agent.tool_use"`
661
662 - `id: string`
663
664 Unique identifier for this event.
665
666 - `input: map[unknown]`
667
668 Input parameters for the tool call.
669
670 - `name: string`
671
672 Name of the agent tool being used.
673
674 - `processed_at: string`
675
676 A timestamp in RFC 3339 format
677
678 format: date-time
679
680 - `evaluated_permission: optional "allow" or "ask" or "deny"`
681
682 AgentEvaluatedPermission enum
683
684 - `"allow"`
685
686 - `"ask"`
687
688 - `"deny"`
689
690 - `evaluation: optional BetaManagedAgentsAgentToolEvaluation`
691
692 Names the resolved permission_policy that produced evaluated_permission, and under auto carries the judgement. Open union: clients must tolerate unknown variants.
693
694 - `session_thread_id: optional string or null`
695
696 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.
697
698 - `BetaManagedAgentsAgentToolResultEvent object`
699
700 Event representing the result of an agent tool execution.
701
702 - `type: "agent.tool_result"`
703
704 - `id: string`
705
706 Unique identifier for this event.
707
708 - `processed_at: string`
709
710 A timestamp in RFC 3339 format
711
712 format: date-time
713
714 - `tool_use_id: string`
715
716 The id of the `agent.tool_use` event this result corresponds to.
717
718 - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock`
719
720 The result content returned by the tool.
721
722 - `BetaManagedAgentsTextBlock object`
723
724 Regular text content.
725
726 - `BetaManagedAgentsImageBlock object`
727
728 Image content specified directly as base64 data or as a reference via a URL.
729
730 - `BetaManagedAgentsDocumentBlock object`
731
732 Document content, either specified directly as base64 data, as text, or as a reference via a URL.
733
734 - `BetaManagedAgentsSearchResultBlock object`
735
736 A block containing a web search result.
737
738 - `is_error: optional boolean or null`
739
740 Whether the tool execution resulted in an error.
741
742 - `BetaManagedAgentsAgentThreadMessageReceivedEvent object`
743
744 Delivery event written to the target thread's input stream when an agent-to-agent message arrives.
745
746 - `type: "agent.thread_message_received"`
747
748 - `id: string`
749
750 Unique identifier for this event.
751
752 - `content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsRedactedBlock`
753
754 Message content blocks.
755
756 - `BetaManagedAgentsTextBlock object`
757
758 Regular text content.
759
760 - `BetaManagedAgentsImageBlock object`
761
762 Image content specified directly as base64 data or as a reference via a URL.
763
764 - `BetaManagedAgentsDocumentBlock object`
765
766 Document content, either specified directly as base64 data, as text, or as a reference via a URL.
767
768 - `BetaManagedAgentsRedactedBlock object`
769
770 Placeholder for content withheld by Anthropic model policy.
771
772 - `from_session_thread_id: string`
773
774 Public `sthr_` ID of the thread that sent the message.
775
776 - `processed_at: string`
777
778 A timestamp in RFC 3339 format
779
780 format: date-time
781
782 - `from_agent_name: optional string or null`
783
784 Name of the callable agent this message came from. Absent when received from the primary agent.
785
786 - `BetaManagedAgentsAgentThreadMessageSentEvent object`
787
788 Observability event emitted to the sender's output stream when an agent-to-agent message is sent.
789
790 - `type: "agent.thread_message_sent"`
791
792 - `id: string`
793
794 Unique identifier for this event.
795
796 - `content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsRedactedBlock`
797
798 Message content blocks.
799
800 - `BetaManagedAgentsTextBlock object`
801
802 Regular text content.
803
804 - `BetaManagedAgentsImageBlock object`
805
806 Image content specified directly as base64 data or as a reference via a URL.
807
808 - `BetaManagedAgentsDocumentBlock object`
809
810 Document content, either specified directly as base64 data, as text, or as a reference via a URL.
811
812 - `BetaManagedAgentsRedactedBlock object`
813
814 Placeholder for content withheld by Anthropic model policy.
815
816 - `processed_at: string`
817
818 A timestamp in RFC 3339 format
819
820 format: date-time
821
822 - `to_session_thread_id: string`
823
824 Public `sthr_` ID of the thread the message was sent to.
825
826 - `to_agent_name: optional string or null`
827
828 Name of the callable agent this message was sent to. Absent when sent to the primary agent.
829
830 - `BetaManagedAgentsAgentThreadContextCompactedEvent object`
831
832 Indicates that context compaction (summarization) occurred during the session.
833
834 - `type: "agent.thread_context_compacted"`
835
836 - `id: string`
837
838 Unique identifier for this event.
839
840 - `processed_at: string`
841
842 A timestamp in RFC 3339 format
843
844 format: date-time
845
846 - `BetaManagedAgentsSessionErrorEvent object`
847
848 An error event indicating a problem occurred during session execution.
849
850 - `type: "session.error"`
851
852 - `id: string`
853
854 Unique identifier for this event.
855
856 - `error: BetaManagedAgentsUnknownError or BetaManagedAgentsModelOverloadedError or BetaManagedAgentsModelRateLimitedError or 5 more`
857
858 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.
859
860 - `BetaManagedAgentsUnknownError object`
861
862 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.
863
864 - `type: "unknown_error"`
865
866 - `message: string`
867
868 Human-readable error description.
869
870 - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal`
871
872 What the client should do next in response to this error.
873
874 - `BetaManagedAgentsRetryStatusRetrying object`
875
876 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.
877
878 - `type: "retrying"`
879
880 - `BetaManagedAgentsRetryStatusExhausted object`
881
882 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
883
884 - `type: "exhausted"`
885
886 - `BetaManagedAgentsRetryStatusTerminal object`
887
888 The session encountered a terminal error and will transition to `terminated` state.
889
890 - `type: "terminal"`
891
892 - `BetaManagedAgentsModelOverloadedError object`
893
894 The model is currently overloaded. Emitted after automatic retries are exhausted.
895
896 - `type: "model_overloaded_error"`
897
898 - `message: string`
899
900 Human-readable error description.
901
902 - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal`
903
904 What the client should do next in response to this error.
905
906 - `BetaManagedAgentsRetryStatusRetrying object`
907
908 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.
909
910 - `BetaManagedAgentsRetryStatusExhausted object`
911
912 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
913
914 - `BetaManagedAgentsRetryStatusTerminal object`
915
916 The session encountered a terminal error and will transition to `terminated` state.
917
918 - `BetaManagedAgentsModelRateLimitedError object`
919
920 The model request was rate-limited.
921
922 - `type: "model_rate_limited_error"`
923
924 - `message: string`
925
926 Human-readable error description.
927
928 - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal`
929
930 What the client should do next in response to this error.
931
932 - `BetaManagedAgentsRetryStatusRetrying object`
933
934 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.
935
936 - `BetaManagedAgentsRetryStatusExhausted object`
937
938 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
939
940 - `BetaManagedAgentsRetryStatusTerminal object`
941
942 The session encountered a terminal error and will transition to `terminated` state.
943
944 - `BetaManagedAgentsModelRequestFailedError object`
945
946 A model request failed for a reason other than overload or rate-limiting.
947
948 - `type: "model_request_failed_error"`
949
950 - `message: string`
951
952 Human-readable error description.
953
954 - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal`
955
956 What the client should do next in response to this error.
957
958 - `BetaManagedAgentsRetryStatusRetrying object`
959
960 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.
961
962 - `BetaManagedAgentsRetryStatusExhausted object`
963
964 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
965
966 - `BetaManagedAgentsRetryStatusTerminal object`
967
968 The session encountered a terminal error and will transition to `terminated` state.
969
970 - `BetaManagedAgentsMCPConnectionFailedError object`
971
972 Failed to connect to an MCP server.
973
974 - `type: "mcp_connection_failed_error"`
975
976 - `mcp_server_name: string`
977
978 Name of the MCP server that failed to connect.
979
980 - `message: string`
981
982 Human-readable error description.
983
984 - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal`
985
986 What the client should do next in response to this error.
987
988 - `BetaManagedAgentsRetryStatusRetrying object`
989
990 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.
991
992 - `BetaManagedAgentsRetryStatusExhausted object`
993
994 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
995
996 - `BetaManagedAgentsRetryStatusTerminal object`
997
998 The session encountered a terminal error and will transition to `terminated` state.
999
1000 - `BetaManagedAgentsMCPAuthenticationFailedError object`
1001
1002 Authentication to an MCP server failed.
1003
1004 - `type: "mcp_authentication_failed_error"`
1005
1006 - `mcp_server_name: string`
1007
1008 Name of the MCP server that failed authentication.
1009
1010 - `message: string`
1011
1012 Human-readable error description.
1013
1014 - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal`
1015
1016 What the client should do next in response to this error.
1017
1018 - `BetaManagedAgentsRetryStatusRetrying object`
1019
1020 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.
1021
1022 - `BetaManagedAgentsRetryStatusExhausted object`
1023
1024 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
1025
1026 - `BetaManagedAgentsRetryStatusTerminal object`
1027
1028 The session encountered a terminal error and will transition to `terminated` state.
1029
1030 - `BetaManagedAgentsBillingError object`
1031
1032 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.
1033
1034 - `type: "billing_error"`
1035
1036 - `message: string`
1037
1038 Human-readable error description.
1039
1040 - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal`
1041
1042 What the client should do next in response to this error.
1043
1044 - `BetaManagedAgentsRetryStatusRetrying object`
1045
1046 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.
1047
1048 - `BetaManagedAgentsRetryStatusExhausted object`
1049
1050 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
1051
1052 - `BetaManagedAgentsRetryStatusTerminal object`
1053
1054 The session encountered a terminal error and will transition to `terminated` state.
1055
1056 - `BetaManagedAgentsCredentialHostUnreachableError object`
1057
1058 An `environment_variable` credential's `auth.networking.allowed_hosts` includes a host the environment's network policy does not permit.
1059
1060 - `type: "credential_host_unreachable_error"`
1061
1062 - `credential_id: string`
1063
1064 ID of the affected credential.
1065
1066 - `message: string`
1067
1068 Human-readable error description.
1069
1070 - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal`
1071
1072 What the client should do next in response to this error.
1073
1074 - `BetaManagedAgentsRetryStatusRetrying object`
1075
1076 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.
1077
1078 - `BetaManagedAgentsRetryStatusExhausted object`
1079
1080 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
1081
1082 - `BetaManagedAgentsRetryStatusTerminal object`
1083
1084 The session encountered a terminal error and will transition to `terminated` state.
1085
1086 - `vault_id: string`
1087
1088 ID of the vault containing the affected credential.
1089
1090 - `processed_at: string`
1091
1092 A timestamp in RFC 3339 format
1093
1094 format: date-time
1095
1096 - `BetaManagedAgentsSessionStatusRescheduledEvent object`
1097
1098 Indicates the session is recovering from an error state and is rescheduled for execution.
1099
1100 - `type: "session.status_rescheduled"`
1101
1102 - `id: string`
1103
1104 Unique identifier for this event.
1105
1106 - `processed_at: string`
1107
1108 A timestamp in RFC 3339 format
1109
1110 format: date-time
1111
1112 - `BetaManagedAgentsSessionStatusRunningEvent object`
1113
1114 Indicates the session is actively running and the agent is working.
1115
1116 - `type: "session.status_running"`
1117
1118 - `id: string`
1119
1120 Unique identifier for this event.
1121
1122 - `processed_at: string`
1123
1124 A timestamp in RFC 3339 format
1125
1126 format: date-time
1127
1128 - `BetaManagedAgentsSessionStatusIdleEvent object`
1129
1130 Indicates the agent has paused and is awaiting user input.
1131
1132 - `type: "session.status_idle"`
1133
1134 - `id: string`
1135
1136 Unique identifier for this event.
1137
1138 - `processed_at: string`
1139
1140 A timestamp in RFC 3339 format
1141
1142 format: date-time
1143
1144 - `stop_reason: BetaManagedAgentsSessionEndTurn or BetaManagedAgentsSessionRequiresAction or BetaManagedAgentsSessionRetriesExhausted or BetaManagedAgentsSessionBudgetReached`
1145
1146 The agent completed its turn naturally and is ready for the next user message.
1147
1148 - `BetaManagedAgentsSessionEndTurn object`
1149
1150 The agent completed its turn naturally and is ready for the next user message.
1151
1152 - `type: "end_turn"`
1153
1154 - `BetaManagedAgentsSessionRequiresAction object`
1155
1156 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.
1157
1158 - `type: "requires_action"`
1159
1160 - `event_ids: array of string`
1161
1162 The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder.
1163
1164 - `BetaManagedAgentsSessionRetriesExhausted object`
1165
1166 The turn ended because repeated errors exhausted the retry budget or an error escalated to `retry_status: 'exhausted'`.
1167
1168 - `type: "retries_exhausted"`
1169
1170 - `BetaManagedAgentsSessionBudgetReached object`
1171
1172 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.
1173
1174 - `type: "budget_reached"`
1175
1176 - `BetaManagedAgentsSessionStatusTerminatedEvent object`
1177
1178 Indicates the session has terminated, either due to an error or completion.
1179
1180 - `type: "session.status_terminated"`
1181
1182 - `id: string`
1183
1184 Unique identifier for this event.
1185
1186 - `processed_at: string`
1187
1188 A timestamp in RFC 3339 format
1189
1190 format: date-time
1191
1192 - `BetaManagedAgentsSessionThreadCreatedEvent object`
1193
1194 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.
1195
1196 - `type: "session.thread_created"`
1197
1198 - `id: string`
1199
1200 Unique identifier for this event.
1201
1202 - `agent_name: string`
1203
1204 Name of the callable agent the thread runs.
1205
1206 - `processed_at: string`
1207
1208 A timestamp in RFC 3339 format
1209
1210 format: date-time
1211
1212 - `session_thread_id: string`
1213
1214 Public `sthr_` ID of the newly created thread.
1215
1216 - `BetaManagedAgentsSpanOutcomeEvaluationStartEvent object`
1217
1218 Emitted when an outcome evaluation cycle begins.
1219
1220 - `type: "span.outcome_evaluation_start"`
1221
1222 - `id: string`
1223
1224 Unique identifier for this event.
1225
1226 - `iteration: number`
1227
1228 0-indexed revision cycle. 0 is the first evaluation; 1 is the re-evaluation after the first revision; etc.
1229
1230 format: int32
1231
1232 - `outcome_id: string`
1233
1234 The `outc_` ID of the outcome being evaluated.
1235
1236 - `processed_at: string`
1237
1238 A timestamp in RFC 3339 format
1239
1240 format: date-time
1241
1242 - `BetaManagedAgentsSpanOutcomeEvaluationEndEvent object`
1243
1244 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.
1245
1246 - `type: "span.outcome_evaluation_end"`
1247
1248 - `id: string`
1249
1250 Unique identifier for this event.
1251
1252 - `explanation: string`
1253
1254 Human-readable explanation of the verdict. For `needs_revision`, describes which criteria failed and why.
1255
1256 - `iteration: number`
1257
1258 0-indexed revision cycle, matching the corresponding `span.outcome_evaluation_start`.
1259
1260 format: int32
1261
1262 - `outcome_evaluation_start_id: string`
1263
1264 The id of the corresponding `span.outcome_evaluation_start` event.
1265
1266 - `outcome_id: string`
1267
1268 The `outc_` ID of the outcome being evaluated.
1269
1270 - `processed_at: string`
1271
1272 A timestamp in RFC 3339 format
1273
1274 format: date-time
1275
1276 - `result: string`
1277
1278 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.
1279
1280 - `usage: BetaManagedAgentsSpanModelUsage`
1281
1282 Token usage for a single model request.
1283
1284 - `cache_creation_input_tokens: number`
1285
1286 Tokens used to create prompt cache in this request.
1287
1288 format: int32
1289
1290 - `cache_read_input_tokens: number`
1291
1292 Tokens read from prompt cache in this request.
1293
1294 format: int32
1295
1296 - `input_tokens: number`
1297
1298 Input tokens consumed by this request.
1299
1300 format: int32
1301
1302 - `output_tokens: number`
1303
1304 Output tokens generated by this request.
1305
1306 format: int32
1307
1308 - `speed: optional "standard" or "fast" or null`
1309
1310 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.
1311
1312 - `"standard"`
1313
1314 - `"fast"`
1315
1316 - `BetaManagedAgentsSpanModelRequestStartEvent object`
1317
1318 Emitted when a model request is initiated by the agent.
1319
1320 - `type: "span.model_request_start"`
1321
1322 - `id: string`
1323
1324 Unique identifier for this event.
1325
1326 - `processed_at: string`
1327
1328 A timestamp in RFC 3339 format
1329
1330 format: date-time
1331
1332 - `BetaManagedAgentsSpanModelRequestEndEvent object`
1333
1334 Emitted when a model request completes.
1335
1336 - `type: "span.model_request_end"`
1337
1338 - `id: string`
1339
1340 Unique identifier for this event.
1341
1342 - `is_error: boolean or null`
1343
1344 Whether the model request resulted in an error.
1345
1346 - `model_request_start_id: string`
1347
1348 The id of the corresponding `span.model_request_start` event.
1349
1350 - `model_usage: BetaManagedAgentsSpanModelUsage`
1351
1352 Token usage for a single model request.
1353
1354 - `processed_at: string`
1355
1356 A timestamp in RFC 3339 format
1357
1358 format: date-time
1359
1360 - `BetaManagedAgentsSpanOutcomeEvaluationOngoingEvent object`
1361
1362 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.
1363
1364 - `type: "span.outcome_evaluation_ongoing"`
1365
1366 - `id: string`
1367
1368 Unique identifier for this event.
1369
1370 - `iteration: number`
1371
1372 0-indexed revision cycle, matching the corresponding `span.outcome_evaluation_start`.
1373
1374 format: int32
1375
1376 - `outcome_id: string`
1377
1378 The `outc_` ID of the outcome being evaluated.
1379
1380 - `processed_at: string`
1381
1382 A timestamp in RFC 3339 format
1383
1384 format: date-time
1385
1386 - `BetaManagedAgentsUserDefineOutcomeEvent object`
1387
1388 Echo of a `user.define_outcome` input event. Carries the server-generated `outcome_id` that subsequent `span.outcome_evaluation_*` events reference.
1389
1390 - `type: "user.define_outcome"`
1391
1392 - `id: string`
1393
1394 Unique identifier for this event.
1395
1396 - `description: string`
1397
1398 What the agent should produce. Copied from the input event.
1399
1400 - `max_iterations: number or null`
1401
1402 Evaluate-then-revise cycles before giving up. Default 3, max 20.
1403
1404 format: int32
1405
1406 - `outcome_id: string`
1407
1408 Server-generated `outc_` ID for this outcome. Referenced by `span.outcome_evaluation_*` events and the session's `outcome_evaluations` list.
1409
1410 - `processed_at: string`
1411
1412 A timestamp in RFC 3339 format
1413
1414 format: date-time
1415
1416 - `rubric: BetaManagedAgentsFileRubric or BetaManagedAgentsTextRubric`
1417
1418 Rubric for grading the quality of an outcome.
1419
1420 - `BetaManagedAgentsFileRubric object`
1421
1422 Rubric referenced by a file uploaded via the Files API.
1423
1424 - `type: "file"`
1425
1426 - `file_id: string`
1427
1428 ID of the rubric file.
1429
1430 - `BetaManagedAgentsTextRubric object`
1431
1432 Rubric content provided inline as text.
1433
1491434 - `type: "text"`
1501435
1436 - `content: string`
1437
1438 Rubric content. Plain text or markdown — the grader treats it as freeform text.
1439
1440 - `BetaManagedAgentsSessionDeletedEvent object`
1441
1442 Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session.
1443
1444 - `type: "session.deleted"`
1445
1446 - `id: string`
1447
1448 Unique identifier for this event.
1449
1450 - `processed_at: string`
1451
1452 A timestamp in RFC 3339 format
1453
1454 format: date-time
1455
1456 - `BetaManagedAgentsSessionThreadStatusRunningEvent object`
1457
1458 A session thread has begun executing. Emitted on the thread's own stream and cross-posted to the primary stream for child threads.
1459
1460 - `type: "session.thread_status_running"`
1461
1462 - `id: string`
1463
1464 Unique identifier for this event.
1465
1466 - `agent_name: string`
1467
1468 Name of the agent the thread runs.
1469
1470 - `processed_at: string`
1471
1472 A timestamp in RFC 3339 format
1473
1474 format: date-time
1475
1476 - `session_thread_id: string`
1477
1478 Public sthr_ ID of the thread that started running.
1479
1480 - `BetaManagedAgentsSessionThreadStatusIdleEvent object`
1481
1482 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.
1483
1484 - `type: "session.thread_status_idle"`
1485
1486 - `id: string`
1487
1488 Unique identifier for this event.
1489
1490 - `agent_name: string`
1491
1492 Name of the agent the thread runs.
1493
1494 - `processed_at: string`
1495
1496 A timestamp in RFC 3339 format
1497
1498 format: date-time
1499
1500 - `session_thread_id: string`
1501
1502 Public sthr_ ID of the thread that went idle.
1503
1504 - `stop_reason: BetaManagedAgentsSessionEndTurn or BetaManagedAgentsSessionRequiresAction or BetaManagedAgentsSessionRetriesExhausted or BetaManagedAgentsSessionBudgetReached`
1505
1506 The agent completed its turn naturally and is ready for the next user message.
1507
1508 - `BetaManagedAgentsSessionEndTurn object`
1509
1510 The agent completed its turn naturally and is ready for the next user message.
1511
1512 - `BetaManagedAgentsSessionRequiresAction object`
1513
1514 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.
1515
1516 - `BetaManagedAgentsSessionRetriesExhausted object`
1517
1518 The turn ended because repeated errors exhausted the retry budget or an error escalated to `retry_status: 'exhausted'`.
1519
1520 - `BetaManagedAgentsSessionBudgetReached object`
1521
1522 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.
1523
1524 - `BetaManagedAgentsSessionThreadStatusTerminatedEvent object`
1525
1526 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.
1527
1528 - `type: "session.thread_status_terminated"`
1529
1530 - `id: string`
1531
1532 Unique identifier for this event.
1533
1534 - `agent_name: string`
1535
1536 Name of the agent the thread runs.
1537
1538 - `processed_at: string`
1539
1540 A timestamp in RFC 3339 format
1541
1542 format: date-time
1543
1544 - `session_thread_id: string`
1545
1546 Public sthr_ ID of the thread that terminated.
1547
1548 - `BetaManagedAgentsUserToolResultEvent object`
1549
1550 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.
1551
1552 - `type: "user.tool_result"`
1553
1554 - `id: string`
1555
1556 Unique identifier for this event.
1557
1558 - `tool_use_id: string`
1559
1560 The id of the `agent.tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field.
1561
1562 - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock`
1563
1564 The result content returned by the tool.
1565
1566 - `BetaManagedAgentsTextBlock object`
1567
1568 Regular text content.
1569
1511570 - `BetaManagedAgentsImageBlock object`
1521571
1531572 Image content specified directly as base64 data or as a reference via a URL.
1541573
155 - `source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSource`
156
157 Union type for image source variants.
158
159 - `BetaManagedAgentsBase64ImageSource object`
160
161 Base64-encoded image data.
162
163 - `data: string`
164
165 Base64-encoded image data.
166
167 minLength: 1
168
169 - `media_type: string`
170
171 MIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp").
172
173 minLength: 1
174
175 - `type: "base64"`
176
177 - `BetaManagedAgentsURLImageSource object`
178
179 Image referenced by URL.
180
181 - `type: "url"`
182
183 - `url: string`
184
185 URL of the image to fetch.
186
187 minLength: 1
188
189 - `BetaManagedAgentsFileImageSource object`
190
191 Image referenced by file ID.
192
193 - `file_id: string`
194
195 ID of a previously uploaded file.
196
197 minLength: 1
198
199 - `type: "file"`
200
201 - `type: "image"`
202
2031574 - `BetaManagedAgentsDocumentBlock object`
2041575
2051576 Document content, either specified directly as base64 data, as text, or as a reference via a URL.
2061577
207 - `source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSource`
208
209 Union type for document source variants.
210
211 - `BetaManagedAgentsBase64DocumentSource object`
212
213 Base64-encoded document data.
214
215 - `data: string`
216
217 Base64-encoded document data.
218
219 minLength: 1
220
221 - `media_type: string`
222
223 MIME type of the document (e.g., "application/pdf").
224
225 minLength: 1
226
227 - `type: "base64"`
228
229 - `BetaManagedAgentsPlainTextDocumentSource object`
230
231 Plain text document content.
232
233 - `data: string`
234
235 The plain text content.
236
237 minLength: 1
238
239 - `media_type: "text/plain"`
240
241 MIME type of the text content. Must be "text/plain".
242
243 - `type: "text"`
244
245 - `BetaManagedAgentsURLDocumentSource object`
246
247 Document referenced by URL.
248
249 - `type: "url"`
250
251 - `url: string`
252
253 URL of the document to fetch.
254
255 minLength: 1
256
257 - `BetaManagedAgentsFileDocumentSource object`
258
259 Document referenced by file ID.
260
261 - `file_id: string`
262
263 ID of a previously uploaded file.
264
265 minLength: 1
266
267 - `type: "file"`
268
269 - `type: "document"`
270
271 - `context: optional string or null`
272
273 Additional context about the document for the model.
274
275 - `title: optional string or null`
276
277 The title of the document.
278
279 - `BetaManagedAgentsRedactedBlock object`
280
281 Placeholder for content withheld by Anthropic model policy.
282
283 - `type: "redacted"`
284
285 - `type: "user.message"`
1578 - `BetaManagedAgentsSearchResultBlock object`
1579
1580 A block containing a web search result.
1581
1582 - `is_error: optional boolean or null`
1583
1584 Whether the tool execution resulted in an error.
2861585
2871586 - `processed_at: optional string or null`
2881587
from line 1589
2901589
2911590 format: date-time
2921591
293 - `BetaManagedAgentsUserInterruptEvent object`
294
295 An interrupt event that pauses agent execution and returns control to the user.
296
297 - `id: string`
298
299 Unique identifier for this event.
300
301 - `type: "user.interrupt"`
1592 - `session_thread_id: optional string or null`
1593
1594 Routes this result to a subagent thread. Copy from the `agent.tool_use` event's `session_thread_id`.
1595
1596 - `BetaManagedAgentsSessionThreadStatusRescheduledEvent object`
1597
1598 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.
1599
1600 - `type: "session.thread_status_rescheduled"`
1601
1602 - `id: string`
1603
1604 Unique identifier for this event.
1605
1606 - `agent_name: string`
1607
1608 Name of the agent the thread runs.
1609
1610 - `processed_at: string`
1611
1612 A timestamp in RFC 3339 format
1613
1614 format: date-time
1615
1616 - `session_thread_id: string`
1617
1618 Public sthr_ ID of the thread that is retrying.
1619
1620 - `BetaManagedAgentsSessionUpdatedEvent object`
1621
1622 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.
1623
1624 - `type: "session.updated"`
1625
1626 - `id: string`
1627
1628 Unique identifier for this event.
1629
1630 - `processed_at: string`
1631
1632 A timestamp in RFC 3339 format
1633
1634 format: date-time
1635
1636 - `agent: optional BetaManagedAgentsSessionAgent or null`
1637
1638 Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time.
1639
1640 - `type: "agent"`
1641
1642 - `id: string`
1643
1644 - `description: string or null`
1645
1646 - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition`
1647
1648 - `type: "url"`
1649
1650 - `name: string`
1651
1652 - `url: string`
1653
1654 - `model: BetaManagedAgentsModelConfig`
1655
1656 Model identifier and configuration.
1657
1658 - `id: BetaManagedAgentsModel`
1659
1660 The model that will power your agent.
1661
1662 See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options.
1663
1664 - `"claude-fable-5-1" or "claude-sonnet-5" or "claude-fable-5" or 11 more`
1665
1666 The model that will power your agent.
1667
1668 See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options.
1669
1670 - `"claude-fable-5-1"`
1671
1672 Frontier intelligence for ambitious tasks across coding, scientific discovery, and enterprise workflows
1673
1674 - `"claude-sonnet-5"`
1675
1676 High-performance model for coding and agents
1677
1678 - `"claude-fable-5"`
1679
1680 Next generation of intelligence for the hardest knowledge work and coding problems
1681
1682 - `"claude-opus-5"`
1683
1684 Powerful intelligence for long-running agents and coding
1685
1686 - `"claude-opus-4-8"`
1687
1688 Powerful intelligence for long-running agents and coding
1689
1690 - `"claude-opus-4-7"`
1691
1692 Powerful intelligence for long-running agents and coding
1693
1694 - `"claude-opus-4-6"`
1695
1696 Powerful intelligence for long-running agents and coding
1697
1698 - `"claude-sonnet-4-6"`
1699
1700 Best combination of speed and intelligence
1701
1702 - `"claude-haiku-4-5"`
1703
1704 Fastest model with near-frontier intelligence
1705
1706 - `"claude-haiku-4-5-20251001"`
1707
1708 Fastest model with near-frontier intelligence
1709
1710 - `"claude-opus-4-5"`
1711
1712 Powerful intelligence for long-running agents and coding
1713
1714 - `"claude-opus-4-5-20251101"`
1715
1716 Powerful intelligence for long-running agents and coding
1717
1718 - `"claude-sonnet-4-5"`
1719
1720 High-performance model for agents and coding
1721
1722 - `"claude-sonnet-4-5-20250929"`
1723
1724 High-performance model for agents and coding
1725
1726 - `string`
1727
1728 - `effort: optional BetaManagedAgentsEffortLow or BetaManagedAgentsEffortMedium or BetaManagedAgentsEffortHigh or 2 more`
1729
1730 How hard Claude works on each turn. Sets `output_config.effort` on every Messages call the session makes.
1731
1732 - `BetaManagedAgentsEffortLow object`
1733
1734 Low effort. Favors latency over reasoning depth.
1735
1736 - `type: "low"`
1737
1738 - `BetaManagedAgentsEffortMedium object`
1739
1740 Medium effort. Balances latency and reasoning depth.
1741
1742 - `type: "medium"`
1743
1744 - `BetaManagedAgentsEffortHigh object`
1745
1746 High effort. Favors reasoning depth.
1747
1748 - `type: "high"`
1749
1750 - `BetaManagedAgentsEffortXhigh object`
1751
1752 Extra-high effort. Not all models accept this level.
1753
1754 - `type: "xhigh"`
1755
1756 - `BetaManagedAgentsEffortMax object`
1757
1758 Maximum effort. Favors reasoning depth over latency.
1759
1760 - `type: "max"`
1761
1762 - `inference_geo: optional string`
1763
1764 Geographic region for model inference. When unset, requests fall through to the workspace's default_inference_geo.
1765
1766 - `speed: optional "standard" or "fast"`
1767
1768 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.
1769
1770 - `"standard"`
1771
1772 - `"fast"`
1773
1774 - `multiagent: BetaManagedAgentsSessionMultiagentCoordinator or null`
1775
1776 Resolved coordinator topology with full agent definitions for each roster member.
1777
1778 - `type: "coordinator"`
1779
1780 - `agents: array of BetaManagedAgentsSessionThreadAgent or BetaManagedAgentsAdvisor`
1781
1782 Full `agent` definitions the coordinator may spawn as session threads.
1783
1784 - `BetaManagedAgentsSessionThreadAgent object`
1785
1786 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`.
1787
1788 - `type: "agent"`
1789
1790 - `id: string`
1791
1792 - `description: string or null`
1793
1794 - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition`
1795
1796 - `type: "url"`
1797
1798 - `name: string`
1799
1800 - `url: string`
1801
1802 - `model: BetaManagedAgentsModelConfig`
1803
1804 Model identifier and configuration.
1805
1806 - `name: string`
1807
1808 - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill`
1809
1810 - `BetaManagedAgentsAnthropicSkill object`
1811
1812 A resolved Anthropic-managed skill.
1813
1814 - `type: "anthropic"`
1815
1816 - `skill_id: string`
1817
1818 - `version: string`
1819
1820 - `BetaManagedAgentsCustomSkill object`
1821
1822 A resolved user-created custom skill.
1823
1824 - `type: "custom"`
1825
1826 - `skill_id: string`
1827
1828 - `version: string`
1829
1830 - `system: string or null`
1831
1832 - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool`
1833
1834 - `BetaManagedAgentsAgentToolset20260401 object`
1835
1836 - `type: "agent_toolset_20260401"`
1837
1838 - `configs: array of BetaManagedAgentsAgentToolConfig`
1839
1840 - `BetaManagedAgentsBashToolConfig object`
1841
1842 Configuration for the bash tool.
1843
1844 - `type: "bash"`
1845
1846 - `enabled: boolean`
1847
1848 - `name: "bash"`
1849
1850 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
1851
1852 Permission policy for tool execution.
1853
1854 - `BetaManagedAgentsAlwaysAllowPolicy object`
1855
1856 Tool calls are automatically approved without user confirmation.
1857
1858 - `type: "always_allow"`
1859
1860 - `BetaManagedAgentsAlwaysAskPolicy object`
1861
1862 Tool calls require user confirmation before execution.
1863
1864 - `type: "always_ask"`
1865
1866 - `BetaManagedAgentsAutoPolicy object`
1867
1868 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
1869
1870 - `type: "auto"`
1871
1872 - `BetaManagedAgentsEditToolConfig object`
1873
1874 Configuration for the edit tool.
1875
1876 - `type: "edit"`
1877
1878 - `enabled: boolean`
1879
1880 - `name: "edit"`
1881
1882 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
1883
1884 Permission policy for tool execution.
1885
1886 - `BetaManagedAgentsAlwaysAllowPolicy object`
1887
1888 Tool calls are automatically approved without user confirmation.
1889
1890 - `BetaManagedAgentsAlwaysAskPolicy object`
1891
1892 Tool calls require user confirmation before execution.
1893
1894 - `BetaManagedAgentsAutoPolicy object`
1895
1896 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
1897
1898 - `BetaManagedAgentsReadToolConfig object`
1899
1900 Configuration for the read tool.
1901
1902 - `type: "read"`
1903
1904 - `enabled: boolean`
1905
1906 - `name: "read"`
1907
1908 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
1909
1910 Permission policy for tool execution.
1911
1912 - `BetaManagedAgentsAlwaysAllowPolicy object`
1913
1914 Tool calls are automatically approved without user confirmation.
1915
1916 - `BetaManagedAgentsAlwaysAskPolicy object`
1917
1918 Tool calls require user confirmation before execution.
1919
1920 - `BetaManagedAgentsAutoPolicy object`
1921
1922 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
1923
1924 - `BetaManagedAgentsWriteToolConfig object`
1925
1926 Configuration for the write tool.
1927
1928 - `type: "write"`
1929
1930 - `enabled: boolean`
1931
1932 - `name: "write"`
1933
1934 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
1935
1936 Permission policy for tool execution.
1937
1938 - `BetaManagedAgentsAlwaysAllowPolicy object`
1939
1940 Tool calls are automatically approved without user confirmation.
1941
1942 - `BetaManagedAgentsAlwaysAskPolicy object`
1943
1944 Tool calls require user confirmation before execution.
1945
1946 - `BetaManagedAgentsAutoPolicy object`
1947
1948 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
1949
1950 - `BetaManagedAgentsGlobToolConfig object`
1951
1952 Configuration for the glob tool.
1953
1954 - `type: "glob"`
1955
1956 - `enabled: boolean`
1957
1958 - `name: "glob"`
1959
1960 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
1961
1962 Permission policy for tool execution.
1963
1964 - `BetaManagedAgentsAlwaysAllowPolicy object`
1965
1966 Tool calls are automatically approved without user confirmation.
1967
1968 - `BetaManagedAgentsAlwaysAskPolicy object`
1969
1970 Tool calls require user confirmation before execution.
1971
1972 - `BetaManagedAgentsAutoPolicy object`
1973
1974 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
1975
1976 - `BetaManagedAgentsGrepToolConfig object`
1977
1978 Configuration for the grep tool.
1979
1980 - `type: "grep"`
1981
1982 - `enabled: boolean`
1983
1984 - `name: "grep"`
1985
1986 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
1987
1988 Permission policy for tool execution.
1989
1990 - `BetaManagedAgentsAlwaysAllowPolicy object`
1991
1992 Tool calls are automatically approved without user confirmation.
1993
1994 - `BetaManagedAgentsAlwaysAskPolicy object`
1995
1996 Tool calls require user confirmation before execution.
1997
1998 - `BetaManagedAgentsAutoPolicy object`
1999
2000 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
2001
2002 - `BetaManagedAgentsWebFetchToolConfig object`
2003
2004 Configuration for the web_fetch tool.
2005
2006 - `type: "web_fetch"`
2007
2008 - `enabled: boolean`
2009
2010 - `name: "web_fetch"`
2011
2012 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
2013
2014 Permission policy for tool execution.
2015
2016 - `BetaManagedAgentsAlwaysAllowPolicy object`
2017
2018 Tool calls are automatically approved without user confirmation.
2019
2020 - `BetaManagedAgentsAlwaysAskPolicy object`
2021
2022 Tool calls require user confirmation before execution.
2023
2024 - `BetaManagedAgentsAutoPolicy object`
2025
2026 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
2027
2028 - `allowed_domains: optional array of string`
2029
2030 - `blocked_domains: optional array of string`
2031
2032 - `max_content_tokens: optional number or null`
2033
2034 format: int32
2035
2036 - `BetaManagedAgentsWebSearchToolConfig object`
2037
2038 Configuration for the web_search tool.
2039
2040 - `type: "web_search"`
2041
2042 - `enabled: boolean`
2043
2044 - `name: "web_search"`
2045
2046 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
2047
2048 Permission policy for tool execution.
2049
2050 - `BetaManagedAgentsAlwaysAllowPolicy object`
2051
2052 Tool calls are automatically approved without user confirmation.
2053
2054 - `BetaManagedAgentsAlwaysAskPolicy object`
2055
2056 Tool calls require user confirmation before execution.
2057
2058 - `BetaManagedAgentsAutoPolicy object`
2059
2060 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
2061
2062 - `allowed_domains: optional array of string`
2063
2064 - `blocked_domains: optional array of string`
2065
2066 - `user_location: optional BetaManagedAgentsUserLocation or null`
2067
2068 Approximate user location for search result localization.
2069
2070 - `type: "approximate"`
2071
2072 Location precision. Only "approximate" is supported.
2073
2074 - `city: optional string or null`
2075
2076 City name.
2077
2078 minLength: 1, maxLength: 255
2079
2080 - `country: optional string or null`
2081
2082 Two-letter ISO 3166-1 country code, uppercase.
2083
2084 - `region: optional string or null`
2085
2086 Region or state name.
2087
2088 minLength: 1, maxLength: 255
2089
2090 - `timezone: optional string or null`
2091
2092 IANA timezone identifier, e.g. "America/Los_Angeles".
2093
2094 minLength: 1, maxLength: 255
2095
2096 - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig`
2097
2098 Resolved default configuration for agent tools.
2099
2100 - `enabled: boolean`
2101
2102 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
2103
2104 Permission policy for tool execution.
2105
2106 - `BetaManagedAgentsAlwaysAllowPolicy object`
2107
2108 Tool calls are automatically approved without user confirmation.
2109
2110 - `BetaManagedAgentsAlwaysAskPolicy object`
2111
2112 Tool calls require user confirmation before execution.
2113
2114 - `BetaManagedAgentsAutoPolicy object`
2115
2116 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
2117
2118 - `BetaManagedAgentsMCPToolset object`
2119
2120 - `type: "mcp_toolset"`
2121
2122 - `configs: array of BetaManagedAgentsMCPToolConfig`
2123
2124 - `enabled: boolean`
2125
2126 - `name: string`
2127
2128 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
2129
2130 Permission policy for tool execution.
2131
2132 - `BetaManagedAgentsAlwaysAllowPolicy object`
2133
2134 Tool calls are automatically approved without user confirmation.
2135
2136 - `BetaManagedAgentsAlwaysAskPolicy object`
2137
2138 Tool calls require user confirmation before execution.
2139
2140 - `BetaManagedAgentsAutoPolicy object`
2141
2142 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
2143
2144 - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig`
2145
2146 Resolved default configuration for all tools from an MCP server.
2147
2148 - `enabled: boolean`
2149
2150 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
2151
2152 Permission policy for tool execution.
2153
2154 - `BetaManagedAgentsAlwaysAllowPolicy object`
2155
2156 Tool calls are automatically approved without user confirmation.
2157
2158 - `BetaManagedAgentsAlwaysAskPolicy object`
2159
2160 Tool calls require user confirmation before execution.
2161
2162 - `BetaManagedAgentsAutoPolicy object`
2163
2164 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
2165
2166 - `mcp_server_name: string`
2167
2168 - `BetaManagedAgentsCustomTool object`
2169
2170 A custom tool as returned in API responses.
2171
2172 - `type: "custom"`
2173
2174 - `description: string`
2175
2176 - `input_schema: BetaManagedAgentsCustomToolInputSchema`
2177
2178 JSON Schema for custom tool input parameters.
2179
2180 - `type: "object"`
2181
2182 - `properties: optional map[unknown] or null`
2183
2184 - `required: optional array of string or null`
2185
2186 - `name: string`
2187
2188 - `version: number`
2189
2190 format: int32
2191
2192 - `BetaManagedAgentsAdvisor object`
2193
2194 Platform advisor roster entry: a model the session's primary thread may consult mid-turn.
2195
2196 - `type: "advisor"`
2197
2198 - `model: string`
2199
2200 The advisor model id.
2201
2202 - `name: string`
2203
2204 - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill`
2205
2206 - `BetaManagedAgentsAnthropicSkill object`
2207
2208 A resolved Anthropic-managed skill.
2209
2210 - `BetaManagedAgentsCustomSkill object`
2211
2212 A resolved user-created custom skill.
2213
2214 - `system: string or null`
2215
2216 - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool`
2217
2218 - `BetaManagedAgentsAgentToolset20260401 object`
2219
2220 - `BetaManagedAgentsMCPToolset object`
2221
2222 - `BetaManagedAgentsCustomTool object`
2223
2224 A custom tool as returned in API responses.
2225
2226 - `version: number`
2227
2228 format: int32
2229
2230 - `budget: optional BetaManagedAgentsBudgetLimit or null`
2231
2232 A hard spend ceiling. The session stops issuing new model requests once the tracked list cost reaches `max_list_cost`.
2233
2234 - `type: "limit"`
2235
2236 - `max_list_cost: BetaMonetaryAmount`
2237
2238 A monetary amount in a specific currency.
2239
2240 - `amount: string`
2241
2242 Amount in minor units of the currency, as an integer decimal string with no leading zeros: "2500" is $25.00 and "50" is fifty cents. A string rather than a number so no float rounding is ever applied.
2243
2244 - `currency: BetaCurrency`
2245
2246 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.
2247
2248 - `metadata: optional map[string]`
2249
2250 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.
2251
2252 - `title: optional string or null`
2253
2254 The session's new title. Present only when the update changed it.
2255
2256 - `BetaManagedAgentsStartEvent object`
2257
2258 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.
2259
2260 - `type: "event_start"`
2261
2262 - `event: BetaManagedAgentsStartEventPreview`
2263
2264 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.
2265
2266 - `BetaManagedAgentsAgentMessagePreview object`
2267
2268 - `type: "agent.message"`
2269
2270 - `id: string`
2271
2272 The id the buffered agent.message will carry if it is emitted. Matches the event_id on this preview's event_delta events.
2273
2274 - `BetaManagedAgentsAgentThinkingPreview object`
2275
2276 - `type: "agent.thinking"`
2277
2278 - `id: string`
2279
2280 The id the buffered agent.thinking will carry if it is emitted. Start-only — no event_delta events follow.
2281
2282 - `BetaManagedAgentsDeltaEvent object`
2283
2284 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.
2285
2286 - `type: "event_delta"`
2287
2288 - `delta: BetaManagedAgentsDeltaContent`
2289
2290 One fragment of the previewed event. The delta type is named for the previewed event's field it streams into: agent.message events stream content_delta fragments, each a partial element of the content array.
2291
2292 - `type: "content_delta"`
2293
2294 - `content: BetaManagedAgentsTextBlock`
2295
2296 Regular text content.
2297
2298 - `index: optional number`
2299
2300 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.
2301
2302 format: uint32
2303
2304 - `event_id: string`
2305
2306 The id of the event being previewed. Matches event.id on the corresponding event_start and the buffered event that reconciles the preview.
2307
2308 - `BetaManagedAgentsSystemMessageEvent object`
2309
2310 A mid-conversation system message event. Carries system-role content that is appended to the session as a `role: "system"` turn.
2311
2312 - `type: "system.message"`
2313
2314 - `id: string`
2315
2316 Unique identifier for this event.
2317
2318 - `content: array of BetaManagedAgentsSystemContentBlock`
2319
2320 System content blocks. Text-only.
2321
2322 - `type: "text"`
2323
2324 - `text: string`
2325
2326 The text content.
2327
2328 minLength: 1
3022329
3032330 - `processed_at: optional string or null`
3042331
from line 2333
3062333
3072334 format: date-time
3082335
309 - `session_thread_id: optional string or null`
310
311 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.
312
313 - `BetaManagedAgentsUserToolConfirmationEvent object`
314
315 A tool confirmation event that approves or denies a pending tool execution.
316
317 - `id: string`
318
319 Unique identifier for this event.
320
321 - `result: "allow" or "deny"`
322
323 UserToolConfirmationResult enum
324
325 - `"allow"`
326
327 - `"deny"`
328
329 - `tool_use_id: string`
330
331 The id of the `agent.tool_use` or `agent.mcp_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field.
332
333 - `type: "user.tool_confirmation"`
334
335 - `deny_message: optional string or null`
336
337 Optional message providing context for a 'deny' decision. Only allowed when result is 'deny'.
338
339 maxLength: 10000
340
341 - `processed_at: optional string or null`
342
343 A timestamp in RFC 3339 format
344
345 format: date-time
346
347 - `session_thread_id: optional string or null`
348
349 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.
350
351 - `BetaManagedAgentsUserCustomToolResultEvent object`
352
353 Event sent by the client providing the result of a custom tool execution.
354
355 - `id: string`
356
357 Unique identifier for this event.
358
359 - `custom_tool_use_id: string`
360
361 The id of the `agent.custom_tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field.
362
363 - `type: "user.custom_tool_result"`
364
365 - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock`
366
367 The result content returned by the tool.
368
369 - `BetaManagedAgentsTextBlock object`
370
371 Regular text content.
372
373 - `BetaManagedAgentsImageBlock object`
374
375 Image content specified directly as base64 data or as a reference via a URL.
376
377 - `BetaManagedAgentsDocumentBlock object`
378
379 Document content, either specified directly as base64 data, as text, or as a reference via a URL.
380
381 - `BetaManagedAgentsSearchResultBlock object`
382
383 A block containing a web search result.
384
385 - `citations: BetaManagedAgentsSearchResultCitations`
386
387 Citation settings for a search result.
388
389 - `enabled: boolean`
390
391 Whether citations are enabled for this search result.
392
393 - `content: array of BetaManagedAgentsSearchResultContent`
394
395 Array of text content blocks from the search result.
396
397 - `text: string`
398
399 The text content.
400
401 minLength: 1
402
403 - `type: "text"`
404
405 - `source: string`
406
407 The URL source of the search result.
408
409 minLength: 1
410
411 - `title: string`
412
413 The title of the search result.
414
415 minLength: 1
416
417 - `type: "search_result"`
418
419 - `is_error: optional boolean or null`
420
421 Whether the tool execution resulted in an error.
422
423 - `processed_at: optional string or null`
424
425 A timestamp in RFC 3339 format
426
427 format: date-time
428
429 - `session_thread_id: optional string or null`
430
431 Routes this result to a subagent thread. Copy from the `agent.custom_tool_use` event's `session_thread_id`.
432
433 - `BetaManagedAgentsAgentCustomToolUseEvent object`
434
435 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.
436
437 - `id: string`
438
439 Unique identifier for this event.
440
441 - `input: map[unknown]`
442
443 Input parameters for the tool call.
444
445 - `name: string`
446
447 Name of the custom tool being called.
448
449 - `processed_at: string`
450
451 A timestamp in RFC 3339 format
452
453 format: date-time
454
455 - `type: "agent.custom_tool_use"`
456
457 - `session_thread_id: optional string or null`
458
459 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.
460
461 - `BetaManagedAgentsAgentMessageEvent object`
462
463 An agent response event in the session conversation.
464
465 - `id: string`
466
467 Unique identifier for this event.
468
469 - `content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsRedactedBlock`
470
471 Array of text blocks comprising the agent response.
472
473 - `BetaManagedAgentsTextBlock object`
474
475 Regular text content.
476
477 - `BetaManagedAgentsRedactedBlock object`
478
479 Placeholder for content withheld by Anthropic model policy.
480
481 - `processed_at: string`
482
483 A timestamp in RFC 3339 format
484
485 format: date-time
486
487 - `type: "agent.message"`
488
489 - `BetaManagedAgentsAgentThinkingEvent object`
490
491 Indicates the agent is making forward progress via extended thinking. A progress signal, not a content carrier.
492
493 - `id: string`
494
495 Unique identifier for this event.
496
497 - `processed_at: string`
498
499 A timestamp in RFC 3339 format
500
501 format: date-time
502
503 - `type: "agent.thinking"`
504
505 - `BetaManagedAgentsAgentMCPToolUseEvent object`
506
507 Event emitted when the agent invokes a tool provided by an MCP server.
508
509 - `id: string`
510
511 Unique identifier for this event.
512
513 - `input: map[unknown]`
514
515 Input parameters for the tool call.
516
517 - `mcp_server_name: string`
518
519 Name of the MCP server providing the tool.
520
521 - `name: string`
522
523 Name of the MCP tool being used.
524
525 - `processed_at: string`
526
527 A timestamp in RFC 3339 format
528
529 format: date-time
530
531 - `type: "agent.mcp_tool_use"`
532
533 - `evaluated_permission: optional "allow" or "ask" or "deny"`
534
535 AgentEvaluatedPermission enum
536
537 - `"allow"`
538
539 - `"ask"`
540
541 - `"deny"`
542
543 - `session_thread_id: optional string or null`
544
545 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.
546
547 - `BetaManagedAgentsAgentMCPToolResultEvent object`
548
549 Event representing the result of an MCP tool execution.
550
551 - `id: string`
552
553 Unique identifier for this event.
554
555 - `mcp_tool_use_id: string`
556
557 The id of the `agent.mcp_tool_use` event this result corresponds to.
558
559 - `processed_at: string`
560
561 A timestamp in RFC 3339 format
562
563 format: date-time
564
565 - `type: "agent.mcp_tool_result"`
566
567 - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock`
568
569 The result content returned by the tool.
570
571 - `BetaManagedAgentsTextBlock object`
572
573 Regular text content.
574
575 - `BetaManagedAgentsImageBlock object`
576
577 Image content specified directly as base64 data or as a reference via a URL.
578
579 - `BetaManagedAgentsDocumentBlock object`
580
581 Document content, either specified directly as base64 data, as text, or as a reference via a URL.
582
583 - `BetaManagedAgentsSearchResultBlock object`
584
585 A block containing a web search result.
586
587 - `is_error: optional boolean or null`
588
589 Whether the tool execution resulted in an error.
590
591 - `BetaManagedAgentsAgentToolUseEvent object`
592
593 Event emitted when the agent invokes a built-in agent tool.
594
595 - `id: string`
596
597 Unique identifier for this event.
598
599 - `input: map[unknown]`
600
601 Input parameters for the tool call.
602
603 - `name: string`
604
605 Name of the agent tool being used.
606
607 - `processed_at: string`
608
609 A timestamp in RFC 3339 format
610
611 format: date-time
612
613 - `type: "agent.tool_use"`
614
615 - `evaluated_permission: optional "allow" or "ask" or "deny"`
616
617 AgentEvaluatedPermission enum
618
619 - `"allow"`
620
621 - `"ask"`
622
623 - `"deny"`
624
625 - `session_thread_id: optional string or null`
626
627 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.
628
629 - `BetaManagedAgentsAgentToolResultEvent object`
630
631 Event representing the result of an agent tool execution.
632
633 - `id: string`
634
635 Unique identifier for this event.
636
637 - `processed_at: string`
638
639 A timestamp in RFC 3339 format
640
641 format: date-time
642
643 - `tool_use_id: string`
644
645 The id of the `agent.tool_use` event this result corresponds to.
646
647 - `type: "agent.tool_result"`
648
649 - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock`
650
651 The result content returned by the tool.
652
653 - `BetaManagedAgentsTextBlock object`
654
655 Regular text content.
656
657 - `BetaManagedAgentsImageBlock object`
658
659 Image content specified directly as base64 data or as a reference via a URL.
660
661 - `BetaManagedAgentsDocumentBlock object`
662
663 Document content, either specified directly as base64 data, as text, or as a reference via a URL.
664
665 - `BetaManagedAgentsSearchResultBlock object`
666
667 A block containing a web search result.
668
669 - `is_error: optional boolean or null`
670
671 Whether the tool execution resulted in an error.
672
673 - `BetaManagedAgentsAgentThreadMessageReceivedEvent object`
674
675 Delivery event written to the target thread's input stream when an agent-to-agent message arrives.
676
677 - `id: string`
678
679 Unique identifier for this event.
680
681 - `content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsRedactedBlock`
682
683 Message content blocks.
684
685 - `BetaManagedAgentsTextBlock object`
686
687 Regular text content.
688
689 - `BetaManagedAgentsImageBlock object`
690
691 Image content specified directly as base64 data or as a reference via a URL.
692
693 - `BetaManagedAgentsDocumentBlock object`
694
695 Document content, either specified directly as base64 data, as text, or as a reference via a URL.
696
697 - `BetaManagedAgentsRedactedBlock object`
698
699 Placeholder for content withheld by Anthropic model policy.
700
701 - `from_session_thread_id: string`
702
703 Public `sthr_` ID of the thread that sent the message.
704
705 - `processed_at: string`
706
707 A timestamp in RFC 3339 format
708
709 format: date-time
710
711 - `type: "agent.thread_message_received"`
712
713 - `from_agent_name: optional string or null`
714
715 Name of the callable agent this message came from. Absent when received from the primary agent.
716
717 - `BetaManagedAgentsAgentThreadMessageSentEvent object`
718
719 Observability event emitted to the sender's output stream when an agent-to-agent message is sent.
720
721 - `id: string`
722
723 Unique identifier for this event.
724
725 - `content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsRedactedBlock`
726
727 Message content blocks.
728
729 - `BetaManagedAgentsTextBlock object`
730
731 Regular text content.
732
733 - `BetaManagedAgentsImageBlock object`
734
735 Image content specified directly as base64 data or as a reference via a URL.
736
737 - `BetaManagedAgentsDocumentBlock object`
738
739 Document content, either specified directly as base64 data, as text, or as a reference via a URL.
740
741 - `BetaManagedAgentsRedactedBlock object`
742
743 Placeholder for content withheld by Anthropic model policy.
744
745 - `processed_at: string`
746
747 A timestamp in RFC 3339 format
748
749 format: date-time
750
751 - `to_session_thread_id: string`
752
753 Public `sthr_` ID of the thread the message was sent to.
754
755 - `type: "agent.thread_message_sent"`
756
757 - `to_agent_name: optional string or null`
758
759 Name of the callable agent this message was sent to. Absent when sent to the primary agent.
760
761 - `BetaManagedAgentsAgentThreadContextCompactedEvent object`
762
763 Indicates that context compaction (summarization) occurred during the session.
764
765 - `id: string`
766
767 Unique identifier for this event.
768
769 - `processed_at: string`
770
771 A timestamp in RFC 3339 format
772
773 format: date-time
774
775 - `type: "agent.thread_context_compacted"`
776
777 - `BetaManagedAgentsSessionErrorEvent object`
778
779 An error event indicating a problem occurred during session execution.
780
781 - `id: string`
782
783 Unique identifier for this event.
784
785 - `error: BetaManagedAgentsUnknownError or BetaManagedAgentsModelOverloadedError or BetaManagedAgentsModelRateLimitedError or 5 more`
786
787 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.
788
789 - `BetaManagedAgentsUnknownError object`
790
791 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.
792
793 - `message: string`
794
795 Human-readable error description.
796
797 - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal`
798
799 What the client should do next in response to this error.
800
801 - `BetaManagedAgentsRetryStatusRetrying object`
802
803 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.
804
805 - `type: "retrying"`
806
807 - `BetaManagedAgentsRetryStatusExhausted object`
808
809 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
810
811 - `type: "exhausted"`
812
813 - `BetaManagedAgentsRetryStatusTerminal object`
814
815 The session encountered a terminal error and will transition to `terminated` state.
816
817 - `type: "terminal"`
818
819 - `type: "unknown_error"`
820
821 - `BetaManagedAgentsModelOverloadedError object`
822
823 The model is currently overloaded. Emitted after automatic retries are exhausted.
824
825 - `message: string`
826
827 Human-readable error description.
828
829 - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal`
830
831 What the client should do next in response to this error.
832
833 - `BetaManagedAgentsRetryStatusRetrying object`
834
835 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.
836
837 - `BetaManagedAgentsRetryStatusExhausted object`
838
839 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
840
841 - `BetaManagedAgentsRetryStatusTerminal object`
842
843 The session encountered a terminal error and will transition to `terminated` state.
844
845 - `type: "model_overloaded_error"`
846
847 - `BetaManagedAgentsModelRateLimitedError object`
848
849 The model request was rate-limited.
850
851 - `message: string`
852
853 Human-readable error description.
854
855 - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal`
856
857 What the client should do next in response to this error.
858
859 - `BetaManagedAgentsRetryStatusRetrying object`
860
861 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.
862
863 - `BetaManagedAgentsRetryStatusExhausted object`
864
865 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
866
867 - `BetaManagedAgentsRetryStatusTerminal object`
868
869 The session encountered a terminal error and will transition to `terminated` state.
870
871 - `type: "model_rate_limited_error"`
872
873 - `BetaManagedAgentsModelRequestFailedError object`
874
875 A model request failed for a reason other than overload or rate-limiting.
876
877 - `message: string`
878
879 Human-readable error description.
880
881 - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal`
882
883 What the client should do next in response to this error.
884
885 - `BetaManagedAgentsRetryStatusRetrying object`
886
887 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.
888
889 - `BetaManagedAgentsRetryStatusExhausted object`
890
891 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
892
893 - `BetaManagedAgentsRetryStatusTerminal object`
894
895 The session encountered a terminal error and will transition to `terminated` state.
896
897 - `type: "model_request_failed_error"`
898
899 - `BetaManagedAgentsMCPConnectionFailedError object`
900
901 Failed to connect to an MCP server.
902
903 - `mcp_server_name: string`
904
905 Name of the MCP server that failed to connect.
906
907 - `message: string`
908
909 Human-readable error description.
910
911 - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal`
912
913 What the client should do next in response to this error.
914
915 - `BetaManagedAgentsRetryStatusRetrying object`
916
917 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.
918
919 - `BetaManagedAgentsRetryStatusExhausted object`
920
921 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
922
923 - `BetaManagedAgentsRetryStatusTerminal object`
924
925 The session encountered a terminal error and will transition to `terminated` state.
926
927 - `type: "mcp_connection_failed_error"`
928
929 - `BetaManagedAgentsMCPAuthenticationFailedError object`
930
931 Authentication to an MCP server failed.
932
933 - `mcp_server_name: string`
934
935 Name of the MCP server that failed authentication.
936
937 - `message: string`
938
939 Human-readable error description.
940
941 - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal`
942
943 What the client should do next in response to this error.
944
945 - `BetaManagedAgentsRetryStatusRetrying object`
946
947 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.
948
949 - `BetaManagedAgentsRetryStatusExhausted object`
950
951 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
952
953 - `BetaManagedAgentsRetryStatusTerminal object`
954
955 The session encountered a terminal error and will transition to `terminated` state.
956
957 - `type: "mcp_authentication_failed_error"`
958
959 - `BetaManagedAgentsBillingError object`
960
961 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.
962
963 - `message: string`
964
965 Human-readable error description.
966
967 - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal`
968
969 What the client should do next in response to this error.
970
971 - `BetaManagedAgentsRetryStatusRetrying object`
972
973 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.
974
975 - `BetaManagedAgentsRetryStatusExhausted object`
976
977 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
978
979 - `BetaManagedAgentsRetryStatusTerminal object`
980
981 The session encountered a terminal error and will transition to `terminated` state.
982
983 - `type: "billing_error"`
984
985 - `BetaManagedAgentsCredentialHostUnreachableError object`
986
987 An `environment_variable` credential's `auth.networking.allowed_hosts` includes a host the environment's network policy does not permit.
988
989 - `credential_id: string`
990
991 ID of the affected credential.
992
993 - `message: string`
994
995 Human-readable error description.
996
997 - `retry_status: BetaManagedAgentsRetryStatusRetrying or BetaManagedAgentsRetryStatusExhausted or BetaManagedAgentsRetryStatusTerminal`
998
999 What the client should do next in response to this error.
1000
1001 - `BetaManagedAgentsRetryStatusRetrying object`
1002
1003 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.
1004
1005 - `BetaManagedAgentsRetryStatusExhausted object`
1006
1007 This turn is dead; queued inputs are flushed and the session returns to idle. Client may send a new prompt.
1008
1009 - `BetaManagedAgentsRetryStatusTerminal object`
1010
1011 The session encountered a terminal error and will transition to `terminated` state.
1012
1013 - `type: "credential_host_unreachable_error"`
1014
1015 - `vault_id: string`
1016
1017 ID of the vault containing the affected credential.
1018
1019 - `processed_at: string`
1020
1021 A timestamp in RFC 3339 format
1022
1023 format: date-time
1024
1025 - `type: "session.error"`
1026
1027 - `BetaManagedAgentsSessionStatusRescheduledEvent object`
1028
1029 Indicates the session is recovering from an error state and is rescheduled for execution.
1030
1031 - `id: string`
1032
1033 Unique identifier for this event.
1034
1035 - `processed_at: string`
1036
1037 A timestamp in RFC 3339 format
1038
1039 format: date-time
1040
1041 - `type: "session.status_rescheduled"`
1042
1043 - `BetaManagedAgentsSessionStatusRunningEvent object`
1044
1045 Indicates the session is actively running and the agent is working.
1046
1047 - `id: string`
1048
1049 Unique identifier for this event.
1050
1051 - `processed_at: string`
1052
1053 A timestamp in RFC 3339 format
1054
1055 format: date-time
1056
1057 - `type: "session.status_running"`
1058
1059 - `BetaManagedAgentsSessionStatusIdleEvent object`
1060
1061 Indicates the agent has paused and is awaiting user input.
1062
1063 - `id: string`
1064
1065 Unique identifier for this event.
1066
1067 - `processed_at: string`
1068
1069 A timestamp in RFC 3339 format
1070
1071 format: date-time
1072
1073 - `stop_reason: BetaManagedAgentsSessionEndTurn or BetaManagedAgentsSessionRequiresAction or BetaManagedAgentsSessionRetriesExhausted or BetaManagedAgentsSessionBudgetReached`
1074
1075 The agent completed its turn naturally and is ready for the next user message.
1076
1077 - `BetaManagedAgentsSessionEndTurn object`
1078
1079 The agent completed its turn naturally and is ready for the next user message.
1080
1081 - `type: "end_turn"`
1082
1083 - `BetaManagedAgentsSessionRequiresAction object`
1084
1085 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.
1086
1087 - `event_ids: array of string`
1088
1089 The ids of events the agent is blocked on. Resolving fewer than all re-emits `session.status_idle` with the remainder.
1090
1091 - `type: "requires_action"`
1092
1093 - `BetaManagedAgentsSessionRetriesExhausted object`
1094
1095 The turn ended because repeated errors exhausted the retry budget or an error escalated to `retry_status: 'exhausted'`.
1096
1097 - `type: "retries_exhausted"`
1098
1099 - `BetaManagedAgentsSessionBudgetReached object`
1100
1101 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.
1102
1103 - `type: "budget_reached"`
1104
1105 - `type: "session.status_idle"`
1106
1107 - `BetaManagedAgentsSessionStatusTerminatedEvent object`
1108
1109 Indicates the session has terminated, either due to an error or completion.
1110
1111 - `id: string`
1112
1113 Unique identifier for this event.
1114
1115 - `processed_at: string`
1116
1117 A timestamp in RFC 3339 format
1118
1119 format: date-time
1120
1121 - `type: "session.status_terminated"`
1122
1123 - `BetaManagedAgentsSessionThreadCreatedEvent object`
1124
1125 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.
1126
1127 - `id: string`
1128
1129 Unique identifier for this event.
1130
1131 - `agent_name: string`
1132
1133 Name of the callable agent the thread runs.
1134
1135 - `processed_at: string`
1136
1137 A timestamp in RFC 3339 format
1138
1139 format: date-time
1140
1141 - `session_thread_id: string`
1142
1143 Public `sthr_` ID of the newly created thread.
1144
1145 - `type: "session.thread_created"`
1146
1147 - `BetaManagedAgentsSpanOutcomeEvaluationStartEvent object`
1148
1149 Emitted when an outcome evaluation cycle begins.
1150
1151 - `id: string`
1152
1153 Unique identifier for this event.
1154
1155 - `iteration: number`
1156
1157 0-indexed revision cycle. 0 is the first evaluation; 1 is the re-evaluation after the first revision; etc.
1158
1159 format: int32
1160
1161 - `outcome_id: string`
1162
1163 The `outc_` ID of the outcome being evaluated.
1164
1165 - `processed_at: string`
1166
1167 A timestamp in RFC 3339 format
1168
1169 format: date-time
1170
1171 - `type: "span.outcome_evaluation_start"`
1172
1173 - `BetaManagedAgentsSpanOutcomeEvaluationEndEvent object`
1174
1175 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.
1176
1177 - `id: string`
1178
1179 Unique identifier for this event.
1180
1181 - `explanation: string`
1182
1183 Human-readable explanation of the verdict. For `needs_revision`, describes which criteria failed and why.
1184
1185 - `iteration: number`
1186
1187 0-indexed revision cycle, matching the corresponding `span.outcome_evaluation_start`.
1188
1189 format: int32
1190
1191 - `outcome_evaluation_start_id: string`
1192
1193 The id of the corresponding `span.outcome_evaluation_start` event.
1194
1195 - `outcome_id: string`
1196
1197 The `outc_` ID of the outcome being evaluated.
1198
1199 - `processed_at: string`
1200
1201 A timestamp in RFC 3339 format
1202
1203 format: date-time
1204
1205 - `result: string`
1206
1207 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.
1208
1209 - `type: "span.outcome_evaluation_end"`
1210
1211 - `usage: BetaManagedAgentsSpanModelUsage`
1212
1213 Token usage for a single model request.
1214
1215 - `cache_creation_input_tokens: number`
1216
1217 Tokens used to create prompt cache in this request.
1218
1219 format: int32
1220
1221 - `cache_read_input_tokens: number`
1222
1223 Tokens read from prompt cache in this request.
1224
1225 format: int32
1226
1227 - `input_tokens: number`
1228
1229 Input tokens consumed by this request.
1230
1231 format: int32
1232
1233 - `output_tokens: number`
1234
1235 Output tokens generated by this request.
1236
1237 format: int32
1238
1239 - `speed: optional "standard" or "fast" or null`
1240
1241 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.
1242
1243 - `"standard"`
1244
1245 - `"fast"`
1246
1247 - `BetaManagedAgentsSpanModelRequestStartEvent object`
1248
1249 Emitted when a model request is initiated by the agent.
1250
1251 - `id: string`
1252
1253 Unique identifier for this event.
1254
1255 - `processed_at: string`
1256
1257 A timestamp in RFC 3339 format
1258
1259 format: date-time
1260
1261 - `type: "span.model_request_start"`
1262
1263 - `BetaManagedAgentsSpanModelRequestEndEvent object`
1264
1265 Emitted when a model request completes.
1266
1267 - `id: string`
1268
1269 Unique identifier for this event.
1270
1271 - `is_error: boolean or null`
1272
1273 Whether the model request resulted in an error.
1274
1275 - `model_request_start_id: string`
1276
1277 The id of the corresponding `span.model_request_start` event.
1278
1279 - `model_usage: BetaManagedAgentsSpanModelUsage`
1280
1281 Token usage for a single model request.
1282
1283 - `processed_at: string`
1284
1285 A timestamp in RFC 3339 format
1286
1287 format: date-time
1288
1289 - `type: "span.model_request_end"`
1290
1291 - `BetaManagedAgentsSpanOutcomeEvaluationOngoingEvent object`
1292
1293 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.
1294
1295 - `id: string`
1296
1297 Unique identifier for this event.
1298
1299 - `iteration: number`
1300
1301 0-indexed revision cycle, matching the corresponding `span.outcome_evaluation_start`.
1302
1303 format: int32
1304
1305 - `outcome_id: string`
1306
1307 The `outc_` ID of the outcome being evaluated.
1308
1309 - `processed_at: string`
1310
1311 A timestamp in RFC 3339 format
1312
1313 format: date-time
1314
1315 - `type: "span.outcome_evaluation_ongoing"`
1316
1317 - `BetaManagedAgentsUserDefineOutcomeEvent object`
1318
1319 Echo of a `user.define_outcome` input event. Carries the server-generated `outcome_id` that subsequent `span.outcome_evaluation_*` events reference.
1320
1321 - `id: string`
1322
1323 Unique identifier for this event.
1324
1325 - `description: string`
1326
1327 What the agent should produce. Copied from the input event.
1328
1329 - `max_iterations: number or null`
1330
1331 Evaluate-then-revise cycles before giving up. Default 3, max 20.
1332
1333 format: int32
1334
1335 - `outcome_id: string`
1336
1337 Server-generated `outc_` ID for this outcome. Referenced by `span.outcome_evaluation_*` events and the session's `outcome_evaluations` list.
1338
1339 - `processed_at: string`
1340
1341 A timestamp in RFC 3339 format
1342
1343 format: date-time
1344
1345 - `rubric: BetaManagedAgentsFileRubric or BetaManagedAgentsTextRubric`
1346
1347 Rubric for grading the quality of an outcome.
1348
1349 - `BetaManagedAgentsFileRubric object`
1350
1351 Rubric referenced by a file uploaded via the Files API.
1352
1353 - `file_id: string`
1354
1355 ID of the rubric file.
1356
1357 - `type: "file"`
1358
1359 - `BetaManagedAgentsTextRubric object`
1360
1361 Rubric content provided inline as text.
1362
1363 - `content: string`
1364
1365 Rubric content. Plain text or markdown — the grader treats it as freeform text.
1366
1367 - `type: "text"`
1368
1369 - `type: "user.define_outcome"`
1370
1371 - `BetaManagedAgentsSessionDeletedEvent object`
1372
1373 Emitted when a session has been deleted. Terminates any active event stream — no further events will be emitted for this session.
1374
1375 - `id: string`
1376
1377 Unique identifier for this event.
1378
1379 - `processed_at: string`
1380
1381 A timestamp in RFC 3339 format
1382
1383 format: date-time
1384
1385 - `type: "session.deleted"`
1386
1387 - `BetaManagedAgentsSessionThreadStatusRunningEvent object`
1388
1389 A session thread has begun executing. Emitted on the thread's own stream and cross-posted to the primary stream for child threads.
1390
1391 - `id: string`
1392
1393 Unique identifier for this event.
1394
1395 - `agent_name: string`
1396
1397 Name of the agent the thread runs.
1398
1399 - `processed_at: string`
1400
1401 A timestamp in RFC 3339 format
1402
1403 format: date-time
1404
1405 - `session_thread_id: string`
1406
1407 Public sthr_ ID of the thread that started running.
1408
1409 - `type: "session.thread_status_running"`
1410
1411 - `BetaManagedAgentsSessionThreadStatusIdleEvent object`
1412
1413 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.
1414
1415 - `id: string`
1416
1417 Unique identifier for this event.
1418
1419 - `agent_name: string`
1420
1421 Name of the agent the thread runs.
1422
1423 - `processed_at: string`
1424
1425 A timestamp in RFC 3339 format
1426
1427 format: date-time
1428
1429 - `session_thread_id: string`
1430
1431 Public sthr_ ID of the thread that went idle.
1432
1433 - `stop_reason: BetaManagedAgentsSessionEndTurn or BetaManagedAgentsSessionRequiresAction or BetaManagedAgentsSessionRetriesExhausted or BetaManagedAgentsSessionBudgetReached`
1434
1435 The agent completed its turn naturally and is ready for the next user message.
1436
1437 - `BetaManagedAgentsSessionEndTurn object`
1438
1439 The agent completed its turn naturally and is ready for the next user message.
1440
1441 - `BetaManagedAgentsSessionRequiresAction object`
1442
1443 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.
1444
1445 - `BetaManagedAgentsSessionRetriesExhausted object`
1446
1447 The turn ended because repeated errors exhausted the retry budget or an error escalated to `retry_status: 'exhausted'`.
1448
1449 - `BetaManagedAgentsSessionBudgetReached object`
1450
1451 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.
1452
1453 - `type: "session.thread_status_idle"`
1454
1455 - `BetaManagedAgentsSessionThreadStatusTerminatedEvent object`
1456
1457 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.
1458
1459 - `id: string`
1460
1461 Unique identifier for this event.
1462
1463 - `agent_name: string`
1464
1465 Name of the agent the thread runs.
1466
1467 - `processed_at: string`
1468
1469 A timestamp in RFC 3339 format
1470
1471 format: date-time
1472
1473 - `session_thread_id: string`
1474
1475 Public sthr_ ID of the thread that terminated.
1476
1477 - `type: "session.thread_status_terminated"`
1478
1479 - `BetaManagedAgentsUserToolResultEvent object`
1480
1481 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.
1482
1483 - `id: string`
1484
1485 Unique identifier for this event.
1486
1487 - `tool_use_id: string`
1488
1489 The id of the `agent.tool_use` event this result corresponds to, which can be found in the last `session.status_idle` [event's](https://platform.claude.com/docs/en/api/beta/sessions/events/list#beta_managed_agents_session_requires_action.event_ids) `stop_reason.event_ids` field.
1490
1491 - `type: "user.tool_result"`
1492
1493 - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock`
1494
1495 The result content returned by the tool.
1496
1497 - `BetaManagedAgentsTextBlock object`
1498
1499 Regular text content.
1500
1501 - `BetaManagedAgentsImageBlock object`
1502
1503 Image content specified directly as base64 data or as a reference via a URL.
1504
1505 - `BetaManagedAgentsDocumentBlock object`
1506
1507 Document content, either specified directly as base64 data, as text, or as a reference via a URL.
1508
1509 - `BetaManagedAgentsSearchResultBlock object`
1510
1511 A block containing a web search result.
1512
1513 - `is_error: optional boolean or null`
1514
1515 Whether the tool execution resulted in an error.
1516
1517 - `processed_at: optional string or null`
1518
1519 A timestamp in RFC 3339 format
1520
1521 format: date-time
1522
1523 - `session_thread_id: optional string or null`
1524
1525 Routes this result to a subagent thread. Copy from the `agent.tool_use` event's `session_thread_id`.
1526
1527 - `BetaManagedAgentsSessionThreadStatusRescheduledEvent object`
1528
1529 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.
1530
1531 - `id: string`
1532
1533 Unique identifier for this event.
1534
1535 - `agent_name: string`
1536
1537 Name of the agent the thread runs.
1538
1539 - `processed_at: string`
1540
1541 A timestamp in RFC 3339 format
1542
1543 format: date-time
1544
1545 - `session_thread_id: string`
1546
1547 Public sthr_ ID of the thread that is retrying.
1548
1549 - `type: "session.thread_status_rescheduled"`
1550
1551 - `BetaManagedAgentsSessionUpdatedEvent object`
1552
1553 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.
1554
1555 - `id: string`
1556
1557 Unique identifier for this event.
1558
1559 - `processed_at: string`
1560
1561 A timestamp in RFC 3339 format
1562
1563 format: date-time
1564
1565 - `type: "session.updated"`
1566
1567 - `agent: optional BetaManagedAgentsSessionAgent or null`
1568
1569 Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time.
1570
1571 - `id: string`
1572
1573 - `description: string or null`
1574
1575 - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition`
1576
1577 - `name: string`
1578
1579 - `type: "url"`
1580
1581 - `url: string`
1582
1583 - `model: BetaManagedAgentsModelConfig`
1584
1585 Model identifier and configuration.
1586
1587 - `id: BetaManagedAgentsModel`
1588
1589 The model that will power your agent.
1590
1591 See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options.
1592
1593 - `"claude-fable-5-1" or "claude-sonnet-5" or "claude-fable-5" or 11 more`
1594
1595 The model that will power your agent.
1596
1597 See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options.
1598
1599 - `"claude-fable-5-1"`
1600
1601 Frontier intelligence for ambitious tasks across coding, scientific discovery, and enterprise workflows
1602
1603 - `"claude-sonnet-5"`
1604
1605 High-performance model for coding and agents
1606
1607 - `"claude-fable-5"`
1608
1609 Next generation of intelligence for the hardest knowledge work and coding problems
1610
1611 - `"claude-opus-5"`
1612
1613 Powerful intelligence for long-running agents and coding
1614
1615 - `"claude-opus-4-8"`
1616
1617 Powerful intelligence for long-running agents and coding
1618
1619 - `"claude-opus-4-7"`
1620
1621 Powerful intelligence for long-running agents and coding
1622
1623 - `"claude-opus-4-6"`
1624
1625 Powerful intelligence for long-running agents and coding
1626
1627 - `"claude-sonnet-4-6"`
1628
1629 Best combination of speed and intelligence
1630
1631 - `"claude-haiku-4-5"`
1632
1633 Fastest model with near-frontier intelligence
1634
1635 - `"claude-haiku-4-5-20251001"`
1636
1637 Fastest model with near-frontier intelligence
1638
1639 - `"claude-opus-4-5"`
1640
1641 Powerful intelligence for long-running agents and coding
1642
1643 - `"claude-opus-4-5-20251101"`
1644
1645 Powerful intelligence for long-running agents and coding
1646
1647 - `"claude-sonnet-4-5"`
1648
1649 High-performance model for agents and coding
1650
1651 - `"claude-sonnet-4-5-20250929"`
1652
1653 High-performance model for agents and coding
1654
1655 - `string`
1656
1657 - `effort: optional BetaManagedAgentsEffortLow or BetaManagedAgentsEffortMedium or BetaManagedAgentsEffortHigh or 2 more`
1658
1659 How hard Claude works on each turn. Sets `output_config.effort` on every Messages call the session makes.
1660
1661 - `BetaManagedAgentsEffortLow object`
1662
1663 Low effort. Favors latency over reasoning depth.
1664
1665 - `type: "low"`
1666
1667 - `BetaManagedAgentsEffortMedium object`
1668
1669 Medium effort. Balances latency and reasoning depth.
1670
1671 - `type: "medium"`
1672
1673 - `BetaManagedAgentsEffortHigh object`
1674
1675 High effort. Favors reasoning depth.
1676
1677 - `type: "high"`
1678
1679 - `BetaManagedAgentsEffortXhigh object`
1680
1681 Extra-high effort. Not all models accept this level.
1682
1683 - `type: "xhigh"`
1684
1685 - `BetaManagedAgentsEffortMax object`
1686
1687 Maximum effort. Favors reasoning depth over latency.
1688
1689 - `type: "max"`
1690
1691 - `inference_geo: optional string`
1692
1693 Geographic region for model inference. When unset, requests fall through to the workspace's default_inference_geo.
1694
1695 - `speed: optional "standard" or "fast"`
1696
1697 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.
1698
1699 - `"standard"`
1700
1701 - `"fast"`
1702
1703 - `multiagent: BetaManagedAgentsSessionMultiagentCoordinator or null`
1704
1705 Resolved coordinator topology with full agent definitions for each roster member.
1706
1707 - `agents: array of BetaManagedAgentsSessionThreadAgent or BetaManagedAgentsAdvisor`
1708
1709 Full `agent` definitions the coordinator may spawn as session threads.
1710
1711 - `BetaManagedAgentsSessionThreadAgent object`
1712
1713 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`.
1714
1715 - `id: string`
1716
1717 - `description: string or null`
1718
1719 - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition`
1720
1721 - `name: string`
1722
1723 - `type: "url"`
1724
1725 - `url: string`
1726
1727 - `model: BetaManagedAgentsModelConfig`
1728
1729 Model identifier and configuration.
1730
1731 - `name: string`
1732
1733 - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill`
1734
1735 - `BetaManagedAgentsAnthropicSkill object`
1736
1737 A resolved Anthropic-managed skill.
1738
1739 - `skill_id: string`
1740
1741 - `type: "anthropic"`
1742
1743 - `version: string`
1744
1745 - `BetaManagedAgentsCustomSkill object`
1746
1747 A resolved user-created custom skill.
1748
1749 - `skill_id: string`
1750
1751 - `type: "custom"`
1752
1753 - `version: string`
1754
1755 - `system: string or null`
1756
1757 - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool`
1758
1759 - `BetaManagedAgentsAgentToolset20260401 object`
1760
1761 - `configs: array of BetaManagedAgentsAgentToolConfig`
1762
1763 - `BetaManagedAgentsBashToolConfig object`
1764
1765 Configuration for the bash tool.
1766
1767 - `enabled: boolean`
1768
1769 - `name: "bash"`
1770
1771 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
1772
1773 Permission policy for tool execution.
1774
1775 - `BetaManagedAgentsAlwaysAllowPolicy object`
1776
1777 Tool calls are automatically approved without user confirmation.
1778
1779 - `type: "always_allow"`
1780
1781 - `BetaManagedAgentsAlwaysAskPolicy object`
1782
1783 Tool calls require user confirmation before execution.
1784
1785 - `type: "always_ask"`
1786
1787 - `type: "bash"`
1788
1789 - `BetaManagedAgentsEditToolConfig object`
1790
1791 Configuration for the edit tool.
1792
1793 - `enabled: boolean`
1794
1795 - `name: "edit"`
1796
1797 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
1798
1799 Permission policy for tool execution.
1800
1801 - `BetaManagedAgentsAlwaysAllowPolicy object`
1802
1803 Tool calls are automatically approved without user confirmation.
1804
1805 - `BetaManagedAgentsAlwaysAskPolicy object`
1806
1807 Tool calls require user confirmation before execution.
1808
1809 - `type: "edit"`
1810
1811 - `BetaManagedAgentsReadToolConfig object`
1812
1813 Configuration for the read tool.
1814
1815 - `enabled: boolean`
1816
1817 - `name: "read"`
1818
1819 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
1820
1821 Permission policy for tool execution.
1822
1823 - `BetaManagedAgentsAlwaysAllowPolicy object`
1824
1825 Tool calls are automatically approved without user confirmation.
1826
1827 - `BetaManagedAgentsAlwaysAskPolicy object`
1828
1829 Tool calls require user confirmation before execution.
1830
1831 - `type: "read"`
1832
1833 - `BetaManagedAgentsWriteToolConfig object`
1834
1835 Configuration for the write tool.
1836
1837 - `enabled: boolean`
1838
1839 - `name: "write"`
1840
1841 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
1842
1843 Permission policy for tool execution.
1844
1845 - `BetaManagedAgentsAlwaysAllowPolicy object`
1846
1847 Tool calls are automatically approved without user confirmation.
1848
1849 - `BetaManagedAgentsAlwaysAskPolicy object`
1850
1851 Tool calls require user confirmation before execution.
1852
1853 - `type: "write"`
1854
1855 - `BetaManagedAgentsGlobToolConfig object`
1856
1857 Configuration for the glob tool.
1858
1859 - `enabled: boolean`
1860
1861 - `name: "glob"`
1862
1863 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
1864
1865 Permission policy for tool execution.
1866
1867 - `BetaManagedAgentsAlwaysAllowPolicy object`
1868
1869 Tool calls are automatically approved without user confirmation.
1870
1871 - `BetaManagedAgentsAlwaysAskPolicy object`
1872
1873 Tool calls require user confirmation before execution.
1874
1875 - `type: "glob"`
1876
1877 - `BetaManagedAgentsGrepToolConfig object`
1878
1879 Configuration for the grep tool.
1880
1881 - `enabled: boolean`
1882
1883 - `name: "grep"`
1884
1885 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
1886
1887 Permission policy for tool execution.
1888
1889 - `BetaManagedAgentsAlwaysAllowPolicy object`
1890
1891 Tool calls are automatically approved without user confirmation.
1892
1893 - `BetaManagedAgentsAlwaysAskPolicy object`
1894
1895 Tool calls require user confirmation before execution.
1896
1897 - `type: "grep"`
1898
1899 - `BetaManagedAgentsWebFetchToolConfig object`
1900
1901 Configuration for the web_fetch tool.
1902
1903 - `enabled: boolean`
1904
1905 - `name: "web_fetch"`
1906
1907 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
1908
1909 Permission policy for tool execution.
1910
1911 - `BetaManagedAgentsAlwaysAllowPolicy object`
1912
1913 Tool calls are automatically approved without user confirmation.
1914
1915 - `BetaManagedAgentsAlwaysAskPolicy object`
1916
1917 Tool calls require user confirmation before execution.
1918
1919 - `type: "web_fetch"`
1920
1921 - `allowed_domains: optional array of string`
1922
1923 - `blocked_domains: optional array of string`
1924
1925 - `max_content_tokens: optional number or null`
1926
1927 format: int32
1928
1929 - `BetaManagedAgentsWebSearchToolConfig object`
1930
1931 Configuration for the web_search tool.
1932
1933 - `enabled: boolean`
1934
1935 - `name: "web_search"`
1936
1937 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
1938
1939 Permission policy for tool execution.
1940
1941 - `BetaManagedAgentsAlwaysAllowPolicy object`
1942
1943 Tool calls are automatically approved without user confirmation.
1944
1945 - `BetaManagedAgentsAlwaysAskPolicy object`
1946
1947 Tool calls require user confirmation before execution.
1948
1949 - `type: "web_search"`
1950
1951 - `allowed_domains: optional array of string`
1952
1953 - `blocked_domains: optional array of string`
1954
1955 - `user_location: optional BetaManagedAgentsUserLocation or null`
1956
1957 Approximate user location for search result localization.
1958
1959 - `type: "approximate"`
1960
1961 Location precision. Only "approximate" is supported.
1962
1963 - `city: optional string or null`
1964
1965 City name.
1966
1967 minLength: 1, maxLength: 255
1968
1969 - `country: optional string or null`
1970
1971 Two-letter ISO 3166-1 country code, uppercase.
1972
1973 - `region: optional string or null`
1974
1975 Region or state name.
1976
1977 minLength: 1, maxLength: 255
1978
1979 - `timezone: optional string or null`
1980
1981 IANA timezone identifier, e.g. "America/Los_Angeles".
1982
1983 minLength: 1, maxLength: 255
1984
1985 - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig`
1986
1987 Resolved default configuration for agent tools.
1988
1989 - `enabled: boolean`
1990
1991 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
1992
1993 Permission policy for tool execution.
1994
1995 - `BetaManagedAgentsAlwaysAllowPolicy object`
1996
1997 Tool calls are automatically approved without user confirmation.
1998
1999 - `BetaManagedAgentsAlwaysAskPolicy object`
2000
2001 Tool calls require user confirmation before execution.
2002
2003 - `type: "agent_toolset_20260401"`
2004
2005 - `BetaManagedAgentsMCPToolset object`
2006
2007 - `configs: array of BetaManagedAgentsMCPToolConfig`
2008
2009 - `enabled: boolean`
2010
2011 - `name: string`
2012
2013 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
2014
2015 Permission policy for tool execution.
2016
2017 - `BetaManagedAgentsAlwaysAllowPolicy object`
2018
2019 Tool calls are automatically approved without user confirmation.
2020
2021 - `BetaManagedAgentsAlwaysAskPolicy object`
2022
2023 Tool calls require user confirmation before execution.
2024
2025 - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig`
2026
2027 Resolved default configuration for all tools from an MCP server.
2028
2029 - `enabled: boolean`
2030
2031 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
2032
2033 Permission policy for tool execution.
2034
2035 - `BetaManagedAgentsAlwaysAllowPolicy object`
2036
2037 Tool calls are automatically approved without user confirmation.
2038
2039 - `BetaManagedAgentsAlwaysAskPolicy object`
2040
2041 Tool calls require user confirmation before execution.
2042
2043 - `mcp_server_name: string`
2044
2045 - `type: "mcp_toolset"`
2046
2047 - `BetaManagedAgentsCustomTool object`
2048
2049 A custom tool as returned in API responses.
2050
2051 - `description: string`
2052
2053 - `input_schema: BetaManagedAgentsCustomToolInputSchema`
2054
2055 JSON Schema for custom tool input parameters.
2056
2057 - `type: "object"`
2058
2059 - `properties: optional map[unknown] or null`
2060
2061 - `required: optional array of string or null`
2062
2063 - `name: string`
2064
2065 - `type: "custom"`
2066
2067 - `type: "agent"`
2068
2069 - `version: number`
2070
2071 format: int32
2072
2073 - `BetaManagedAgentsAdvisor object`
2074
2075 Platform advisor roster entry: a model the session's primary thread may consult mid-turn.
2076
2077 - `model: string`
2078
2079 The advisor model id.
2080
2081 - `type: "advisor"`
2082
2083 - `type: "coordinator"`
2084
2085 - `name: string`
2086
2087 - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill`
2088
2089 - `BetaManagedAgentsAnthropicSkill object`
2090
2091 A resolved Anthropic-managed skill.
2092
2093 - `BetaManagedAgentsCustomSkill object`
2094
2095 A resolved user-created custom skill.
2096
2097 - `system: string or null`
2098
2099 - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool`
2100
2101 - `BetaManagedAgentsAgentToolset20260401 object`
2102
2103 - `BetaManagedAgentsMCPToolset object`
2104
2105 - `BetaManagedAgentsCustomTool object`
2106
2107 A custom tool as returned in API responses.
2108
2109 - `type: "agent"`
2110
2111 - `version: number`
2112
2113 format: int32
2114
2115 - `budget: optional BetaManagedAgentsBudgetLimit or null`
2116
2117 A hard spend ceiling. The session stops issuing new model requests once the tracked list cost reaches `max_list_cost`.
2118
2119 - `max_list_cost: BetaMonetaryAmount`
2120
2121 A monetary amount in a specific currency.
2122
2123 - `amount: string`
2124
2125 Amount in minor units of the currency, as an integer decimal string with no leading zeros: "2500" is $25.00 and "50" is fifty cents. A string rather than a number so no float rounding is ever applied.
2126
2127 - `currency: BetaCurrency`
2128
2129 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.
2130
2131 - `type: "limit"`
2132
2133 - `metadata: optional map[string]`
2134
2135 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.
2136
2137 - `title: optional string or null`
2138
2139 The session's new title. Present only when the update changed it.
2140
2141 - `BetaManagedAgentsStartEvent object`
2142
2143 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.
2144
2145 - `event: BetaManagedAgentsStartEventPreview`
2146
2147 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.
2148
2149 - `BetaManagedAgentsAgentMessagePreview object`
2150
2151 - `id: string`
2152
2153 The id the buffered agent.message will carry if it is emitted. Matches the event_id on this preview's event_delta events.
2154
2155 - `type: "agent.message"`
2156
2157 - `BetaManagedAgentsAgentThinkingPreview object`
2158
2159 - `id: string`
2160
2161 The id the buffered agent.thinking will carry if it is emitted. Start-only — no event_delta events follow.
2162
2163 - `type: "agent.thinking"`
2164
2165 - `type: "event_start"`
2166
2167 - `BetaManagedAgentsDeltaEvent object`
2168
2169 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.
2170
2171 - `delta: BetaManagedAgentsDeltaContent`
2172
2173 One fragment of the previewed event. The delta type is named for the previewed event's field it streams into: agent.message events stream content_delta fragments, each a partial element of the content array.
2174
2175 - `content: BetaManagedAgentsTextBlock`
2176
2177 Regular text content.
2178
2179 - `type: "content_delta"`
2180
2181 - `index: optional number`
2182
2183 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.
2184
2185 format: uint32
2186
2187 - `event_id: string`
2188
2189 The id of the event being previewed. Matches event.id on the corresponding event_start and the buffered event that reconciles the preview.
2190
2191 - `type: "event_delta"`
2192
2193 - `BetaManagedAgentsSystemMessageEvent object`
2194
2195 A mid-conversation system message event. Carries system-role content that is appended to the session as a `role: "system"` turn.
2196
2197 - `id: string`
2198
2199 Unique identifier for this event.
2200
2201 - `content: array of BetaManagedAgentsSystemContentBlock`
2202
2203 System content blocks. Text-only.
2204
2205 - `text: string`
2206
2207 The text content.
2208
2209 minLength: 1
2210
2211 - `type: "text"`
2212
2213 - `type: "system.message"`
2214
2215 - `processed_at: optional string or null`
2216
2217 A timestamp in RFC 3339 format
2218
2219 format: date-time
2220
22212336 - `BetaManagedAgentsSessionUsageEvent object`
22222337
22232338 Periodic snapshot of the session's cumulative usage and tracked list cost.
22242339
2225 - `id: string`
2226
2227 Unique identifier for this event.
2228
2229 - `processed_at: string`
2230
2231 A timestamp in RFC 3339 format
2232
2233 format: date-time
2234
22352340 - `type: "session.usage"`
2341
2342 - `id: string`
2343
2344 Unique identifier for this event.
2345
2346 - `processed_at: string`
2347
2348 A timestamp in RFC 3339 format
2349
2350 format: date-time
22362351
22372352 - `usage: BetaManagedAgentsSessionUsageSnapshot`
22382353
22392354
api/beta/sessions/threads/list Changed · +366 / -311 lines
from line 1
1---
2title: List Session Threads
3url: https://platform.claude.com/docs/en/api/beta/sessions/threads/list
4---
5
16# List Session Threads
27
38**GET** `/v1/sessions/{session_id}/threads`
from line 33
2833
2934 - `string`
3035
31 - `"message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 41 more`
36 - `"message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 42 more`
3237
3338 - `"message-batches-2024-09-24"`
3439
from line 81
7681
7782 - `"user-profiles-2026-08-18"`
7883
84 - `"user-profiles-2026-09-04"`
85
7986 - `"advisor-tool-2026-03-01"`
8087
8188 - `"managed-agents-2026-04-01"`
from line 125
118125
119126 - `"mid-conversation-system-clear-at-2026-08-21"`
120127
128- `"anthropic-workspace-id": optional string`
129
121130## Returns
122131
123132- `data: optional array of BetaManagedAgentsSessionThread`
from line 133
124133
125134 Threads in the session, primary first then children in spawn order.
126135
136 - `type: "session_thread"`
137
127138 - `id: string`
128139
129140 Unique identifier for this thread.
from line 147
136147
137148 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`.
138149
150 - `type: "agent"`
151
139152 - `id: string`
140153
141154 - `description: string or null`
from line 155
142155
143156 - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition`
144157
145 - `name: string`
146
147158 - `type: "url"`
148159
160 - `name: string`
161
149162 - `url: string`
150163
151164 - `model: BetaManagedAgentsModelConfig`
from line 289
276289
277290 A resolved Anthropic-managed skill.
278291
279 - `skill_id: string`
280
281292 - `type: "anthropic"`
282293
294 - `skill_id: string`
295
283296 - `version: string`
284297
285298 - `BetaManagedAgentsCustomSkill object`
from line 299
286299
287300 A resolved user-created custom skill.
288301
289 - `skill_id: string`
290
291302 - `type: "custom"`
292303
304 - `skill_id: string`
305
293306 - `version: string`
294307
295308 - `system: string or null`
from line 311
298311
299312 - `BetaManagedAgentsAgentToolset20260401 object`
300313
314 - `type: "agent_toolset_20260401"`
315
301316 - `configs: array of BetaManagedAgentsAgentToolConfig`
302317
303318 - `BetaManagedAgentsBashToolConfig object`
from line 319
304319
305320 Configuration for the bash tool.
306321
322 - `type: "bash"`
323
307324 - `enabled: boolean`
308325
309326 - `name: "bash"`
310327
311 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
328 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
312329
313330 Permission policy for tool execution.
314331
from line 341
324341
325342 - `type: "always_ask"`
326343
327 - `type: "bash"`
344 - `BetaManagedAgentsAutoPolicy object`
328345
346 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
347
348 - `type: "auto"`
349
329350 - `BetaManagedAgentsEditToolConfig object`
330351
331352 Configuration for the edit tool.
332353
354 - `type: "edit"`
355
333356 - `enabled: boolean`
334357
335358 - `name: "edit"`
336359
337 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
360 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
338361
339362 Permission policy for tool execution.
340363
from line 369
346369
347370 Tool calls require user confirmation before execution.
348371
349 - `type: "edit"`
372 - `BetaManagedAgentsAutoPolicy object`
350373
374 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
375
351376 - `BetaManagedAgentsReadToolConfig object`
352377
353378 Configuration for the read tool.
354379
380 - `type: "read"`
381
355382 - `enabled: boolean`
356383
357384 - `name: "read"`
358385
359 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
386 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
360387
361388 Permission policy for tool execution.
362389
from line 395
368395
369396 Tool calls require user confirmation before execution.
370397
371 - `type: "read"`
398 - `BetaManagedAgentsAutoPolicy object`
372399
400 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
401
373402 - `BetaManagedAgentsWriteToolConfig object`
374403
375404 Configuration for the write tool.
376405
406 - `type: "write"`
407
377408 - `enabled: boolean`
378409
379410 - `name: "write"`
380411
381 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
412 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
382413
383414 Permission policy for tool execution.
384415
from line 421
390421
391422 Tool calls require user confirmation before execution.
392423
393 - `type: "write"`
424 - `BetaManagedAgentsAutoPolicy object`
394425
426 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
427
395428 - `BetaManagedAgentsGlobToolConfig object`
396429
397430 Configuration for the glob tool.
398431
432 - `type: "glob"`
433
399434 - `enabled: boolean`
400435
401436 - `name: "glob"`
402437
403 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
438 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
404439
405440 Permission policy for tool execution.
406441
from line 447
412447
413448 Tool calls require user confirmation before execution.
414449
415 - `type: "glob"`
450 - `BetaManagedAgentsAutoPolicy object`
416451
452 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
453
417454 - `BetaManagedAgentsGrepToolConfig object`
418455
419456 Configuration for the grep tool.
420457
458 - `type: "grep"`
459
421460 - `enabled: boolean`
422461
423462 - `name: "grep"`
424463
425 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
464 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
426465
427466 Permission policy for tool execution.
428467
from line 473
434473
435474 Tool calls require user confirmation before execution.
436475
437 - `type: "grep"`
476 - `BetaManagedAgentsAutoPolicy object`
438477
478 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
479
439480 - `BetaManagedAgentsWebFetchToolConfig object`
440481
441482 Configuration for the web_fetch tool.
442483
484 - `type: "web_fetch"`
485
443486 - `enabled: boolean`
444487
445488 - `name: "web_fetch"`
446489
447 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
490 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
448491
449492 Permission policy for tool execution.
450493
from line 499
456499
457500 Tool calls require user confirmation before execution.
458501
459 - `type: "web_fetch"`
502 - `BetaManagedAgentsAutoPolicy object`
460503
504 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
505
461506 - `allowed_domains: optional array of string`
462507
463508 - `blocked_domains: optional array of string`
from line 515
470515
471516 Configuration for the web_search tool.
472517
518 - `type: "web_search"`
519
473520 - `enabled: boolean`
474521
475522 - `name: "web_search"`
476523
477 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
524 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
478525
479526 Permission policy for tool execution.
480527
from line 533
486533
487534 Tool calls require user confirmation before execution.
488535
489 - `type: "web_search"`
536 - `BetaManagedAgentsAutoPolicy object`
490537
538 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
539
491540 - `allowed_domains: optional array of string`
492541
493542 - `blocked_domains: optional array of string`
from line 577
528577
529578 - `enabled: boolean`
530579
531 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
580 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
532581
533582 Permission policy for tool execution.
534583
from line 589
540589
541590 Tool calls require user confirmation before execution.
542591
543 - `type: "agent_toolset_20260401"`
592 - `BetaManagedAgentsAutoPolicy object`
544593
594 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
595
545596 - `BetaManagedAgentsMCPToolset object`
546597
598 - `type: "mcp_toolset"`
599
547600 - `configs: array of BetaManagedAgentsMCPToolConfig`
548601
549602 - `enabled: boolean`
from line 603
550603
551604 - `name: string`
552605
553 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
606 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
554607
555608 Permission policy for tool execution.
556609
from line 615
562615
563616 Tool calls require user confirmation before execution.
564617
618 - `BetaManagedAgentsAutoPolicy object`
619
620 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
621
565622 - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig`
566623
567624 Resolved default configuration for all tools from an MCP server.
from line 625
568625
569626 - `enabled: boolean`
570627
571 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
628 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
572629
573630 Permission policy for tool execution.
574631
from line 637
580637
581638 Tool calls require user confirmation before execution.
582639
583 - `mcp_server_name: string`
640 - `BetaManagedAgentsAutoPolicy object`
584641
585 - `type: "mcp_toolset"`
642 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
586643
644 - `mcp_server_name: string`
645
587646 - `BetaManagedAgentsCustomTool object`
588647
589648 A custom tool as returned in API responses.
590649
650 - `type: "custom"`
651
591652 - `description: string`
592653
593654 - `input_schema: BetaManagedAgentsCustomToolInputSchema`
from line 663
602663
603664 - `name: string`
604665
605 - `type: "custom"`
606
607 - `type: "agent"`
608
609666 - `version: number`
610667
611668 format: int32
from line 671
614671
615672 Platform advisor roster entry: a model the session's primary thread may consult mid-turn.
616673
674 - `type: "advisor"`
675
617676 - `model: string`
618677
619678 The advisor model id.
620679
621 - `type: "advisor"`
622
623680 - `archived_at: string or null`
624681
625682 A timestamp in RFC 3339 format
from line 730
673730 - `"rescheduling"`
674731
675732 - `"terminated"`
676
677 - `type: "session_thread"`
678733
679734 - `updated_at: string`
680735
api/beta/sessions/threads/retrieve Changed · +366 / -311 lines
from line 1
1---
2title: Get Session Thread
3url: https://platform.claude.com/docs/en/api/beta/sessions/threads/retrieve
4---
5
16# Get Session Thread
27
38**GET** `/v1/sessions/{session_id}/threads/{thread_id}`
from line 23
1823
1924 - `string`
2025
21 - `"message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 41 more`
26 - `"message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 42 more`
2227
2328 - `"message-batches-2024-09-24"`
2429
from line 71
6671
6772 - `"user-profiles-2026-08-18"`
6873
74 - `"user-profiles-2026-09-04"`
75
6976 - `"advisor-tool-2026-03-01"`
7077
7178 - `"managed-agents-2026-04-01"`
from line 115
108115
109116 - `"mid-conversation-system-clear-at-2026-08-21"`
110117
118- `"anthropic-workspace-id": optional string`
119
111120## Returns
112121
113122- `BetaManagedAgentsSessionThread object`
from line 123
114123
115124 An execution thread within a `session`. Each session has one primary thread plus zero or more child threads spawned by the coordinator.
116125
126 - `type: "session_thread"`
127
117128 - `id: string`
118129
119130 Unique identifier for this thread.
from line 137
126137
127138 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`.
128139
140 - `type: "agent"`
141
129142 - `id: string`
130143
131144 - `description: string or null`
from line 145
132145
133146 - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition`
134147
135 - `name: string`
136
137148 - `type: "url"`
138149
150 - `name: string`
151
139152 - `url: string`
140153
141154 - `model: BetaManagedAgentsModelConfig`
from line 279
266279
267280 A resolved Anthropic-managed skill.
268281
269 - `skill_id: string`
270
271282 - `type: "anthropic"`
272283
284 - `skill_id: string`
285
273286 - `version: string`
274287
275288 - `BetaManagedAgentsCustomSkill object`
from line 289
276289
277290 A resolved user-created custom skill.
278291
279 - `skill_id: string`
280
281292 - `type: "custom"`
282293
294 - `skill_id: string`
295
283296 - `version: string`
284297
285298 - `system: string or null`
from line 301
288301
289302 - `BetaManagedAgentsAgentToolset20260401 object`
290303
304 - `type: "agent_toolset_20260401"`
305
291306 - `configs: array of BetaManagedAgentsAgentToolConfig`
292307
293308 - `BetaManagedAgentsBashToolConfig object`
from line 309
294309
295310 Configuration for the bash tool.
296311
312 - `type: "bash"`
313
297314 - `enabled: boolean`
298315
299316 - `name: "bash"`
300317
301 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
318 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
302319
303320 Permission policy for tool execution.
304321
from line 331
314331
315332 - `type: "always_ask"`
316333
317 - `type: "bash"`
334 - `BetaManagedAgentsAutoPolicy object`
318335
336 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
337
338 - `type: "auto"`
339
319340 - `BetaManagedAgentsEditToolConfig object`
320341
321342 Configuration for the edit tool.
322343
344 - `type: "edit"`
345
323346 - `enabled: boolean`
324347
325348 - `name: "edit"`
326349
327 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
350 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
328351
329352 Permission policy for tool execution.
330353
from line 359
336359
337360 Tool calls require user confirmation before execution.
338361
339 - `type: "edit"`
362 - `BetaManagedAgentsAutoPolicy object`
340363
364 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
365
341366 - `BetaManagedAgentsReadToolConfig object`
342367
343368 Configuration for the read tool.
344369
370 - `type: "read"`
371
345372 - `enabled: boolean`
346373
347374 - `name: "read"`
348375
349 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
376 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
350377
351378 Permission policy for tool execution.
352379
from line 385
358385
359386 Tool calls require user confirmation before execution.
360387
361 - `type: "read"`
388 - `BetaManagedAgentsAutoPolicy object`
362389
390 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
391
363392 - `BetaManagedAgentsWriteToolConfig object`
364393
365394 Configuration for the write tool.
366395
396 - `type: "write"`
397
367398 - `enabled: boolean`
368399
369400 - `name: "write"`
370401
371 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
402 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
372403
373404 Permission policy for tool execution.
374405
from line 411
380411
381412 Tool calls require user confirmation before execution.
382413
383 - `type: "write"`
414 - `BetaManagedAgentsAutoPolicy object`
384415
416 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
417
385418 - `BetaManagedAgentsGlobToolConfig object`
386419
387420 Configuration for the glob tool.
388421
422 - `type: "glob"`
423
389424 - `enabled: boolean`
390425
391426 - `name: "glob"`
392427
393 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
428 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
394429
395430 Permission policy for tool execution.
396431
from line 437
402437
403438 Tool calls require user confirmation before execution.
404439
405 - `type: "glob"`
440 - `BetaManagedAgentsAutoPolicy object`
406441
442 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
443
407444 - `BetaManagedAgentsGrepToolConfig object`
408445
409446 Configuration for the grep tool.
410447
448 - `type: "grep"`
449
411450 - `enabled: boolean`
412451
413452 - `name: "grep"`
414453
415 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
454 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
416455
417456 Permission policy for tool execution.
418457
from line 463
424463
425464 Tool calls require user confirmation before execution.
426465
427 - `type: "grep"`
466 - `BetaManagedAgentsAutoPolicy object`
428467
468 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
469
429470 - `BetaManagedAgentsWebFetchToolConfig object`
430471
431472 Configuration for the web_fetch tool.
432473
474 - `type: "web_fetch"`
475
433476 - `enabled: boolean`
434477
435478 - `name: "web_fetch"`
436479
437 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
480 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
438481
439482 Permission policy for tool execution.
440483
from line 489
446489
447490 Tool calls require user confirmation before execution.
448491
449 - `type: "web_fetch"`
492 - `BetaManagedAgentsAutoPolicy object`
450493
494 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
495
451496 - `allowed_domains: optional array of string`
452497
453498 - `blocked_domains: optional array of string`
from line 505
460505
461506 Configuration for the web_search tool.
462507
508 - `type: "web_search"`
509
463510 - `enabled: boolean`
464511
465512 - `name: "web_search"`
466513
467 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
514 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
468515
469516 Permission policy for tool execution.
470517
from line 523
476523
477524 Tool calls require user confirmation before execution.
478525
479 - `type: "web_search"`
526 - `BetaManagedAgentsAutoPolicy object`
480527
528 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
529
481530 - `allowed_domains: optional array of string`
482531
483532 - `blocked_domains: optional array of string`
from line 567
518567
519568 - `enabled: boolean`
520569
521 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
570 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
522571
523572 Permission policy for tool execution.
524573
from line 579
530579
531580 Tool calls require user confirmation before execution.
532581
533 - `type: "agent_toolset_20260401"`
582 - `BetaManagedAgentsAutoPolicy object`
534583
584 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
585
535586 - `BetaManagedAgentsMCPToolset object`
536587
588 - `type: "mcp_toolset"`
589
537590 - `configs: array of BetaManagedAgentsMCPToolConfig`
538591
539592 - `enabled: boolean`
from line 593
540593
541594 - `name: string`
542595
543 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
596 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
544597
545598 Permission policy for tool execution.
546599
from line 605
552605
553606 Tool calls require user confirmation before execution.
554607
608 - `BetaManagedAgentsAutoPolicy object`
609
610 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
611
555612 - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig`
556613
557614 Resolved default configuration for all tools from an MCP server.
from line 615
558615
559616 - `enabled: boolean`
560617
561 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
618 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
562619
563620 Permission policy for tool execution.
564621
from line 627
570627
571628 Tool calls require user confirmation before execution.
572629
573 - `mcp_server_name: string`
630 - `BetaManagedAgentsAutoPolicy object`
574631
575 - `type: "mcp_toolset"`
632 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
576633
634 - `mcp_server_name: string`
635
577636 - `BetaManagedAgentsCustomTool object`
578637
579638 A custom tool as returned in API responses.
580639
640 - `type: "custom"`
641
581642 - `description: string`
582643
583644 - `input_schema: BetaManagedAgentsCustomToolInputSchema`
from line 653
592653
593654 - `name: string`
594655
595 - `type: "custom"`
596
597 - `type: "agent"`
598
599656 - `version: number`
600657
601658 format: int32
from line 661
604661
605662 Platform advisor roster entry: a model the session's primary thread may consult mid-turn.
606663
664 - `type: "advisor"`
665
607666 - `model: string`
608667
609668 The advisor model id.
610669
611 - `type: "advisor"`
612
613670 - `archived_at: string or null`
614671
615672 A timestamp in RFC 3339 format
from line 720
663720 - `"rescheduling"`
664721
665722 - `"terminated"`
666
667 - `type: "session_thread"`
668723
669724 - `updated_at: string`
670725
api/beta/sessions/update Changed · +459 / -358 lines
from line 1
1---
2title: Update Session
3url: https://platform.claude.com/docs/en/api/beta/sessions/update
4---
5
16# Update Session
27
38**POST** `/v1/sessions/{session_id}`
from line 21
1621
1722 - `string`
1823
19 - `"message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 41 more`
24 - `"message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 42 more`
2025
2126 - `"message-batches-2024-09-24"`
2227
from line 69
6469
6570 - `"user-profiles-2026-08-18"`
6671
72 - `"user-profiles-2026-09-04"`
73
6774 - `"advisor-tool-2026-03-01"`
6875
6976 - `"managed-agents-2026-04-01"`
from line 113
106113
107114 - `"mid-conversation-system-clear-at-2026-08-21"`
108115
116- `"anthropic-workspace-id": optional string`
117
109118## Body parameters
110119
111120- `agent: optional BetaManagedAgentsSessionAgentUpdate`
from line 125
116125
117126 Replacement MCP server list. Full replacement: the provided array becomes the new value. Send an empty array to clear; omit to preserve.
118127
128 - `type: "url"`
129
119130 - `name: string`
120131
121132 Unique name for this server, referenced by mcp_toolset configurations. 1-255 characters.
from line 133
122133
123134 minLength: 1, maxLength: 255
124135
125 - `type: "url"`
126
127136 - `url: string`
128137
129138 Endpoint URL for the MCP server.
from line 157
148157
149158 Configuration override for the bash tool.
150159
160 - `type: optional "bash"`
161
151162 - `name: "bash"`
152163
153164 Must be "bash".
from line 167
156167
157168 Whether this tool is enabled and available to Claude. Overrides the default_config setting.
158169
159 - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or null`
170 - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null`
160171
161172 Permission policy for tool execution.
162173
from line 183
172183
173184 - `type: "always_ask"`
174185
175 - `type: optional "bash"`
186 - `BetaManagedAgentsAutoPolicy object`
176187
188 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
189
190 - `type: "auto"`
191
177192 - `BetaManagedAgentsEditToolConfigParams object`
178193
179194 Configuration override for the edit tool.
180195
196 - `type: optional "edit"`
197
181198 - `name: "edit"`
182199
183200 Must be "edit".
from line 203
186203
187204 Whether this tool is enabled and available to Claude. Overrides the default_config setting.
188205
189 - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or null`
206 - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null`
190207
191208 Permission policy for tool execution.
192209
from line 215
198215
199216 Tool calls require user confirmation before execution.
200217
201 - `type: optional "edit"`
218 - `BetaManagedAgentsAutoPolicy object`
202219
220 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
221
203222 - `BetaManagedAgentsReadToolConfigParams object`
204223
205224 Configuration override for the read tool.
206225
226 - `type: optional "read"`
227
207228 - `name: "read"`
208229
209230 Must be "read".
from line 233
212233
213234 Whether this tool is enabled and available to Claude. Overrides the default_config setting.
214235
215 - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or null`
236 - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null`
216237
217238 Permission policy for tool execution.
218239
from line 245
224245
225246 Tool calls require user confirmation before execution.
226247
227 - `type: optional "read"`
248 - `BetaManagedAgentsAutoPolicy object`
228249
250 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
251
229252 - `BetaManagedAgentsWriteToolConfigParams object`
230253
231254 Configuration override for the write tool.
232255
256 - `type: optional "write"`
257
233258 - `name: "write"`
234259
235260 Must be "write".
from line 263
238263
239264 Whether this tool is enabled and available to Claude. Overrides the default_config setting.
240265
241 - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or null`
266 - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null`
242267
243268 Permission policy for tool execution.
244269
from line 275
250275
251276 Tool calls require user confirmation before execution.
252277
253 - `type: optional "write"`
278 - `BetaManagedAgentsAutoPolicy object`
254279
280 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
281
255282 - `BetaManagedAgentsGlobToolConfigParams object`
256283
257284 Configuration override for the glob tool.
258285
286 - `type: optional "glob"`
287
259288 - `name: "glob"`
260289
261290 Must be "glob".
from line 293
264293
265294 Whether this tool is enabled and available to Claude. Overrides the default_config setting.
266295
267 - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or null`
296 - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null`
268297
269298 Permission policy for tool execution.
270299
from line 305
276305
277306 Tool calls require user confirmation before execution.
278307
279 - `type: optional "glob"`
308 - `BetaManagedAgentsAutoPolicy object`
280309
310 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
311
281312 - `BetaManagedAgentsGrepToolConfigParams object`
282313
283314 Configuration override for the grep tool.
284315
316 - `type: optional "grep"`
317
285318 - `name: "grep"`
286319
287320 Must be "grep".
from line 323
290323
291324 Whether this tool is enabled and available to Claude. Overrides the default_config setting.
292325
293 - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or null`
326 - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null`
294327
295328 Permission policy for tool execution.
296329
from line 335
302335
303336 Tool calls require user confirmation before execution.
304337
305 - `type: optional "grep"`
338 - `BetaManagedAgentsAutoPolicy object`
306339
340 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
341
307342 - `BetaManagedAgentsWebFetchToolConfigParams object`
308343
309344 Configuration override for the web_fetch tool.
310345
346 - `type: optional "web_fetch"`
347
311348 - `name: "web_fetch"`
312349
313350 Must be "web_fetch".
from line 367
330367
331368 format: int32
332369
333 - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or null`
370 - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null`
334371
335372 Permission policy for tool execution.
336373
from line 379
342379
343380 Tool calls require user confirmation before execution.
344381
345 - `type: optional "web_fetch"`
382 - `BetaManagedAgentsAutoPolicy object`
346383
384 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
385
347386 - `BetaManagedAgentsWebSearchToolConfigParams object`
348387
349388 Configuration override for the web_search tool.
350389
390 - `type: optional "web_search"`
391
351392 - `name: "web_search"`
352393
353394 Must be "web_search".
from line 405
364405
365406 Whether this tool is enabled and available to Claude. Overrides the default_config setting.
366407
367 - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or null`
408 - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null`
368409
369410 Permission policy for tool execution.
370411
from line 417
376417
377418 Tool calls require user confirmation before execution.
378419
379 - `type: optional "web_search"`
420 - `BetaManagedAgentsAutoPolicy object`
380421
422 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
423
381424 - `user_location: optional BetaManagedAgentsUserLocation or null`
382425
383426 Approximate user location for search result localization.
from line 459
416459
417460 Whether tools are enabled and available to Claude by default. Defaults to true if not specified.
418461
419 - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or null`
462 - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null`
420463
421464 Permission policy for tool execution.
422465
from line 471
428471
429472 Tool calls require user confirmation before execution.
430473
474 - `BetaManagedAgentsAutoPolicy object`
475
476 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
477
431478 - `BetaManagedAgentsMCPToolsetParams object`
432479
433480 Configuration for tools from an MCP server defined in `mcp_servers`.
434481
482 - `type: "mcp_toolset"`
483
435484 - `mcp_server_name: string`
436485
437486 Name of the MCP server. Must match a server name from the mcp_servers array. 1-255 characters.
from line 487
438487
439488 minLength: 1, maxLength: 255
440489
441 - `type: "mcp_toolset"`
442
443490 - `configs: optional array of BetaManagedAgentsMCPToolConfigParams`
444491
445492 Per-tool configuration overrides.
from line 501
454501
455502 Whether this tool is enabled. Overrides the `default_config` setting.
456503
457 - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or null`
504 - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null`
458505
459506 Permission policy for tool execution.
460507
from line 513
466513
467514 Tool calls require user confirmation before execution.
468515
516 - `BetaManagedAgentsAutoPolicy object`
517
518 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
519
469520 - `default_config: optional BetaManagedAgentsMCPToolsetDefaultConfigParams or null`
470521
471522 Default configuration for all tools from an MCP server.
from line 525
474525
475526 Whether tools are enabled by default. Defaults to true if not specified.
476527
477 - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or null`
528 - `permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or null`
478529
479530 Permission policy for tool execution.
480531
from line 537
486537
487538 Tool calls require user confirmation before execution.
488539
540 - `BetaManagedAgentsAutoPolicy object`
541
542 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
543
489544 - `BetaManagedAgentsCustomToolParams object`
490545
491546 A custom tool that is executed by the API client rather than the agent. When the agent calls this tool, an `agent.custom_tool_use` event is emitted and the session goes idle, waiting for the client to provide the result via a `user.custom_tool_result` event.
492547
548 - `type: "custom"`
549
493550 - `description: string`
494551
495552 Description of what the tool does, shown to the agent to help it decide when to use the tool.
from line 569
512569
513570 minLength: 1, maxLength: 128
514571
515 - `type: "custom"`
516
517572- `budget: optional BetaManagedAgentsBudgetLimit or null`
518573
519574 A hard spend ceiling. The session stops issuing new model requests once the tracked list cost reaches `max_list_cost`.
520575
576 - `type: "limit"`
577
521578 - `max_list_cost: BetaMonetaryAmount`
522579
523580 A monetary amount in a specific currency.
from line 587
530587
531588 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.
532589
533 - `type: "limit"`
534
535590- `metadata: optional map[string] or null`
536591
537592 Metadata patch. Set a key to a string to upsert it, or to null to delete it. Omit the field to preserve.
from line 607
552607
553608 A Managed Agents `session`.
554609
610 - `type: "session"`
611
555612 - `id: string`
556613
557614 - `agent: BetaManagedAgentsSessionAgent`
from line 615
558615
559616 Resolved `agent` definition for a `session`. Snapshot of the `agent` at `session` creation time.
560617
618 - `type: "agent"`
619
561620 - `id: string`
562621
563622 - `description: string or null`
from line 623
564623
565624 - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition`
566625
567 - `name: string`
568
569626 - `type: "url"`
570627
628 - `name: string`
629
571630 - `url: string`
572631
573632 - `model: BetaManagedAgentsModelConfig`
from line 753
694753
695754 Resolved coordinator topology with full agent definitions for each roster member.
696755
756 - `type: "coordinator"`
757
697758 - `agents: array of BetaManagedAgentsSessionThreadAgent or BetaManagedAgentsAdvisor`
698759
699760 Full `agent` definitions the coordinator may spawn as session threads.
from line 763
702763
703764 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`.
704765
766 - `type: "agent"`
767
705768 - `id: string`
706769
707770 - `description: string or null`
from line 771
708771
709772 - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition`
710773
711 - `name: string`
712
713774 - `type: "url"`
714775
776 - `name: string`
777
715778 - `url: string`
716779
717780 - `model: BetaManagedAgentsModelConfig`
from line 789
726789
727790 A resolved Anthropic-managed skill.
728791
729 - `skill_id: string`
730
731792 - `type: "anthropic"`
732793
794 - `skill_id: string`
795
733796 - `version: string`
734797
735798 - `BetaManagedAgentsCustomSkill object`
from line 799
736799
737800 A resolved user-created custom skill.
738801
739 - `skill_id: string`
740
741802 - `type: "custom"`
742803
804 - `skill_id: string`
805
743806 - `version: string`
744807
745808 - `system: string or null`
from line 811
748811
749812 - `BetaManagedAgentsAgentToolset20260401 object`
750813
814 - `type: "agent_toolset_20260401"`
815
751816 - `configs: array of BetaManagedAgentsAgentToolConfig`
752817
753818 - `BetaManagedAgentsBashToolConfig object`
from line 819
754819
755820 Configuration for the bash tool.
756821
822 - `type: "bash"`
823
757824 - `enabled: boolean`
758825
759826 - `name: "bash"`
760827
761 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
828 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
762829
763830 Permission policy for tool execution.
764831
from line 841
774841
775842 - `type: "always_ask"`
776843
777 - `type: "bash"`
844 - `BetaManagedAgentsAutoPolicy object`
778845
846 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
847
848 - `type: "auto"`
849
779850 - `BetaManagedAgentsEditToolConfig object`
780851
781852 Configuration for the edit tool.
782853
854 - `type: "edit"`
855
783856 - `enabled: boolean`
784857
785858 - `name: "edit"`
786859
787 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
860 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
788861
789862 Permission policy for tool execution.
790863
from line 869
796869
797870 Tool calls require user confirmation before execution.
798871
799 - `type: "edit"`
872 - `BetaManagedAgentsAutoPolicy object`
800873
874 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
875
801876 - `BetaManagedAgentsReadToolConfig object`
802877
803878 Configuration for the read tool.
804879
880 - `type: "read"`
881
805882 - `enabled: boolean`
806883
807884 - `name: "read"`
808885
809 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
886 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
810887
811888 Permission policy for tool execution.
812889
from line 895
818895
819896 Tool calls require user confirmation before execution.
820897
821 - `type: "read"`
898 - `BetaManagedAgentsAutoPolicy object`
822899
900 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
901
823902 - `BetaManagedAgentsWriteToolConfig object`
824903
825904 Configuration for the write tool.
826905
906 - `type: "write"`
907
827908 - `enabled: boolean`
828909
829910 - `name: "write"`
830911
831 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
912 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
832913
833914 Permission policy for tool execution.
834915
from line 921
840921
841922 Tool calls require user confirmation before execution.
842923
843 - `type: "write"`
924 - `BetaManagedAgentsAutoPolicy object`
844925
926 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
927
845928 - `BetaManagedAgentsGlobToolConfig object`
846929
847930 Configuration for the glob tool.
848931
932 - `type: "glob"`
933
849934 - `enabled: boolean`
850935
851936 - `name: "glob"`
852937
853 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
938 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
854939
855940 Permission policy for tool execution.
856941
from line 947
862947
863948 Tool calls require user confirmation before execution.
864949
865 - `type: "glob"`
950 - `BetaManagedAgentsAutoPolicy object`
866951
952 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
953
867954 - `BetaManagedAgentsGrepToolConfig object`
868955
869956 Configuration for the grep tool.
870957
958 - `type: "grep"`
959
871960 - `enabled: boolean`
872961
873962 - `name: "grep"`
874963
875 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
964 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
876965
877966 Permission policy for tool execution.
878967
from line 973
884973
885974 Tool calls require user confirmation before execution.
886975
887 - `type: "grep"`
976 - `BetaManagedAgentsAutoPolicy object`
888977
978 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
979
889980 - `BetaManagedAgentsWebFetchToolConfig object`
890981
891982 Configuration for the web_fetch tool.
892983
984 - `type: "web_fetch"`
985
893986 - `enabled: boolean`
894987
895988 - `name: "web_fetch"`
896989
897 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
990 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
898991
899992 Permission policy for tool execution.
900993
from line 999
906999
9071000 Tool calls require user confirmation before execution.
9081001
909 - `type: "web_fetch"`
1002 - `BetaManagedAgentsAutoPolicy object`
9101003
1004 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
1005
9111006 - `allowed_domains: optional array of string`
9121007
9131008 - `blocked_domains: optional array of string`
from line 1015
9201015
9211016 Configuration for the web_search tool.
9221017
1018 - `type: "web_search"`
1019
9231020 - `enabled: boolean`
9241021
9251022 - `name: "web_search"`
9261023
927 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
1024 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
9281025
9291026 Permission policy for tool execution.
9301027
from line 1033
9361033
9371034 Tool calls require user confirmation before execution.
9381035
939 - `type: "web_search"`
1036 - `BetaManagedAgentsAutoPolicy object`
9401037
1038 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
1039
9411040 - `allowed_domains: optional array of string`
9421041
9431042 - `blocked_domains: optional array of string`
from line 1077
9781077
9791078 - `enabled: boolean`
9801079
981 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
1080 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
9821081
9831082 Permission policy for tool execution.
9841083
from line 1089
9901089
9911090 Tool calls require user confirmation before execution.
9921091
993 - `type: "agent_toolset_20260401"`
1092 - `BetaManagedAgentsAutoPolicy object`
9941093
1094 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
1095
9951096 - `BetaManagedAgentsMCPToolset object`
9961097
1098 - `type: "mcp_toolset"`
1099
9971100 - `configs: array of BetaManagedAgentsMCPToolConfig`
9981101
9991102 - `enabled: boolean`
from line 1103
10001103
10011104 - `name: string`
10021105
1003 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
1106 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
10041107
10051108 Permission policy for tool execution.
10061109
from line 1115
10121115
10131116 Tool calls require user confirmation before execution.
10141117
1118 - `BetaManagedAgentsAutoPolicy object`
1119
1120 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
1121
10151122 - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig`
10161123
10171124 Resolved default configuration for all tools from an MCP server.
from line 1125
10181125
10191126 - `enabled: boolean`
10201127
1021 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy`
1128 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
10221129
10231130 Permission policy for tool execution.
10241131
from line 1137
10301137
10311138 Tool calls require user confirmation before execution.
10321139
1033 - `mcp_server_name: string`
1140 - `BetaManagedAgentsAutoPolicy object`
10341141
1035 - `type: "mcp_toolset"`
1142 The server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
10361143
1144 - `mcp_server_name: string`
1145
10371146 - `BetaManagedAgentsCustomTool object`
10381147
10391148 A custom tool as returned in API responses.
10401149
1150 - `type: "custom"`
1151
10411152 - `description: string`
10421153
10431154 - `input_schema: BetaManagedAgentsCustomToolInputSchema`
from line 1163
10521163
10531164 - `name: string`
10541165
1055 - `type: "custom"`
1056
1057 - `type: "agent"`
1058
10591166 - `version: number`
10601167
10611168 format: int32
from line 1171
10641171
10651172 Platform advisor roster entry: a model the session's primary thread may consult mid-turn.
10661173
1174 - `type: "advisor"`
1175
10671176 - `model: string`
10681177
10691178 The advisor model id.
10701179
1071 - `type: "advisor"`
1072
1073 - `type: "coordinator"`
1074
10751180 - `name: string`
10761181
10771182 - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill`
from line 1201
10961201
10971202 A custom tool as returned in API responses.
10981203
1099 - `type: "agent"`
1100
11011204 - `version: number`
11021205
11031206 format: int32
from line 1215
11121215
11131216 A hard spend ceiling. The session stops issuing new model requests once the tracked list cost reaches `max_list_cost`.
11141217
1218 - `type: "limit"`
1219
11151220 - `max_list_cost: BetaMonetaryAmount`
11161221
11171222 A monetary amount in a specific currency.
from line 1229
11241229
11251230 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.
11261231
1127 - `type: "limit"`
1128
11291232 - `created_at: string`
11301233
11311234 A timestamp in RFC 3339 format
from line 1243
11401243
11411244 Per-outcome evaluation state. One entry per `define_outcome` event sent to the session.
11421245
1246 - `type: "outcome_evaluation"`
1247
11431248 - `completed_at: string or null`
11441249
11451250 A timestamp in RFC 3339 format
from line 1273
11681273
11691274 Current evaluation state. `pending` before the agent begins work; `running` while producing or revising; `evaluating` while the grader scores; `satisfied`/`max_iterations_reached`/`failed`/`interrupted` are terminal.
11701275
1171 - `type: "outcome_evaluation"`
1172
11731276 - `resources: array of BetaManagedAgentsSessionResource`
11741277
11751278 - `BetaManagedAgentsGitHubRepositoryResource object`
11761279
1280 - `type: "github_repository"`
1281
11771282 - `id: string`
11781283
11791284 - `created_at: string`
from line 1289
11841289
11851290 - `mount_path: string`
11861291
1187 - `type: "github_repository"`
1188
11891292 - `updated_at: string`
11901293
11911294 A timestamp in RFC 3339 format
from line 1301
11981301
11991302 - `BetaManagedAgentsBranchCheckout object`
12001303
1304 - `type: "branch"`
1305
12011306 - `name: string`
12021307
12031308 Branch name to check out.
from line 1309
12041309
12051310 minLength: 1, maxLength: 255
12061311
1207 - `type: "branch"`
1208
12091312 - `BetaManagedAgentsCommitCheckout object`
12101313
1314 - `type: "commit"`
1315
12111316 - `sha: string`
12121317
12131318 Full commit SHA to check out.
from line 1319
12141319
12151320 minLength: 7, maxLength: 64
12161321
1217 - `type: "commit"`
1218
12191322 - `BetaManagedAgentsFileResource object`
12201323
1324 - `type: "file"`
1325
12211326 - `id: string`
12221327
12231328 - `created_at: string`
from line 1335
12301335
12311336 - `mount_path: string`
12321337
1233 - `type: "file"`
1234
12351338 - `updated_at: string`
12361339
12371340 A timestamp in RFC 3339 format
from line 1345
12421345
12431346 A memory store attached to an agent session.
12441347
1348 - `type: "memory_store"`
1349
12451350 - `memory_store_id: string`
12461351
12471352 The memory store ID (memstore_...). Must belong to the caller's organization and workspace.
12481353
1249 - `type: "memory_store"`
1250
12511354 - `access: optional "read_write" or "read_only" or null`
12521355
12531356 Access mode for an attached memory store.
from line 1406
13031406 - `"terminated"`
13041407
13051408 - `title: string or null`
1306
1307 - `type: "session"`
13081409
13091410 - `updated_at: string`
13101411
api/beta/skills Changed · +130 / -89 lines
from line 1
1---
2title: Skills
3url: https://platform.claude.com/docs/en/api/beta/skills
4---
5
16# Skills
27
38## Create Skill
from line 19
1419
1520 - `string`
1621
17 - `"message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 41 more`
22 - `"message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 42 more`
1823
1924 - `"message-batches-2024-09-24"`
2025
from line 67
6267
6368 - `"user-profiles-2026-08-18"`
6469
70 - `"user-profiles-2026-09-04"`
71
6572 - `"advisor-tool-2026-03-01"`
6673
6774 - `"managed-agents-2026-04-01"`
from line 111
104111
105112 - `"mid-conversation-system-clear-at-2026-08-21"`
106113
114- `"anthropic-workspace-id": optional string`
115
107116### Body parameters (form-data)
108117
109118- `files: array of string`
from line 131
122131
123132- `BetaSkill object`
124133
134 - `type: "skill"`
135
136 Object type.
137
138 For Skills, this is always `"skill"`.
139
140 default: skill
141
125142 - `id: string`
126143
127144 Unique identifier for the skill.
from line 191
174191
175192 - `"plugin"`
176193
177 - `type: "skill"`
178
179 Object type.
180
181 For Skills, this is always `"skill"`.
182
183 default: skill
184
185194 - `updated_at: string`
186195
187196 ISO 8601 timestamp of when the skill was last updated.
from line 262
253262
254263 - `string`
255264
256 - `"message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 41 more`
265 - `"message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 42 more`
257266
258267 - `"message-batches-2024-09-24"`
259268
from line 310
301310
302311 - `"user-profiles-2026-08-18"`
303312
313 - `"user-profiles-2026-09-04"`
314
304315 - `"advisor-tool-2026-03-01"`
305316
306317 - `"managed-agents-2026-04-01"`
from line 354
343354
344355 - `"mid-conversation-system-clear-at-2026-08-21"`
345356
357- `"anthropic-workspace-id": optional string`
358
346359### Returns
347360
348361- `data: array of BetaSkill`
from line 362
349362
350363 List of skills.
351364
365 - `type: "skill"`
366
367 Object type.
368
369 For Skills, this is always `"skill"`.
370
371 default: skill
372
352373 - `id: string`
353374
354375 Unique identifier for the skill.
from line 422
401422
402423 - `"plugin"`
403424
404 - `type: "skill"`
405
406 Object type.
407
408 For Skills, this is always `"skill"`.
409
410 default: skill
411
412425 - `updated_at: string`
413426
414427 ISO 8601 timestamp of when the skill was last updated.
from line 485
472485
473486 - `string`
474487
475 - `"message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 41 more`
488 - `"message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 42 more`
476489
477490 - `"message-batches-2024-09-24"`
478491
from line 533
520533
521534 - `"user-profiles-2026-08-18"`
522535
536 - `"user-profiles-2026-09-04"`
537
523538 - `"advisor-tool-2026-03-01"`
524539
525540 - `"managed-agents-2026-04-01"`
from line 577
562577
563578 - `"mid-conversation-system-clear-at-2026-08-21"`
564579
580- `"anthropic-workspace-id": optional string`
581
565582### Returns
566583
567584- `BetaSkill object`
568585
586 - `type: "skill"`
587
588 Object type.
589
590 For Skills, this is always `"skill"`.
591
592 default: skill
593
569594 - `id: string`
570595
571596 Unique identifier for the skill.
from line 643
618643
619644 - `"plugin"`
620645
621 - `type: "skill"`
622
623 Object type.
624
625 For Skills, this is always `"skill"`.
626
627 default: skill
628
629646 - `updated_at: string`
630647
631648 ISO 8601 timestamp of when the skill was last updated.
from line 695
678695
679696 - `string`
680697
681 - `"message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 41 more`
698 - `"message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 42 more`
682699
683700 - `"message-batches-2024-09-24"`
684701
from line 743
726743
727744 - `"user-profiles-2026-08-18"`
728745
746 - `"user-profiles-2026-09-04"`
747
729748 - `"advisor-tool-2026-03-01"`
730749
731750 - `"managed-agents-2026-04-01"`
from line 787
768787
769788 - `"mid-conversation-system-clear-at-2026-08-21"`
770789
790- `"anthropic-workspace-id": optional string`
791
771792### Returns
772793
773794- `BetaDeletedSkill object`
774795
775 - `id: string`
776
777 Unique identifier for the skill.
778
779 The format and length of IDs may change over time.
780
781796 - `type: "skill_deleted"`
782797
783798 Deleted object type.
from line 801
786801
787802 default: skill_deleted
788803
804 - `id: string`
805
806 Unique identifier for the skill.
807
808 The format and length of IDs may change over time.
809
789810### Example
790811
791812```bash
from line 831
810831
811832- `BetaDeletedSkill object`
812833
813 - `id: string`
814
815 Unique identifier for the skill.
816
817 The format and length of IDs may change over time.
818
819834 - `type: "skill_deleted"`
820835
821836 Deleted object type.
from line 839
824839
825840 default: skill_deleted
826841
842 - `id: string`
843
844 Unique identifier for the skill.
845
846 The format and length of IDs may change over time.
847
827848### Beta Skill
828849
829850- `BetaSkill object`
830851
852 - `type: "skill"`
853
854 Object type.
855
856 For Skills, this is always `"skill"`.
857
858 default: skill
859
831860 - `id: string`
832861
833862 Unique identifier for the skill.
from line 909
880909
881910 - `"plugin"`
882911
883 - `type: "skill"`
884
885 Object type.
886
887 For Skills, this is always `"skill"`.
888
889 default: skill
890
891912 - `updated_at: string`
892913
893914 ISO 8601 timestamp of when the skill was last updated.
from line 962
941962
942963 - `string`
943964
944 - `"message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 41 more`
965 - `"message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 42 more`
945966
946967 - `"message-batches-2024-09-24"`
947968
from line 1010
9891010
9901011 - `"user-profiles-2026-08-18"`
9911012
1013 - `"user-profiles-2026-09-04"`
1014
9921015 - `"advisor-tool-2026-03-01"`
9931016
9941017 - `"managed-agents-2026-04-01"`
from line 1054
10311054
10321055 - `"mid-conversation-system-clear-at-2026-08-21"`
10331056
1057- `"anthropic-workspace-id": optional string`
1058
10341059#### Body parameters (form-data)
10351060
10361061- `files: array of string`
from line 1068
10431068
10441069- `BetaSkillVersion object`
10451070
1071 - `type: "skill_version"`
1072
1073 Object type.
1074
1075 For Skill Versions, this is always `"skill_version"`.
1076
1077 default: skill_version
1078
10461079 - `id: string`
10471080
10481081 Unique identifier for this Skill Version. The id addresses the version in
from line 1106
10731106
10741107 The format and length of IDs may change over time.
10751108
1076 - `type: "skill_version"`
1077
1078 Object type.
1079
1080 For Skill Versions, this is always `"skill_version"`.
1081
1082 default: skill_version
1083
10841109#### Example
10851110
10861111```bash
from line 1165
11401165
11411166 - `string`
11421167
1143 - `"message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 41 more`
1168 - `"message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 42 more`
11441169
11451170 - `"message-batches-2024-09-24"`
11461171
from line 1213
11881213
11891214 - `"user-profiles-2026-08-18"`
11901215
1216 - `"user-profiles-2026-09-04"`
1217
11911218 - `"advisor-tool-2026-03-01"`
11921219
11931220 - `"managed-agents-2026-04-01"`
from line 1257
12301257
12311258 - `"mid-conversation-system-clear-at-2026-08-21"`
12321259
1260- `"anthropic-workspace-id": optional string`
1261
12331262#### Returns
12341263
12351264- `data: array of BetaSkillVersion`
from line 1265
12361265
12371266 List of skills.
12381267
1268 - `type: "skill_version"`
1269
1270 Object type.
1271
1272 For Skill Versions, this is always `"skill_version"`.
1273
1274 default: skill_version
1275
12391276 - `id: string`
12401277
12411278 Unique identifier for this Skill Version. The id addresses the version in
from line 1303
12661303
12671304 The format and length of IDs may change over time.
12681305
1269 - `type: "skill_version"`
1270
1271 Object type.
1272
1273 For Skill Versions, this is always `"skill_version"`.
1274
1275 default: skill_version
1276
12771306- `next_page: string or null`
12781307
12791308 Token for fetching the next page of results.
from line 1363
13341363
13351364 - `string`
13361365
1337 - `"message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 41 more`
1366 - `"message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 42 more`
13381367
13391368 - `"message-batches-2024-09-24"`
13401369
from line 1411
13821411
13831412 - `"user-profiles-2026-08-18"`
13841413
1414 - `"user-profiles-2026-09-04"`
1415
13851416 - `"advisor-tool-2026-03-01"`
13861417
13871418 - `"managed-agents-2026-04-01"`
from line 1455
14241455
14251456 - `"mid-conversation-system-clear-at-2026-08-21"`
14261457
1458- `"anthropic-workspace-id": optional string`
1459
14271460#### Example
14281461
14291462```bash
from line 1493
14601493
14611494 - `string`
14621495
1463 - `"message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 41 more`
1496 - `"message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 42 more`
14641497
14651498 - `"message-batches-2024-09-24"`
14661499
from line 1541
15081541
15091542 - `"user-profiles-2026-08-18"`
15101543
1544 - `"user-profiles-2026-09-04"`
1545
15111546 - `"advisor-tool-2026-03-01"`
15121547
15131548 - `"managed-agents-2026-04-01"`
from line 1585
15501585
15511586 - `"mid-conversation-system-clear-at-2026-08-21"`
15521587
1588- `"anthropic-workspace-id": optional string`
1589
15531590#### Returns
15541591
15551592- `BetaSkillVersion object`
15561593
1594 - `type: "skill_version"`
1595
1596 Object type.
1597
1598 For Skill Versions, this is always `"skill_version"`.
1599
1600 default: skill_version
1601
15571602 - `id: string`
15581603
15591604 Unique identifier for this Skill Version. The id addresses the version in
from line 1629
15841629
15851630 The format and length of IDs may change over time.
15861631
1587 - `type: "skill_version"`
1588
1589 Object type.
1590
1591 For Skill Versions, this is always `"skill_version"`.
1592
1593 default: skill_version
1594
15951632#### Example
15961633
15971634```bash
from line 1678
16411678
16421679 - `string`
16431680
1644 - `"message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 41 more`
1681 - `"message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 42 more`
16451682
16461683 - `"message-batches-2024-09-24"`
16471684
from line 1726
16891726
16901727 - `"user-profiles-2026-08-18"`
16911728
1729 - `"user-profiles-2026-09-04"`
1730
16921731 - `"advisor-tool-2026-03-01"`
16931732
16941733 - `"managed-agents-2026-04-01"`
from line 1770
17311770
17321771 - `"mid-conversation-system-clear-at-2026-08-21"`
17331772
1773- `"anthropic-workspace-id": optional string`
1774
17341775#### Returns
17351776
17361777- `BetaDeletedSkillVersion object`
17371778
1738 - `id: string`
1739
1740 Unique identifier for this Skill Version. The id addresses the version in
1741 paths and pins it in references.
1742
17431779 - `type: "skill_version_deleted"`
17441780
17451781 Deleted object type.
from line 1783
17471783 For Skill Versions, this is always `"skill_version_deleted"`.
17481784
17491785 default: skill_version_deleted
1786
1787 - `id: string`
1788
1789 Unique identifier for this Skill Version. The id addresses the version in
1790 paths and pins it in references.
17501791
17511792#### Example
17521793
api/beta/skills/create Changed · +18 / -9 lines
from line 1
1---
2title: Create Skill
3url: https://platform.claude.com/docs/en/api/beta/skills/create
4---
5
16# Create Skill
27
38**POST** `/v1/skills`
from line 17
1217
1318 - `string`
1419
15 - `"message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 41 more`
20 - `"message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 42 more`
1621
1722 - `"message-batches-2024-09-24"`
1823
from line 65
6065
6166 - `"user-profiles-2026-08-18"`
6267
68 - `"user-profiles-2026-09-04"`
69
6370 - `"advisor-tool-2026-03-01"`
6471
6572 - `"managed-agents-2026-04-01"`
from line 109
102109
103110 - `"mid-conversation-system-clear-at-2026-08-21"`
104111
112- `"anthropic-workspace-id": optional string`
113
105114## Body parameters (form-data)
106115
107116- `files: array of string`
from line 129
120129
121130- `BetaSkill object`
122131
132 - `type: "skill"`
133
134 Object type.
135
136 For Skills, this is always `"skill"`.
137
138 default: skill
139
123140 - `id: string`
124141
125142 Unique identifier for the skill.
from line 188
171188 - `"anthropic_example"`
172189
173190 - `"plugin"`
174
175 - `type: "skill"`
176
177 Object type.
178
179 For Skills, this is always `"skill"`.
180
181 default: skill
182191
183192 - `updated_at: string`
184193
api/beta/skills/delete Changed · +16 / -7 lines
from line 1
1---
2title: Delete Skill
3url: https://platform.claude.com/docs/en/api/beta/skills/delete
4---
5
16# Delete Skill
27
38**DELETE** `/v1/skills/{skill_id}`
from line 25
2025
2126 - `string`
2227
23 - `"message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 41 more`
28 - `"message-batches-2024-09-24" or "prompt-caching-2024-07-31" or "computer-use-2024-10-22" or 42 more`
2429
2530 - `"message-batches-2024-09-24"`
2631
from line 73
6873
6974 - `"user-profiles-2026-08-18"`
7075
76 - `"user-profiles-2026-09-04"`
77
7178 - `"advisor-tool-2026-03-01"`
7279
7380 - `"managed-agents-2026-04-01"`
from line 117
110117
111118 - `"mid-conversation-system-clear-at-2026-08-21"`
112119
120- `"anthropic-workspace-id": optional string`
121
113122## Returns
114123
115124- `BetaDeletedSkill object`
116125
117 - `id: string`
118
119 Unique identifier for the skill.
120
121 The format and length of IDs may change over time.
122
123126 - `type: "skill_deleted"`
124127
125128 Deleted object type.
from line 130
127130 For Skills, this is always `"skill_deleted"`.
128131
129132 default: skill_deleted
133
134 - `id: string`
135
136 Unique identifier for the skill.
137
138 The format and length of IDs may change over time.
130139
131140## Example
132141