The whole hunk
from line 1, old and new numbered
/
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