One read of Claude Developer Platformapi-20261009T213714Z
59 pages moved out of 762 read.
Pages moved
59
significant first
Pages read
762
in this capture
Captured
21:37 UTC
Corpus hash
e3252cf6bcbe
index-hash
What this read moved
26-50 of 59, page 2 of 3This capture is too large to show at once. Changes 26-50 of 59 are below, significant first; the rest are on the following screens.
api/beta/sessions/threads/events Changed · +1667 / -879 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 383
383383
384384 - `custom_tool_use_id: string`
385385
386 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.
386 The id of the `agent.custom_tool_use` event this result corresponds to. It is also listed 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.
387387
388388 - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock`
389389
from line 455
455455
456456 - `BetaManagedAgentsAgentCustomToolUseEvent object`
457457
458 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.
458 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. The client can send it as soon as this event arrives, without waiting for `session.status_idle`.
459459
460460 - `type: "agent.custom_tool_use"`
461461
from line 1397
13971397
13981398 Public `sthr_` ID of the newly created thread.
13991399
1400 - `workflow_run_id: string or null`
1401
1402 Identifier of the workflow run that created the thread, or `null` for any other thread.
1403
14001404 - `BetaManagedAgentsSpanOutcomeEvaluationStartEvent object`
14011405
14021406 Emitted when an outcome evaluation cycle begins.
from line 1901
18971901
18981902 - `"claude-haiku-4-5"`
18991903
1900 Fastest model with near-frontier intelligence
1901
19021904 - `"claude-haiku-4-5-20251001"`
19031905
1904 Fastest model with near-frontier intelligence
1905
19061906 - `"claude-opus-4-5"`
19071907
19081908 Powerful intelligence for long-running agents and coding
from line 1971
19711971
19721972 - `"fast"`
19731973
1974 - `multiagent: BetaManagedAgentsSessionMultiagentCoordinator or null`
1974 - `multiagent: BetaManagedAgentsSessionMultiagent or null`
19751975
19761976 Resolved multiagent orchestration configuration. Null when the agent is single-threaded.
19771977
1978 - `type: "coordinator"`
1979
1980 - `agents: array of BetaManagedAgentsSessionThreadAgent or BetaManagedAgentsAdvisor`
1981
1982 Full `agent` definitions the coordinator may spawn as session threads.
1983
1984 - `BetaManagedAgentsSessionThreadAgent object`
1985
1986 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`.
1987
1988 - `type: "agent"`
1989
1990 - `id: string`
1991
1992 - `description: string or null`
1993
1994 - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition`
1995
1996 - `type: "url"`
1978 - `BetaManagedAgentsSessionMultiagentCoordinator object`
1979
1980 Resolved coordinator topology with full agent definitions for each roster member.
1981
1982 - `type: "coordinator"`
1983
1984 - `agents: array of BetaManagedAgentsSessionThreadAgent or BetaManagedAgentsAdvisor`
1985
1986 Full `agent` definitions the coordinator may spawn as session threads.
1987
1988 - `BetaManagedAgentsSessionThreadAgent object`
1989
1990 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`.
1991
1992 - `type: "agent"`
1993
1994 - `id: string`
1995
1996 - `description: string or null`
1997
1998 - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition`
1999
2000 - `type: "url"`
2001
2002 - `name: string`
2003
2004 - `url: string`
2005
2006 - `model: BetaManagedAgentsModelConfig`
2007
2008 Model identifier and configuration.
19972009
19982010 - `name: string`
19992011
2000 - `url: string`
2001
2002 - `model: BetaManagedAgentsModelConfig`
2003
2004 Model identifier and configuration.
2005
2006 - `name: string`
2007
2008 - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill`
2009
2010 - `BetaManagedAgentsAnthropicSkill object`
2011
2012 A resolved Anthropic-managed skill.
2013
2014 - `type: "anthropic"`
2015
2016 - `skill_id: string`
2017
2018 - `version: string`
2019
2020 - `BetaManagedAgentsCustomSkill object`
2021
2022 A resolved user-created custom skill.
2023
2024 - `type: "custom"`
2025
2026 - `skill_id: string`
2027
2028 - `version: string`
2029
2030 - `system: string or null`
2031
2032 - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool`
2033
2034 - `BetaManagedAgentsAgentToolset20260401 object`
2035
2036 - `type: "agent_toolset_20260401"`
2037
2038 - `configs: array of BetaManagedAgentsAgentToolConfig`
2039
2040 - `BetaManagedAgentsBashToolConfig object`
2041
2042 Configuration for the bash tool.
2043
2044 - `type: "bash"`
2012 - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill`
2013
2014 - `BetaManagedAgentsAnthropicSkill object`
2015
2016 A resolved Anthropic-managed skill.
2017
2018 - `type: "anthropic"`
2019
2020 - `skill_id: string`
2021
2022 - `version: string`
2023
2024 - `BetaManagedAgentsCustomSkill object`
2025
2026 A resolved user-created custom skill.
2027
2028 - `type: "custom"`
2029
2030 - `skill_id: string`
2031
2032 - `version: string`
2033
2034 - `system: string or null`
2035
2036 - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool`
2037
2038 - `BetaManagedAgentsAgentToolset20260401 object`
2039
2040 - `type: "agent_toolset_20260401"`
2041
2042 - `configs: array of BetaManagedAgentsAgentToolConfig`
2043
2044 - `BetaManagedAgentsBashToolConfig object`
2045
2046 Configuration for the bash tool.
2047
2048 - `type: "bash"`
2049
2050 - `enabled: boolean`
2051
2052 - `name: "bash"`
2053
2054 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
2055
2056 Permission policy for tool execution.
2057
2058 - `BetaManagedAgentsAlwaysAllowPolicy object`
2059
2060 Tool calls are automatically approved without user confirmation.
2061
2062 - `type: "always_allow"`
2063
2064 - `BetaManagedAgentsAlwaysAskPolicy object`
2065
2066 Tool calls require user confirmation before execution.
2067
2068 - `type: "always_ask"`
2069
2070 - `BetaManagedAgentsAutoPolicy object`
2071
2072 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.
2073
2074 - `type: "auto"`
2075
2076 - `BetaManagedAgentsEditToolConfig object`
2077
2078 Configuration for the edit tool.
2079
2080 - `type: "edit"`
2081
2082 - `enabled: boolean`
2083
2084 - `name: "edit"`
2085
2086 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
2087
2088 Permission policy for tool execution.
2089
2090 - `BetaManagedAgentsAlwaysAllowPolicy object`
2091
2092 Tool calls are automatically approved without user confirmation.
2093
2094 - `BetaManagedAgentsAlwaysAskPolicy object`
2095
2096 Tool calls require user confirmation before execution.
2097
2098 - `BetaManagedAgentsAutoPolicy object`
2099
2100 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.
2101
2102 - `BetaManagedAgentsReadToolConfig object`
2103
2104 Configuration for the read tool.
2105
2106 - `type: "read"`
2107
2108 - `enabled: boolean`
2109
2110 - `name: "read"`
2111
2112 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
2113
2114 Permission policy for tool execution.
2115
2116 - `BetaManagedAgentsAlwaysAllowPolicy object`
2117
2118 Tool calls are automatically approved without user confirmation.
2119
2120 - `BetaManagedAgentsAlwaysAskPolicy object`
2121
2122 Tool calls require user confirmation before execution.
2123
2124 - `BetaManagedAgentsAutoPolicy object`
2125
2126 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.
2127
2128 - `BetaManagedAgentsWriteToolConfig object`
2129
2130 Configuration for the write tool.
2131
2132 - `type: "write"`
2133
2134 - `enabled: boolean`
2135
2136 - `name: "write"`
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 - `BetaManagedAgentsGlobToolConfig object`
2155
2156 Configuration for the glob tool.
2157
2158 - `type: "glob"`
2159
2160 - `enabled: boolean`
2161
2162 - `name: "glob"`
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 - `BetaManagedAgentsGrepToolConfig object`
2181
2182 Configuration for the grep tool.
2183
2184 - `type: "grep"`
2185
2186 - `enabled: boolean`
2187
2188 - `name: "grep"`
2189
2190 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
2191
2192 Permission policy for tool execution.
2193
2194 - `BetaManagedAgentsAlwaysAllowPolicy object`
2195
2196 Tool calls are automatically approved without user confirmation.
2197
2198 - `BetaManagedAgentsAlwaysAskPolicy object`
2199
2200 Tool calls require user confirmation before execution.
2201
2202 - `BetaManagedAgentsAutoPolicy object`
2203
2204 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.
2205
2206 - `BetaManagedAgentsWebFetchToolConfig object`
2207
2208 Configuration for the web_fetch tool.
2209
2210 - `type: "web_fetch"`
2211
2212 - `enabled: boolean`
2213
2214 - `name: "web_fetch"`
2215
2216 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
2217
2218 Permission policy for tool execution.
2219
2220 - `BetaManagedAgentsAlwaysAllowPolicy object`
2221
2222 Tool calls are automatically approved without user confirmation.
2223
2224 - `BetaManagedAgentsAlwaysAskPolicy object`
2225
2226 Tool calls require user confirmation before execution.
2227
2228 - `BetaManagedAgentsAutoPolicy object`
2229
2230 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.
2231
2232 - `url_sources: BetaManagedAgentsWebFetchURLSources or null`
2233
2234 Which sources contribute URLs the tool may fetch, always in the object form. Null when not set, which allows every source.
2235
2236 - `client_tool_results: BetaManagedAgentsWebFetchURLSourceToolFilter or null`
2237
2238 Which custom tools' results contribute URLs that may be fetched. Null when not set, which allows every custom tool's results.
2239
2240 - `BetaManagedAgentsWebFetchURLSourceAll object`
2241
2242 Every URL from this source may be fetched. This is the default.
2243
2244 - `type: "all"`
2245
2246 - `BetaManagedAgentsWebFetchURLSourceNone object`
2247
2248 This source contributes no URLs that may be fetched.
2249
2250 - `type: "none"`
2251
2252 - `BetaManagedAgentsWebFetchURLSourceOnly object`
2253
2254 Only the named tools' results contribute URLs that may be fetched.
2255
2256 - `type: "only"`
2257
2258 - `tools: array of BetaManagedAgentsWebFetchURLSourceToolReference`
2259
2260 The tools whose results contribute. Between 1 and 128 entries, each with a different name. An empty list is rejected; use "none" to allow no tool's results.
2261
2262 - `type: "tool_reference"`
2263
2264 Must be "tool_reference".
2265
2266 - `name: string`
2267
2268 Name of the tool. Compared exactly, so upper and lower case letters are different.
2269
2270 minLength: 1, maxLength: 128
2271
2272 - `BetaManagedAgentsWebFetchURLSourceExcept object`
2273
2274 Every tool's results contribute URLs that may be fetched, except the named tools' results.
2275
2276 - `type: "except"`
2277
2278 - `tools: array of BetaManagedAgentsWebFetchURLSourceToolReference`
2279
2280 The tools whose results do not contribute. Between 1 and 128 entries, each with a different name. An empty list is rejected; use "all" to leave out no tool's results.
2281
2282 - `type: "tool_reference"`
2283
2284 Must be "tool_reference".
2285
2286 - `name: string`
2287
2288 Name of the tool. Compared exactly, so upper and lower case letters are different.
2289
2290 minLength: 1, maxLength: 128
2291
2292 - `server_tool_results: BetaManagedAgentsWebFetchURLSourceToolFilter or null`
2293
2294 Which of the web_search and web_fetch tools' results contribute URLs that may be fetched. Null when not set, which allows both.
2295
2296 - `user_input: BetaManagedAgentsWebFetchURLSourceUserInput or null`
2297
2298 Whether URLs in the text of user messages may be fetched. Null when not set, which allows them.
2299
2300 - `BetaManagedAgentsWebFetchURLSourceAll object`
2301
2302 Every URL from this source may be fetched. This is the default.
2303
2304 - `BetaManagedAgentsWebFetchURLSourceNone object`
2305
2306 This source contributes no URLs that may be fetched.
2307
2308 - `allowed_domains: optional array of string`
2309
2310 - `blocked_domains: optional array of string`
2311
2312 - `max_content_tokens: optional number or null`
2313
2314 format: int32
2315
2316 - `BetaManagedAgentsWebSearchToolConfig object`
2317
2318 Configuration for the web_search tool.
2319
2320 - `type: "web_search"`
2321
2322 - `enabled: boolean`
2323
2324 - `name: "web_search"`
2325
2326 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
2327
2328 Permission policy for tool execution.
2329
2330 - `BetaManagedAgentsAlwaysAllowPolicy object`
2331
2332 Tool calls are automatically approved without user confirmation.
2333
2334 - `BetaManagedAgentsAlwaysAskPolicy object`
2335
2336 Tool calls require user confirmation before execution.
2337
2338 - `BetaManagedAgentsAutoPolicy object`
2339
2340 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.
2341
2342 - `allowed_domains: optional array of string`
2343
2344 - `blocked_domains: optional array of string`
2345
2346 - `user_location: optional BetaManagedAgentsUserLocation or null`
2347
2348 Approximate user location for search result localization.
2349
2350 - `type: "approximate"`
2351
2352 Location precision. Only "approximate" is supported.
2353
2354 - `city: optional string or null`
2355
2356 City name.
2357
2358 minLength: 1, maxLength: 255
2359
2360 - `country: optional string or null`
2361
2362 Two-letter ISO 3166-1 country code, uppercase.
2363
2364 - `region: optional string or null`
2365
2366 Region or state name.
2367
2368 minLength: 1, maxLength: 255
2369
2370 - `timezone: optional string or null`
2371
2372 IANA timezone identifier, e.g. "America/Los_Angeles".
2373
2374 minLength: 1, maxLength: 255
2375
2376 - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig`
2377
2378 Resolved default configuration for agent tools.
20452379
20462380 - `enabled: boolean`
20472381
2048 - `name: "bash"`
2049
20502382 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
20512383
20522384 Permission policy for tool execution.
from line 2387
20552387
20562388 Tool calls are automatically approved without user confirmation.
20572389
2058 - `type: "always_allow"`
2059
20602390 - `BetaManagedAgentsAlwaysAskPolicy object`
20612391
20622392 Tool calls require user confirmation before execution.
20632393
2064 - `type: "always_ask"`
2065
20662394 - `BetaManagedAgentsAutoPolicy object`
20672395
20682396 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.
20692397
2070 - `type: "auto"`
2071
2072 - `BetaManagedAgentsEditToolConfig object`
2073
2074 Configuration for the edit tool.
2075
2076 - `type: "edit"`
2398 - `BetaManagedAgentsMCPToolset object`
2399
2400 - `type: "mcp_toolset"`
2401
2402 - `configs: array of BetaManagedAgentsMCPToolConfig`
20772403
20782404 - `enabled: boolean`
20792405
2080 - `name: "edit"`
2406 - `name: string`
20812407
20822408 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
20832409
from line 2421
20952421
20962422 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.
20972423
2098 - `BetaManagedAgentsReadToolConfig object`
2099
2100 Configuration for the read tool.
2101
2102 - `type: "read"`
2424 - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig`
2425
2426 Resolved default configuration for all tools from an MCP server.
21032427
21042428 - `enabled: boolean`
21052429
2106 - `name: "read"`
2107
21082430 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
21092431
21102432 Permission policy for tool execution.
from line 2443
21212443
21222444 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.
21232445
2124 - `BetaManagedAgentsWriteToolConfig object`
2125
2126 Configuration for the write tool.
2127
2128 - `type: "write"`
2129
2130 - `enabled: boolean`
2131
2132 - `name: "write"`
2133
2134 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
2135
2136 Permission policy for tool execution.
2137
2138 - `BetaManagedAgentsAlwaysAllowPolicy object`
2139
2140 Tool calls are automatically approved without user confirmation.
2141
2142 - `BetaManagedAgentsAlwaysAskPolicy object`
2143
2144 Tool calls require user confirmation before execution.
2145
2146 - `BetaManagedAgentsAutoPolicy object`
2147
2148 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.
2149
2150 - `BetaManagedAgentsGlobToolConfig object`
2151
2152 Configuration for the glob tool.
2153
2154 - `type: "glob"`
2155
2156 - `enabled: boolean`
2157
2158 - `name: "glob"`
2159
2160 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
2161
2162 Permission policy for tool execution.
2163
2164 - `BetaManagedAgentsAlwaysAllowPolicy object`
2165
2166 Tool calls are automatically approved without user confirmation.
2167
2168 - `BetaManagedAgentsAlwaysAskPolicy object`
2169
2170 Tool calls require user confirmation before execution.
2171
2172 - `BetaManagedAgentsAutoPolicy object`
2173
2174 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.
2175
2176 - `BetaManagedAgentsGrepToolConfig object`
2177
2178 Configuration for the grep tool.
2179
2180 - `type: "grep"`
2181
2182 - `enabled: boolean`
2183
2184 - `name: "grep"`
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 - `BetaManagedAgentsWebFetchToolConfig object`
2203
2204 Configuration for the web_fetch tool.
2205
2206 - `type: "web_fetch"`
2207
2208 - `enabled: boolean`
2209
2210 - `name: "web_fetch"`
2211
2212 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
2213
2214 Permission policy for tool execution.
2215
2216 - `BetaManagedAgentsAlwaysAllowPolicy object`
2217
2218 Tool calls are automatically approved without user confirmation.
2219
2220 - `BetaManagedAgentsAlwaysAskPolicy object`
2221
2222 Tool calls require user confirmation before execution.
2223
2224 - `BetaManagedAgentsAutoPolicy object`
2225
2226 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.
2227
2228 - `url_sources: BetaManagedAgentsWebFetchURLSources or null`
2229
2230 Which sources contribute URLs the tool may fetch, always in the object form. Null when not set, which allows every source.
2231
2232 - `client_tool_results: BetaManagedAgentsWebFetchURLSourceToolFilter or null`
2233
2234 Which custom tools' results contribute URLs that may be fetched. Null when not set, which allows every custom tool's results.
2235
2236 - `BetaManagedAgentsWebFetchURLSourceAll object`
2237
2238 Every URL from this source may be fetched. This is the default.
2239
2240 - `type: "all"`
2241
2242 - `BetaManagedAgentsWebFetchURLSourceNone object`
2243
2244 This source contributes no URLs that may be fetched.
2245
2246 - `type: "none"`
2247
2248 - `BetaManagedAgentsWebFetchURLSourceOnly object`
2249
2250 Only the named tools' results contribute URLs that may be fetched.
2251
2252 - `type: "only"`
2253
2254 - `tools: array of BetaManagedAgentsWebFetchURLSourceToolReference`
2255
2256 The tools whose results contribute. Between 1 and 128 entries, each with a different name. An empty list is rejected; use "none" to allow no tool's results.
2257
2258 - `type: "tool_reference"`
2259
2260 Must be "tool_reference".
2261
2262 - `name: string`
2263
2264 Name of the tool. Compared exactly, so upper and lower case letters are different.
2265
2266 minLength: 1, maxLength: 128
2267
2268 - `BetaManagedAgentsWebFetchURLSourceExcept object`
2269
2270 Every tool's results contribute URLs that may be fetched, except the named tools' results.
2271
2272 - `type: "except"`
2273
2274 - `tools: array of BetaManagedAgentsWebFetchURLSourceToolReference`
2275
2276 The tools whose results do not contribute. Between 1 and 128 entries, each with a different name. An empty list is rejected; use "all" to leave out no tool's results.
2277
2278 - `type: "tool_reference"`
2279
2280 Must be "tool_reference".
2281
2282 - `name: string`
2283
2284 Name of the tool. Compared exactly, so upper and lower case letters are different.
2285
2286 minLength: 1, maxLength: 128
2287
2288 - `server_tool_results: BetaManagedAgentsWebFetchURLSourceToolFilter or null`
2289
2290 Which of the web_search and web_fetch tools' results contribute URLs that may be fetched. Null when not set, which allows both.
2291
2292 - `user_input: BetaManagedAgentsWebFetchURLSourceUserInput or null`
2293
2294 Whether URLs in the text of user messages may be fetched. Null when not set, which allows them.
2295
2296 - `BetaManagedAgentsWebFetchURLSourceAll object`
2297
2298 Every URL from this source may be fetched. This is the default.
2299
2300 - `BetaManagedAgentsWebFetchURLSourceNone object`
2301
2302 This source contributes no URLs that may be fetched.
2303
2304 - `allowed_domains: optional array of string`
2305
2306 - `blocked_domains: optional array of string`
2307
2308 - `max_content_tokens: optional number or null`
2309
2310 format: int32
2311
2312 - `BetaManagedAgentsWebSearchToolConfig object`
2313
2314 Configuration for the web_search tool.
2315
2316 - `type: "web_search"`
2317
2318 - `enabled: boolean`
2319
2320 - `name: "web_search"`
2321
2322 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
2323
2324 Permission policy for tool execution.
2325
2326 - `BetaManagedAgentsAlwaysAllowPolicy object`
2327
2328 Tool calls are automatically approved without user confirmation.
2329
2330 - `BetaManagedAgentsAlwaysAskPolicy object`
2331
2332 Tool calls require user confirmation before execution.
2333
2334 - `BetaManagedAgentsAutoPolicy object`
2335
2336 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.
2337
2338 - `allowed_domains: optional array of string`
2339
2340 - `blocked_domains: optional array of string`
2341
2342 - `user_location: optional BetaManagedAgentsUserLocation or null`
2343
2344 Approximate user location for search result localization.
2345
2346 - `type: "approximate"`
2347
2348 Location precision. Only "approximate" is supported.
2349
2350 - `city: optional string or null`
2351
2352 City name.
2353
2354 minLength: 1, maxLength: 255
2355
2356 - `country: optional string or null`
2357
2358 Two-letter ISO 3166-1 country code, uppercase.
2359
2360 - `region: optional string or null`
2361
2362 Region or state name.
2363
2364 minLength: 1, maxLength: 255
2365
2366 - `timezone: optional string or null`
2367
2368 IANA timezone identifier, e.g. "America/Los_Angeles".
2369
2370 minLength: 1, maxLength: 255
2371
2372 - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig`
2373
2374 Resolved default configuration for agent tools.
2375
2376 - `enabled: boolean`
2377
2378 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
2379
2380 Permission policy for tool execution.
2381
2382 - `BetaManagedAgentsAlwaysAllowPolicy object`
2383
2384 Tool calls are automatically approved without user confirmation.
2385
2386 - `BetaManagedAgentsAlwaysAskPolicy object`
2387
2388 Tool calls require user confirmation before execution.
2389
2390 - `BetaManagedAgentsAutoPolicy object`
2391
2392 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.
2393
2394 - `BetaManagedAgentsMCPToolset object`
2395
2396 - `type: "mcp_toolset"`
2397
2398 - `configs: array of BetaManagedAgentsMCPToolConfig`
2399
2400 - `enabled: boolean`
2446 - `mcp_server_name: string`
2447
2448 - `BetaManagedAgentsCustomTool object`
2449
2450 A custom tool as returned in API responses.
2451
2452 - `type: "custom"`
2453
2454 - `description: string`
2455
2456 - `input_schema: BetaManagedAgentsCustomToolInputSchema`
2457
2458 JSON Schema for custom tool input parameters.
2459
2460 - `type: "object"`
2461
2462 - `properties: optional map[unknown] or null`
2463
2464 - `required: optional array of string or null`
24012465
24022466 - `name: string`
24032467
2404 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
2405
2406 Permission policy for tool execution.
2407
2408 - `BetaManagedAgentsAlwaysAllowPolicy object`
2409
2410 Tool calls are automatically approved without user confirmation.
2411
2412 - `BetaManagedAgentsAlwaysAskPolicy object`
2413
2414 Tool calls require user confirmation before execution.
2415
2416 - `BetaManagedAgentsAutoPolicy object`
2417
2418 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.
2419
2420 - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig`
2421
2422 Resolved default configuration for all tools from an MCP server.
2423
2424 - `enabled: boolean`
2425
2426 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
2427
2428 Permission policy for tool execution.
2429
2430 - `BetaManagedAgentsAlwaysAllowPolicy object`
2431
2432 Tool calls are automatically approved without user confirmation.
2433
2434 - `BetaManagedAgentsAlwaysAskPolicy object`
2435
2436 Tool calls require user confirmation before execution.
2437
2438 - `BetaManagedAgentsAutoPolicy object`
2439
2440 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.
2441
2442 - `mcp_server_name: string`
2443
2444 - `BetaManagedAgentsCustomTool object`
2445
2446 A custom tool as returned in API responses.
2447
2448 - `type: "custom"`
2449
2450 - `description: string`
2451
2452 - `input_schema: BetaManagedAgentsCustomToolInputSchema`
2453
2454 JSON Schema for custom tool input parameters.
2455
2456 - `type: "object"`
2457
2458 - `properties: optional map[unknown] or null`
2459
2460 - `required: optional array of string or null`
2468 - `version: number`
2469
2470 format: int32
2471
2472 - `BetaManagedAgentsAdvisor object`
2473
2474 Platform advisor roster entry: a model the session's primary thread may consult mid-turn.
2475
2476 - `type: "advisor"`
2477
2478 - `model: string`
2479
2480 The advisor model id.
2481
2482 - `BetaManagedAgentsSessionMultiagent20261001 object`
2483
2484 Resolved multiagent configuration with three members, as copied to the `session` at creation.
2485
2486 - `type: "multiagent_20261001"`
2487
2488 - `advisor: BetaManagedAgentsMultiagentAdvisor`
2489
2490 Whether the session's primary thread can consult an advisor model.
2491
2492 - `BetaManagedAgentsMultiagentAdvisorEnabled object`
2493
2494 The session's primary thread can consult `model` mid-turn.
2495
2496 - `type: "enabled"`
2497
2498 - `model: string`
2499
2500 The advisor model id.
2501
2502 - `BetaManagedAgentsMultiagentAdvisorDisabled object`
2503
2504 The agent has no advisor.
2505
2506 - `type: "disabled"`
2507
2508 - `subagents: BetaManagedAgentsSessionMultiagentSubagents`
2509
2510 Whether the agent can spawn session threads.
2511
2512 - `BetaManagedAgentsSessionMultiagentSubagentsEnabled object`
2513
2514 The agent can spawn session threads.
2515
2516 - `type: "enabled"`
2517
2518 - `inline_agents: BetaManagedAgentsMultiagentInlineAgents`
2519
2520 Whether the agent can define inline agents, which are not saved, when it spawns session threads.
2521
2522 - `BetaManagedAgentsMultiagentInlineAgentsEnabled object`
2523
2524 The agent can define inline agents.
2525
2526 - `type: "enabled"`
2527
2528 - `BetaManagedAgentsMultiagentInlineAgentsDisabled object`
2529
2530 The agent cannot define inline agents.
2531
2532 - `type: "disabled"`
2533
2534 - `predefined_agents: array of BetaManagedAgentsSessionThreadAgent`
2535
2536 Full `agent` definitions of the predefined agents, which are saved agents that this agent can spawn as session threads.
2537
2538 - `type: "agent"`
2539
2540 - `id: string`
2541
2542 - `description: string or null`
2543
2544 - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition`
2545
2546 - `model: BetaManagedAgentsModelConfig`
2547
2548 Model identifier and configuration.
24612549
24622550 - `name: string`
24632551
2464 - `version: number`
2465
2466 format: int32
2467
2468 - `BetaManagedAgentsAdvisor object`
2469
2470 Platform advisor roster entry: a model the session's primary thread may consult mid-turn.
2471
2472 - `type: "advisor"`
2473
2474 - `model: string`
2475
2476 The advisor model id.
2552 - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill`
2553
2554 - `system: string or null`
2555
2556 - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool`
2557
2558 - `version: number`
2559
2560 format: int32
2561
2562 - `BetaManagedAgentsMultiagentSubagentsDisabled object`
2563
2564 The agent cannot spawn session threads.
2565
2566 - `type: "disabled"`
2567
2568 - `workflows: BetaManagedAgentsSessionMultiagentWorkflows`
2569
2570 Whether the agent can start workflow runs.
2571
2572 - `BetaManagedAgentsSessionMultiagentWorkflowsEnabled object`
2573
2574 The agent can start workflow runs.
2575
2576 - `type: "enabled"`
2577
2578 - `inline_agents: BetaManagedAgentsMultiagentInlineAgents`
2579
2580 Whether a run's plan can define inline agents, which are not saved.
2581
2582 - `predefined_agents: array of BetaManagedAgentsSessionThreadAgent`
2583
2584 Full `agent` definitions of the predefined agents, which are saved agents that a run's plan can use.
2585
2586 - `type: "agent"`
2587
2588 - `id: string`
2589
2590 - `description: string or null`
2591
2592 - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition`
2593
2594 - `model: BetaManagedAgentsModelConfig`
2595
2596 Model identifier and configuration.
2597
2598 - `name: string`
2599
2600 - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill`
2601
2602 - `system: string or null`
2603
2604 - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool`
2605
2606 - `version: number`
2607
2608 format: int32
2609
2610 - `BetaManagedAgentsMultiagentWorkflowsDisabled object`
2611
2612 The agent cannot start workflow runs.
2613
2614 - `type: "disabled"`
24772615
24782616 - `name: string`
24792617
from line 2778
26402778 - `budget: optional BetaManagedAgentsBudgetLimit or null`
26412779
26422780 The session's configured budget at the snapshot time, or null when the session has no budget.
2781
2782 - `BetaManagedAgentsWorkflowRunCreatedEvent object`
2783
2784 A workflow run was created. A workflow run is background work that the session's agent starts. Emitted once per run, before the run's other `workflow_run.*` events.
2785
2786 - `type: "workflow_run.created"`
2787
2788 - `id: string`
2789
2790 Unique identifier for this event.
2791
2792 - `description: string or null`
2793
2794 Description that the agent gave the run, passed on as written, or `null` if it gave none.
2795
2796 - `name: string`
2797
2798 Name that the agent gave the run, passed on as written, or a name that the server assigned.
2799
2800 - `phases: array of BetaManagedAgentsWorkflowRunPhase`
2801
2802 The phases that the run's plan declares, in the plan's order. Can be empty.
2803
2804 - `id: string`
2805
2806 Unique identifier for the phase.
2807
2808 - `description: string or null`
2809
2810 Description that the agent gave the phase, passed on as written, or `null` if it gave none.
2811
2812 - `name: string`
2813
2814 Name that the agent gave the phase, passed on as written.
2815
2816 - `processed_at: string`
2817
2818 Timestamp when this event was processed.
2819
2820 format: date-time
2821
2822 - `workflow_run_id: string`
2823
2824 Identifier of the run. The same value is on all of the run's `workflow_run.*` events.
2825
2826 - `BetaManagedAgentsWorkflowRunStatusEndedEvent object`
2827
2828 A workflow run ended. Emitted once per run, as the last of the run's `workflow_run.*` events.
2829
2830 - `type: "workflow_run.status_ended"`
2831
2832 - `id: string`
2833
2834 Unique identifier for this event.
2835
2836 - `processed_at: string`
2837
2838 Timestamp when this event was processed.
2839
2840 format: date-time
2841
2842 - `result: BetaManagedAgentsWorkflowRunResult`
2843
2844 How the run ended.
2845
2846 - `BetaManagedAgentsWorkflowRunResultCompleted object`
2847
2848 The run's plan, a program that the agent wrote, finished. This does not say whether the work succeeded.
2849
2850 - `type: "completed"`
2851
2852 - `BetaManagedAgentsWorkflowRunResultError object`
2853
2854 The run failed or reached its time limit.
2855
2856 - `type: "error"`
2857
2858 - `error: BetaManagedAgentsWorkflowRunError`
2859
2860 Why the run did not finish.
2861
2862 - `BetaManagedAgentsTimeoutWorkflowRunError object`
2863
2864 The run reached its time limit.
2865
2866 - `type: "timeout_error"`
2867
2868 - `message: string`
2869
2870 Short explanation written by the server. It never contains content from the run or its agents.
2871
2872 - `BetaManagedAgentsProgramWorkflowRunError object`
2873
2874 The plan, a program that the agent wrote, failed, or the server refused it.
2875
2876 - `type: "program_error"`
2877
2878 - `message: string`
2879
2880 Short explanation written by the server. It never contains content from the run or its agents.
2881
2882 - `BetaManagedAgentsUnknownWorkflowRunError object`
2883
2884 A failure that has no type of its own.
2885
2886 - `type: "unknown_error"`
2887
2888 - `message: string`
2889
2890 Short explanation written by the server. It never contains content from the run or its agents.
2891
2892 - `BetaManagedAgentsThreadLimitWorkflowRunError object`
2893
2894 The run exceeded the limit on the number of threads that a run can create.
2895
2896 - `type: "thread_limit_error"`
2897
2898 - `message: string`
2899
2900 Short explanation written by the server. It never contains content from the run or its agents.
2901
2902 - `BetaManagedAgentsMaxWorkflowRunsWorkflowRunError object`
2903
2904 No run was created, because the session was at its limit of open workflow runs, which are runs that have not ended. Only `workflow_run.error` carries this type.
2905
2906 - `type: "max_workflow_runs_error"`
2907
2908 - `message: string`
2909
2910 Short explanation written by the server. It never contains content from the run or its agents.
2911
2912 - `BetaManagedAgentsWorkflowRunResultStopped object`
2913
2914 The agent stopped the run.
2915
2916 - `type: "stopped"`
2917
2918 - `workflow_run_id: string`
2919
2920 Identifier of the run. The same value is on all of the run's `workflow_run.*` events.
2921
2922 - `BetaManagedAgentsWorkflowRunPhaseStartedEvent object`
2923
2924 A workflow run's plan entered a phase.
2925
2926 - `type: "workflow_run.phase_started"`
2927
2928 - `id: string`
2929
2930 Unique identifier for this event.
2931
2932 - `processed_at: string`
2933
2934 Timestamp when this event was processed.
2935
2936 format: date-time
2937
2938 - `workflow_run_id: string`
2939
2940 Identifier of the run. The same value is on all of the run's `workflow_run.*` events.
2941
2942 - `workflow_run_phase_id: string`
2943
2944 Identifier of the phase, as in `phases` on the run's `workflow_run.created` event.
2945
2946 - `BetaManagedAgentsWorkflowRunPhaseEndedEvent object`
2947
2948 A workflow run's plan left a phase, or the run's end closed it. Emitted once for every `workflow_run.phase_started` event, before the run's `workflow_run.status_ended` event. The event does not say whether the plan finished the phase's work, or why it left.
2949
2950 - `type: "workflow_run.phase_ended"`
2951
2952 - `id: string`
2953
2954 Unique identifier for this event.
2955
2956 - `phase_started_id: string`
2957
2958 Identifier of the `workflow_run.phase_started` event that opened the phase.
2959
2960 - `processed_at: string`
2961
2962 Timestamp when this event was processed.
2963
2964 format: date-time
2965
2966 - `workflow_run_id: string`
2967
2968 Identifier of the run. The same value is on all of the run's `workflow_run.*` events.
2969
2970 - `workflow_run_phase_id: string`
2971
2972 Identifier of the phase, as in `phases` on the run's `workflow_run.created` event.
2973
2974 - `BetaManagedAgentsWorkflowRunStatusRunningEvent object`
2975
2976 A workflow run is running. Emitted when the run starts to execute, and each time it resumes after being idle. A run that starts idle emits `workflow_run.status_idle` first.
2977
2978 - `type: "workflow_run.status_running"`
2979
2980 - `id: string`
2981
2982 Unique identifier for this event.
2983
2984 - `processed_at: string`
2985
2986 Timestamp when this event was processed.
2987
2988 format: date-time
2989
2990 - `workflow_run_id: string`
2991
2992 Identifier of the run. The same value is on all of the run's `workflow_run.*` events.
2993
2994 - `BetaManagedAgentsWorkflowRunStatusIdleEvent object`
2995
2996 A workflow run is idle. Emitted each time the run goes idle, whatever the cause. If the run ends while idle, no `workflow_run.status_running` comes between this event and its `workflow_run.status_ended`.
2997
2998 - `type: "workflow_run.status_idle"`
2999
3000 - `id: string`
3001
3002 Unique identifier for this event.
3003
3004 - `processed_at: string`
3005
3006 Timestamp when this event was processed.
3007
3008 format: date-time
3009
3010 - `workflow_run_id: string`
3011
3012 Identifier of the run. The same value is on all of the run's `workflow_run.*` events.
3013
3014 - `BetaManagedAgentsWorkflowRunErrorEvent object`
3015
3016 A workflow run met an error, or an error kept a run from being created. A run that ends with a `result.type` of `error` emits this event before its `workflow_run.status_ended`, with the same `error`.
3017
3018 - `type: "workflow_run.error"`
3019
3020 - `id: string`
3021
3022 Unique identifier for this event.
3023
3024 - `error: BetaManagedAgentsWorkflowRunError`
3025
3026 Why the run did not finish, or was not created.
3027
3028 - `processed_at: string`
3029
3030 Timestamp when this event was processed.
3031
3032 format: date-time
3033
3034 - `workflow_run_id: string or null`
3035
3036 Identifier of the run that met the error, or `null` when the error kept a run from being created.
26433037
26443038- `next_page: optional string or null`
26453039
from line 3220
28263220
28273221### Returns
28283222
2829- `BetaManagedAgentsStreamSessionThreadEvents = BetaManagedAgentsUserMessageEvent or BetaManagedAgentsUserInterruptEvent or BetaManagedAgentsUserToolConfirmationEvent or 34 more`
3223- `BetaManagedAgentsStreamSessionThreadEvents = BetaManagedAgentsUserMessageEvent or BetaManagedAgentsUserInterruptEvent or BetaManagedAgentsUserToolConfirmationEvent or 41 more`
28303224
28313225 Server-sent event in a single thread's stream.
28323226
from line 3460
30663460
30673461 - `custom_tool_use_id: string`
30683462
3069 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.
3463 The id of the `agent.custom_tool_use` event this result corresponds to. It is also listed 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.
30703464
30713465 - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock`
30723466
from line 3532
31383532
31393533 - `BetaManagedAgentsAgentCustomToolUseEvent object`
31403534
3141 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.
3535 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. The client can send it as soon as this event arrives, without waiting for `session.status_idle`.
31423536
31433537 - `type: "agent.custom_tool_use"`
31443538
from line 4474
40804474
40814475 Public `sthr_` ID of the newly created thread.
40824476
4477 - `workflow_run_id: string or null`
4478
4479 Identifier of the workflow run that created the thread, or `null` for any other thread.
4480
40834481 - `BetaManagedAgentsSpanOutcomeEvaluationStartEvent object`
40844482
40854483 Emitted when an outcome evaluation cycle begins.
from line 4978
45804978
45814979 - `"claude-haiku-4-5"`
45824980
4583 Fastest model with near-frontier intelligence
4584
45854981 - `"claude-haiku-4-5-20251001"`
45864982
4587 Fastest model with near-frontier intelligence
4588
45894983 - `"claude-opus-4-5"`
45904984
45914985 Powerful intelligence for long-running agents and coding
from line 5048
46545048
46555049 - `"fast"`
46565050
4657 - `multiagent: BetaManagedAgentsSessionMultiagentCoordinator or null`
5051 - `multiagent: BetaManagedAgentsSessionMultiagent or null`
46585052
46595053 Resolved multiagent orchestration configuration. Null when the agent is single-threaded.
46605054
4661 - `type: "coordinator"`
4662
4663 - `agents: array of BetaManagedAgentsSessionThreadAgent or BetaManagedAgentsAdvisor`
4664
4665 Full `agent` definitions the coordinator may spawn as session threads.
4666
4667 - `BetaManagedAgentsSessionThreadAgent object`
4668
4669 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`.
4670
4671 - `type: "agent"`
4672
4673 - `id: string`
4674
4675 - `description: string or null`
4676
4677 - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition`
4678
4679 - `type: "url"`
5055 - `BetaManagedAgentsSessionMultiagentCoordinator object`
5056
5057 Resolved coordinator topology with full agent definitions for each roster member.
5058
5059 - `type: "coordinator"`
5060
5061 - `agents: array of BetaManagedAgentsSessionThreadAgent or BetaManagedAgentsAdvisor`
5062
5063 Full `agent` definitions the coordinator may spawn as session threads.
5064
5065 - `BetaManagedAgentsSessionThreadAgent object`
5066
5067 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`.
5068
5069 - `type: "agent"`
5070
5071 - `id: string`
5072
5073 - `description: string or null`
5074
5075 - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition`
5076
5077 - `type: "url"`
5078
5079 - `name: string`
5080
5081 - `url: string`
5082
5083 - `model: BetaManagedAgentsModelConfig`
5084
5085 Model identifier and configuration.
46805086
46815087 - `name: string`
46825088
4683 - `url: string`
4684
4685 - `model: BetaManagedAgentsModelConfig`
4686
4687 Model identifier and configuration.
4688
4689 - `name: string`
4690
4691 - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill`
4692
4693 - `BetaManagedAgentsAnthropicSkill object`
4694
4695 A resolved Anthropic-managed skill.
4696
4697 - `type: "anthropic"`
4698
4699 - `skill_id: string`
4700
4701 - `version: string`
4702
4703 - `BetaManagedAgentsCustomSkill object`
4704
4705 A resolved user-created custom skill.
4706
4707 - `type: "custom"`
4708
4709 - `skill_id: string`
4710
4711 - `version: string`
4712
4713 - `system: string or null`
4714
4715 - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool`
4716
4717 - `BetaManagedAgentsAgentToolset20260401 object`
4718
4719 - `type: "agent_toolset_20260401"`
4720
4721 - `configs: array of BetaManagedAgentsAgentToolConfig`
4722
4723 - `BetaManagedAgentsBashToolConfig object`
4724
4725 Configuration for the bash tool.
4726
4727 - `type: "bash"`
5089 - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill`
5090
5091 - `BetaManagedAgentsAnthropicSkill object`
5092
5093 A resolved Anthropic-managed skill.
5094
5095 - `type: "anthropic"`
5096
5097 - `skill_id: string`
5098
5099 - `version: string`
5100
5101 - `BetaManagedAgentsCustomSkill object`
5102
5103 A resolved user-created custom skill.
5104
5105 - `type: "custom"`
5106
5107 - `skill_id: string`
5108
5109 - `version: string`
5110
5111 - `system: string or null`
5112
5113 - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool`
5114
5115 - `BetaManagedAgentsAgentToolset20260401 object`
5116
5117 - `type: "agent_toolset_20260401"`
5118
5119 - `configs: array of BetaManagedAgentsAgentToolConfig`
5120
5121 - `BetaManagedAgentsBashToolConfig object`
5122
5123 Configuration for the bash tool.
5124
5125 - `type: "bash"`
5126
5127 - `enabled: boolean`
5128
5129 - `name: "bash"`
5130
5131 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
5132
5133 Permission policy for tool execution.
5134
5135 - `BetaManagedAgentsAlwaysAllowPolicy object`
5136
5137 Tool calls are automatically approved without user confirmation.
5138
5139 - `type: "always_allow"`
5140
5141 - `BetaManagedAgentsAlwaysAskPolicy object`
5142
5143 Tool calls require user confirmation before execution.
5144
5145 - `type: "always_ask"`
5146
5147 - `BetaManagedAgentsAutoPolicy object`
5148
5149 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.
5150
5151 - `type: "auto"`
5152
5153 - `BetaManagedAgentsEditToolConfig object`
5154
5155 Configuration for the edit tool.
5156
5157 - `type: "edit"`
5158
5159 - `enabled: boolean`
5160
5161 - `name: "edit"`
5162
5163 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
5164
5165 Permission policy for tool execution.
5166
5167 - `BetaManagedAgentsAlwaysAllowPolicy object`
5168
5169 Tool calls are automatically approved without user confirmation.
5170
5171 - `BetaManagedAgentsAlwaysAskPolicy object`
5172
5173 Tool calls require user confirmation before execution.
5174
5175 - `BetaManagedAgentsAutoPolicy object`
5176
5177 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.
5178
5179 - `BetaManagedAgentsReadToolConfig object`
5180
5181 Configuration for the read tool.
5182
5183 - `type: "read"`
5184
5185 - `enabled: boolean`
5186
5187 - `name: "read"`
5188
5189 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
5190
5191 Permission policy for tool execution.
5192
5193 - `BetaManagedAgentsAlwaysAllowPolicy object`
5194
5195 Tool calls are automatically approved without user confirmation.
5196
5197 - `BetaManagedAgentsAlwaysAskPolicy object`
5198
5199 Tool calls require user confirmation before execution.
5200
5201 - `BetaManagedAgentsAutoPolicy object`
5202
5203 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.
5204
5205 - `BetaManagedAgentsWriteToolConfig object`
5206
5207 Configuration for the write tool.
5208
5209 - `type: "write"`
5210
5211 - `enabled: boolean`
5212
5213 - `name: "write"`
5214
5215 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
5216
5217 Permission policy for tool execution.
5218
5219 - `BetaManagedAgentsAlwaysAllowPolicy object`
5220
5221 Tool calls are automatically approved without user confirmation.
5222
5223 - `BetaManagedAgentsAlwaysAskPolicy object`
5224
5225 Tool calls require user confirmation before execution.
5226
5227 - `BetaManagedAgentsAutoPolicy object`
5228
5229 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.
5230
5231 - `BetaManagedAgentsGlobToolConfig object`
5232
5233 Configuration for the glob tool.
5234
5235 - `type: "glob"`
5236
5237 - `enabled: boolean`
5238
5239 - `name: "glob"`
5240
5241 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
5242
5243 Permission policy for tool execution.
5244
5245 - `BetaManagedAgentsAlwaysAllowPolicy object`
5246
5247 Tool calls are automatically approved without user confirmation.
5248
5249 - `BetaManagedAgentsAlwaysAskPolicy object`
5250
5251 Tool calls require user confirmation before execution.
5252
5253 - `BetaManagedAgentsAutoPolicy object`
5254
5255 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.
5256
5257 - `BetaManagedAgentsGrepToolConfig object`
5258
5259 Configuration for the grep tool.
5260
5261 - `type: "grep"`
5262
5263 - `enabled: boolean`
5264
5265 - `name: "grep"`
5266
5267 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
5268
5269 Permission policy for tool execution.
5270
5271 - `BetaManagedAgentsAlwaysAllowPolicy object`
5272
5273 Tool calls are automatically approved without user confirmation.
5274
5275 - `BetaManagedAgentsAlwaysAskPolicy object`
5276
5277 Tool calls require user confirmation before execution.
5278
5279 - `BetaManagedAgentsAutoPolicy object`
5280
5281 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.
5282
5283 - `BetaManagedAgentsWebFetchToolConfig object`
5284
5285 Configuration for the web_fetch tool.
5286
5287 - `type: "web_fetch"`
5288
5289 - `enabled: boolean`
5290
5291 - `name: "web_fetch"`
5292
5293 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
5294
5295 Permission policy for tool execution.
5296
5297 - `BetaManagedAgentsAlwaysAllowPolicy object`
5298
5299 Tool calls are automatically approved without user confirmation.
5300
5301 - `BetaManagedAgentsAlwaysAskPolicy object`
5302
5303 Tool calls require user confirmation before execution.
5304
5305 - `BetaManagedAgentsAutoPolicy object`
5306
5307 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.
5308
5309 - `url_sources: BetaManagedAgentsWebFetchURLSources or null`
5310
5311 Which sources contribute URLs the tool may fetch, always in the object form. Null when not set, which allows every source.
5312
5313 - `client_tool_results: BetaManagedAgentsWebFetchURLSourceToolFilter or null`
5314
5315 Which custom tools' results contribute URLs that may be fetched. Null when not set, which allows every custom tool's results.
5316
5317 - `BetaManagedAgentsWebFetchURLSourceAll object`
5318
5319 Every URL from this source may be fetched. This is the default.
5320
5321 - `type: "all"`
5322
5323 - `BetaManagedAgentsWebFetchURLSourceNone object`
5324
5325 This source contributes no URLs that may be fetched.
5326
5327 - `type: "none"`
5328
5329 - `BetaManagedAgentsWebFetchURLSourceOnly object`
5330
5331 Only the named tools' results contribute URLs that may be fetched.
5332
5333 - `type: "only"`
5334
5335 - `tools: array of BetaManagedAgentsWebFetchURLSourceToolReference`
5336
5337 The tools whose results contribute. Between 1 and 128 entries, each with a different name. An empty list is rejected; use "none" to allow no tool's results.
5338
5339 - `type: "tool_reference"`
5340
5341 Must be "tool_reference".
5342
5343 - `name: string`
5344
5345 Name of the tool. Compared exactly, so upper and lower case letters are different.
5346
5347 minLength: 1, maxLength: 128
5348
5349 - `BetaManagedAgentsWebFetchURLSourceExcept object`
5350
5351 Every tool's results contribute URLs that may be fetched, except the named tools' results.
5352
5353 - `type: "except"`
5354
5355 - `tools: array of BetaManagedAgentsWebFetchURLSourceToolReference`
5356
5357 The tools whose results do not contribute. Between 1 and 128 entries, each with a different name. An empty list is rejected; use "all" to leave out no tool's results.
5358
5359 - `type: "tool_reference"`
5360
5361 Must be "tool_reference".
5362
5363 - `name: string`
5364
5365 Name of the tool. Compared exactly, so upper and lower case letters are different.
5366
5367 minLength: 1, maxLength: 128
5368
5369 - `server_tool_results: BetaManagedAgentsWebFetchURLSourceToolFilter or null`
5370
5371 Which of the web_search and web_fetch tools' results contribute URLs that may be fetched. Null when not set, which allows both.
5372
5373 - `user_input: BetaManagedAgentsWebFetchURLSourceUserInput or null`
5374
5375 Whether URLs in the text of user messages may be fetched. Null when not set, which allows them.
5376
5377 - `BetaManagedAgentsWebFetchURLSourceAll object`
5378
5379 Every URL from this source may be fetched. This is the default.
5380
5381 - `BetaManagedAgentsWebFetchURLSourceNone object`
5382
5383 This source contributes no URLs that may be fetched.
5384
5385 - `allowed_domains: optional array of string`
5386
5387 - `blocked_domains: optional array of string`
5388
5389 - `max_content_tokens: optional number or null`
5390
5391 format: int32
5392
5393 - `BetaManagedAgentsWebSearchToolConfig object`
5394
5395 Configuration for the web_search tool.
5396
5397 - `type: "web_search"`
5398
5399 - `enabled: boolean`
5400
5401 - `name: "web_search"`
5402
5403 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
5404
5405 Permission policy for tool execution.
5406
5407 - `BetaManagedAgentsAlwaysAllowPolicy object`
5408
5409 Tool calls are automatically approved without user confirmation.
5410
5411 - `BetaManagedAgentsAlwaysAskPolicy object`
5412
5413 Tool calls require user confirmation before execution.
5414
5415 - `BetaManagedAgentsAutoPolicy object`
5416
5417 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.
5418
5419 - `allowed_domains: optional array of string`
5420
5421 - `blocked_domains: optional array of string`
5422
5423 - `user_location: optional BetaManagedAgentsUserLocation or null`
5424
5425 Approximate user location for search result localization.
5426
5427 - `type: "approximate"`
5428
5429 Location precision. Only "approximate" is supported.
5430
5431 - `city: optional string or null`
5432
5433 City name.
5434
5435 minLength: 1, maxLength: 255
5436
5437 - `country: optional string or null`
5438
5439 Two-letter ISO 3166-1 country code, uppercase.
5440
5441 - `region: optional string or null`
5442
5443 Region or state name.
5444
5445 minLength: 1, maxLength: 255
5446
5447 - `timezone: optional string or null`
5448
5449 IANA timezone identifier, e.g. "America/Los_Angeles".
5450
5451 minLength: 1, maxLength: 255
5452
5453 - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig`
5454
5455 Resolved default configuration for agent tools.
47285456
47295457 - `enabled: boolean`
47305458
4731 - `name: "bash"`
4732
47335459 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
47345460
47355461 Permission policy for tool execution.
from line 5464
47385464
47395465 Tool calls are automatically approved without user confirmation.
47405466
4741 - `type: "always_allow"`
4742
47435467 - `BetaManagedAgentsAlwaysAskPolicy object`
47445468
47455469 Tool calls require user confirmation before execution.
47465470
4747 - `type: "always_ask"`
4748
47495471 - `BetaManagedAgentsAutoPolicy object`
47505472
47515473 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.
47525474
4753 - `type: "auto"`
4754
4755 - `BetaManagedAgentsEditToolConfig object`
4756
4757 Configuration for the edit tool.
4758
4759 - `type: "edit"`
5475 - `BetaManagedAgentsMCPToolset object`
5476
5477 - `type: "mcp_toolset"`
5478
5479 - `configs: array of BetaManagedAgentsMCPToolConfig`
47605480
47615481 - `enabled: boolean`
47625482
4763 - `name: "edit"`
5483 - `name: string`
47645484
47655485 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
47665486
from line 5498
47785498
47795499 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.
47805500
4781 - `BetaManagedAgentsReadToolConfig object`
4782
4783 Configuration for the read tool.
4784
4785 - `type: "read"`
5501 - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig`
5502
5503 Resolved default configuration for all tools from an MCP server.
47865504
47875505 - `enabled: boolean`
47885506
4789 - `name: "read"`
4790
47915507 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
47925508
47935509 Permission policy for tool execution.
from line 5520
48045520
48055521 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.
48065522
4807 - `BetaManagedAgentsWriteToolConfig object`
4808
4809 Configuration for the write tool.
4810
4811 - `type: "write"`
4812
4813 - `enabled: boolean`
4814
4815 - `name: "write"`
4816
4817 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
4818
4819 Permission policy for tool execution.
4820
4821 - `BetaManagedAgentsAlwaysAllowPolicy object`
4822
4823 Tool calls are automatically approved without user confirmation.
4824
4825 - `BetaManagedAgentsAlwaysAskPolicy object`
4826
4827 Tool calls require user confirmation before execution.
4828
4829 - `BetaManagedAgentsAutoPolicy object`
4830
4831 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.
4832
4833 - `BetaManagedAgentsGlobToolConfig object`
4834
4835 Configuration for the glob tool.
4836
4837 - `type: "glob"`
4838
4839 - `enabled: boolean`
4840
4841 - `name: "glob"`
4842
4843 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
4844
4845 Permission policy for tool execution.
4846
4847 - `BetaManagedAgentsAlwaysAllowPolicy object`
4848
4849 Tool calls are automatically approved without user confirmation.
4850
4851 - `BetaManagedAgentsAlwaysAskPolicy object`
4852
4853 Tool calls require user confirmation before execution.
4854
4855 - `BetaManagedAgentsAutoPolicy object`
4856
4857 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.
4858
4859 - `BetaManagedAgentsGrepToolConfig object`
4860
4861 Configuration for the grep tool.
4862
4863 - `type: "grep"`
4864
4865 - `enabled: boolean`
4866
4867 - `name: "grep"`
4868
4869 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
4870
4871 Permission policy for tool execution.
4872
4873 - `BetaManagedAgentsAlwaysAllowPolicy object`
4874
4875 Tool calls are automatically approved without user confirmation.
4876
4877 - `BetaManagedAgentsAlwaysAskPolicy object`
4878
4879 Tool calls require user confirmation before execution.
4880
4881 - `BetaManagedAgentsAutoPolicy object`
4882
4883 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.
4884
4885 - `BetaManagedAgentsWebFetchToolConfig object`
4886
4887 Configuration for the web_fetch tool.
4888
4889 - `type: "web_fetch"`
4890
4891 - `enabled: boolean`
4892
4893 - `name: "web_fetch"`
4894
4895 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
4896
4897 Permission policy for tool execution.
4898
4899 - `BetaManagedAgentsAlwaysAllowPolicy object`
4900
4901 Tool calls are automatically approved without user confirmation.
4902
4903 - `BetaManagedAgentsAlwaysAskPolicy object`
4904
4905 Tool calls require user confirmation before execution.
4906
4907 - `BetaManagedAgentsAutoPolicy object`
4908
4909 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.
4910
4911 - `url_sources: BetaManagedAgentsWebFetchURLSources or null`
4912
4913 Which sources contribute URLs the tool may fetch, always in the object form. Null when not set, which allows every source.
4914
4915 - `client_tool_results: BetaManagedAgentsWebFetchURLSourceToolFilter or null`
4916
4917 Which custom tools' results contribute URLs that may be fetched. Null when not set, which allows every custom tool's results.
4918
4919 - `BetaManagedAgentsWebFetchURLSourceAll object`
4920
4921 Every URL from this source may be fetched. This is the default.
4922
4923 - `type: "all"`
4924
4925 - `BetaManagedAgentsWebFetchURLSourceNone object`
4926
4927 This source contributes no URLs that may be fetched.
4928
4929 - `type: "none"`
4930
4931 - `BetaManagedAgentsWebFetchURLSourceOnly object`
4932
4933 Only the named tools' results contribute URLs that may be fetched.
4934
4935 - `type: "only"`
4936
4937 - `tools: array of BetaManagedAgentsWebFetchURLSourceToolReference`
4938
4939 The tools whose results contribute. Between 1 and 128 entries, each with a different name. An empty list is rejected; use "none" to allow no tool's results.
4940
4941 - `type: "tool_reference"`
4942
4943 Must be "tool_reference".
4944
4945 - `name: string`
4946
4947 Name of the tool. Compared exactly, so upper and lower case letters are different.
4948
4949 minLength: 1, maxLength: 128
4950
4951 - `BetaManagedAgentsWebFetchURLSourceExcept object`
4952
4953 Every tool's results contribute URLs that may be fetched, except the named tools' results.
4954
4955 - `type: "except"`
4956
4957 - `tools: array of BetaManagedAgentsWebFetchURLSourceToolReference`
4958
4959 The tools whose results do not contribute. Between 1 and 128 entries, each with a different name. An empty list is rejected; use "all" to leave out no tool's results.
4960
4961 - `type: "tool_reference"`
4962
4963 Must be "tool_reference".
4964
4965 - `name: string`
4966
4967 Name of the tool. Compared exactly, so upper and lower case letters are different.
4968
4969 minLength: 1, maxLength: 128
4970
4971 - `server_tool_results: BetaManagedAgentsWebFetchURLSourceToolFilter or null`
4972
4973 Which of the web_search and web_fetch tools' results contribute URLs that may be fetched. Null when not set, which allows both.
4974
4975 - `user_input: BetaManagedAgentsWebFetchURLSourceUserInput or null`
4976
4977 Whether URLs in the text of user messages may be fetched. Null when not set, which allows them.
4978
4979 - `BetaManagedAgentsWebFetchURLSourceAll object`
4980
4981 Every URL from this source may be fetched. This is the default.
4982
4983 - `BetaManagedAgentsWebFetchURLSourceNone object`
4984
4985 This source contributes no URLs that may be fetched.
4986
4987 - `allowed_domains: optional array of string`
4988
4989 - `blocked_domains: optional array of string`
4990
4991 - `max_content_tokens: optional number or null`
4992
4993 format: int32
4994
4995 - `BetaManagedAgentsWebSearchToolConfig object`
4996
4997 Configuration for the web_search tool.
4998
4999 - `type: "web_search"`
5000
5001 - `enabled: boolean`
5002
5003 - `name: "web_search"`
5004
5005 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
5006
5007 Permission policy for tool execution.
5008
5009 - `BetaManagedAgentsAlwaysAllowPolicy object`
5010
5011 Tool calls are automatically approved without user confirmation.
5012
5013 - `BetaManagedAgentsAlwaysAskPolicy object`
5014
5015 Tool calls require user confirmation before execution.
5016
5017 - `BetaManagedAgentsAutoPolicy object`
5018
5019 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.
5020
5021 - `allowed_domains: optional array of string`
5022
5023 - `blocked_domains: optional array of string`
5024
5025 - `user_location: optional BetaManagedAgentsUserLocation or null`
5026
5027 Approximate user location for search result localization.
5028
5029 - `type: "approximate"`
5030
5031 Location precision. Only "approximate" is supported.
5032
5033 - `city: optional string or null`
5034
5035 City name.
5036
5037 minLength: 1, maxLength: 255
5038
5039 - `country: optional string or null`
5040
5041 Two-letter ISO 3166-1 country code, uppercase.
5042
5043 - `region: optional string or null`
5044
5045 Region or state name.
5046
5047 minLength: 1, maxLength: 255
5048
5049 - `timezone: optional string or null`
5050
5051 IANA timezone identifier, e.g. "America/Los_Angeles".
5052
5053 minLength: 1, maxLength: 255
5054
5055 - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig`
5056
5057 Resolved default configuration for agent tools.
5058
5059 - `enabled: boolean`
5060
5061 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
5062
5063 Permission policy for tool execution.
5064
5065 - `BetaManagedAgentsAlwaysAllowPolicy object`
5066
5067 Tool calls are automatically approved without user confirmation.
5068
5069 - `BetaManagedAgentsAlwaysAskPolicy object`
5070
5071 Tool calls require user confirmation before execution.
5072
5073 - `BetaManagedAgentsAutoPolicy object`
5074
5075 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.
5076
5077 - `BetaManagedAgentsMCPToolset object`
5078
5079 - `type: "mcp_toolset"`
5080
5081 - `configs: array of BetaManagedAgentsMCPToolConfig`
5082
5083 - `enabled: boolean`
5523 - `mcp_server_name: string`
5524
5525 - `BetaManagedAgentsCustomTool object`
5526
5527 A custom tool as returned in API responses.
5528
5529 - `type: "custom"`
5530
5531 - `description: string`
5532
5533 - `input_schema: BetaManagedAgentsCustomToolInputSchema`
5534
5535 JSON Schema for custom tool input parameters.
5536
5537 - `type: "object"`
5538
5539 - `properties: optional map[unknown] or null`
5540
5541 - `required: optional array of string or null`
50845542
50855543 - `name: string`
50865544
5087 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
5088
5089 Permission policy for tool execution.
5090
5091 - `BetaManagedAgentsAlwaysAllowPolicy object`
5092
5093 Tool calls are automatically approved without user confirmation.
5094
5095 - `BetaManagedAgentsAlwaysAskPolicy object`
5096
5097 Tool calls require user confirmation before execution.
5098
5099 - `BetaManagedAgentsAutoPolicy object`
5100
5101 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.
5102
5103 - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig`
5104
5105 Resolved default configuration for all tools from an MCP server.
5106
5107 - `enabled: boolean`
5108
5109 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
5110
5111 Permission policy for tool execution.
5112
5113 - `BetaManagedAgentsAlwaysAllowPolicy object`
5114
5115 Tool calls are automatically approved without user confirmation.
5116
5117 - `BetaManagedAgentsAlwaysAskPolicy object`
5118
5119 Tool calls require user confirmation before execution.
5120
5121 - `BetaManagedAgentsAutoPolicy object`
5122
5123 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.
5124
5125 - `mcp_server_name: string`
5126
5127 - `BetaManagedAgentsCustomTool object`
5128
5129 A custom tool as returned in API responses.
5130
5131 - `type: "custom"`
5132
5133 - `description: string`
5134
5135 - `input_schema: BetaManagedAgentsCustomToolInputSchema`
5136
5137 JSON Schema for custom tool input parameters.
5138
5139 - `type: "object"`
5140
5141 - `properties: optional map[unknown] or null`
5142
5143 - `required: optional array of string or null`
5545 - `version: number`
5546
5547 format: int32
5548
5549 - `BetaManagedAgentsAdvisor object`
5550
5551 Platform advisor roster entry: a model the session's primary thread may consult mid-turn.
5552
5553 - `type: "advisor"`
5554
5555 - `model: string`
5556
5557 The advisor model id.
5558
5559 - `BetaManagedAgentsSessionMultiagent20261001 object`
5560
5561 Resolved multiagent configuration with three members, as copied to the `session` at creation.
5562
5563 - `type: "multiagent_20261001"`
5564
5565 - `advisor: BetaManagedAgentsMultiagentAdvisor`
5566
5567 Whether the session's primary thread can consult an advisor model.
5568
5569 - `BetaManagedAgentsMultiagentAdvisorEnabled object`
5570
5571 The session's primary thread can consult `model` mid-turn.
5572
5573 - `type: "enabled"`
5574
5575 - `model: string`
5576
5577 The advisor model id.
5578
5579 - `BetaManagedAgentsMultiagentAdvisorDisabled object`
5580
5581 The agent has no advisor.
5582
5583 - `type: "disabled"`
5584
5585 - `subagents: BetaManagedAgentsSessionMultiagentSubagents`
5586
5587 Whether the agent can spawn session threads.
5588
5589 - `BetaManagedAgentsSessionMultiagentSubagentsEnabled object`
5590
5591 The agent can spawn session threads.
5592
5593 - `type: "enabled"`
5594
5595 - `inline_agents: BetaManagedAgentsMultiagentInlineAgents`
5596
5597 Whether the agent can define inline agents, which are not saved, when it spawns session threads.
5598
5599 - `BetaManagedAgentsMultiagentInlineAgentsEnabled object`
5600
5601 The agent can define inline agents.
5602
5603 - `type: "enabled"`
5604
5605 - `BetaManagedAgentsMultiagentInlineAgentsDisabled object`
5606
5607 The agent cannot define inline agents.
5608
5609 - `type: "disabled"`
5610
5611 - `predefined_agents: array of BetaManagedAgentsSessionThreadAgent`
5612
5613 Full `agent` definitions of the predefined agents, which are saved agents that this agent can spawn as session threads.
5614
5615 - `type: "agent"`
5616
5617 - `id: string`
5618
5619 - `description: string or null`
5620
5621 - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition`
5622
5623 - `model: BetaManagedAgentsModelConfig`
5624
5625 Model identifier and configuration.
51445626
51455627 - `name: string`
51465628
5147 - `version: number`
5148
5149 format: int32
5150
5151 - `BetaManagedAgentsAdvisor object`
5152
5153 Platform advisor roster entry: a model the session's primary thread may consult mid-turn.
5154
5155 - `type: "advisor"`
5156
5157 - `model: string`
5158
5159 The advisor model id.
5629 - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill`
5630
5631 - `system: string or null`
5632
5633 - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool`
5634
5635 - `version: number`
5636
5637 format: int32
5638
5639 - `BetaManagedAgentsMultiagentSubagentsDisabled object`
5640
5641 The agent cannot spawn session threads.
5642
5643 - `type: "disabled"`
5644
5645 - `workflows: BetaManagedAgentsSessionMultiagentWorkflows`
5646
5647 Whether the agent can start workflow runs.
5648
5649 - `BetaManagedAgentsSessionMultiagentWorkflowsEnabled object`
5650
5651 The agent can start workflow runs.
5652
5653 - `type: "enabled"`
5654
5655 - `inline_agents: BetaManagedAgentsMultiagentInlineAgents`
5656
5657 Whether a run's plan can define inline agents, which are not saved.
5658
5659 - `predefined_agents: array of BetaManagedAgentsSessionThreadAgent`
5660
5661 Full `agent` definitions of the predefined agents, which are saved agents that a run's plan can use.
5662
5663 - `type: "agent"`
5664
5665 - `id: string`
5666
5667 - `description: string or null`
5668
5669 - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition`
5670
5671 - `model: BetaManagedAgentsModelConfig`
5672
5673 Model identifier and configuration.
5674
5675 - `name: string`
5676
5677 - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill`
5678
5679 - `system: string or null`
5680
5681 - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool`
5682
5683 - `version: number`
5684
5685 format: int32
5686
5687 - `BetaManagedAgentsMultiagentWorkflowsDisabled object`
5688
5689 The agent cannot start workflow runs.
5690
5691 - `type: "disabled"`
51605692
51615693 - `name: string`
51625694
from line 5905
53735905 - `budget: optional BetaManagedAgentsBudgetLimit or null`
53745906
53755907 The session's configured budget at the snapshot time, or null when the session has no budget.
5908
5909 - `BetaManagedAgentsWorkflowRunCreatedEvent object`
5910
5911 A workflow run was created. A workflow run is background work that the session's agent starts. Emitted once per run, before the run's other `workflow_run.*` events.
5912
5913 - `type: "workflow_run.created"`
5914
5915 - `id: string`
5916
5917 Unique identifier for this event.
5918
5919 - `description: string or null`
5920
5921 Description that the agent gave the run, passed on as written, or `null` if it gave none.
5922
5923 - `name: string`
5924
5925 Name that the agent gave the run, passed on as written, or a name that the server assigned.
5926
5927 - `phases: array of BetaManagedAgentsWorkflowRunPhase`
5928
5929 The phases that the run's plan declares, in the plan's order. Can be empty.
5930
5931 - `id: string`
5932
5933 Unique identifier for the phase.
5934
5935 - `description: string or null`
5936
5937 Description that the agent gave the phase, passed on as written, or `null` if it gave none.
5938
5939 - `name: string`
5940
5941 Name that the agent gave the phase, passed on as written.
5942
5943 - `processed_at: string`
5944
5945 Timestamp when this event was processed.
5946
5947 format: date-time
5948
5949 - `workflow_run_id: string`
5950
5951 Identifier of the run. The same value is on all of the run's `workflow_run.*` events.
5952
5953 - `BetaManagedAgentsWorkflowRunStatusEndedEvent object`
5954
5955 A workflow run ended. Emitted once per run, as the last of the run's `workflow_run.*` events.
5956
5957 - `type: "workflow_run.status_ended"`
5958
5959 - `id: string`
5960
5961 Unique identifier for this event.
5962
5963 - `processed_at: string`
5964
5965 Timestamp when this event was processed.
5966
5967 format: date-time
5968
5969 - `result: BetaManagedAgentsWorkflowRunResult`
5970
5971 How the run ended.
5972
5973 - `BetaManagedAgentsWorkflowRunResultCompleted object`
5974
5975 The run's plan, a program that the agent wrote, finished. This does not say whether the work succeeded.
5976
5977 - `type: "completed"`
5978
5979 - `BetaManagedAgentsWorkflowRunResultError object`
5980
5981 The run failed or reached its time limit.
5982
5983 - `type: "error"`
5984
5985 - `error: BetaManagedAgentsWorkflowRunError`
5986
5987 Why the run did not finish.
5988
5989 - `BetaManagedAgentsTimeoutWorkflowRunError object`
5990
5991 The run reached its time limit.
5992
5993 - `type: "timeout_error"`
5994
5995 - `message: string`
5996
5997 Short explanation written by the server. It never contains content from the run or its agents.
5998
5999 - `BetaManagedAgentsProgramWorkflowRunError object`
6000
6001 The plan, a program that the agent wrote, failed, or the server refused it.
6002
6003 - `type: "program_error"`
6004
6005 - `message: string`
6006
6007 Short explanation written by the server. It never contains content from the run or its agents.
6008
6009 - `BetaManagedAgentsUnknownWorkflowRunError object`
6010
6011 A failure that has no type of its own.
6012
6013 - `type: "unknown_error"`
6014
6015 - `message: string`
6016
6017 Short explanation written by the server. It never contains content from the run or its agents.
6018
6019 - `BetaManagedAgentsThreadLimitWorkflowRunError object`
6020
6021 The run exceeded the limit on the number of threads that a run can create.
6022
6023 - `type: "thread_limit_error"`
6024
6025 - `message: string`
6026
6027 Short explanation written by the server. It never contains content from the run or its agents.
6028
6029 - `BetaManagedAgentsMaxWorkflowRunsWorkflowRunError object`
6030
6031 No run was created, because the session was at its limit of open workflow runs, which are runs that have not ended. Only `workflow_run.error` carries this type.
6032
6033 - `type: "max_workflow_runs_error"`
6034
6035 - `message: string`
6036
6037 Short explanation written by the server. It never contains content from the run or its agents.
6038
6039 - `BetaManagedAgentsWorkflowRunResultStopped object`
6040
6041 The agent stopped the run.
6042
6043 - `type: "stopped"`
6044
6045 - `workflow_run_id: string`
6046
6047 Identifier of the run. The same value is on all of the run's `workflow_run.*` events.
6048
6049 - `BetaManagedAgentsWorkflowRunPhaseStartedEvent object`
6050
6051 A workflow run's plan entered a phase.
6052
6053 - `type: "workflow_run.phase_started"`
6054
6055 - `id: string`
6056
6057 Unique identifier for this event.
6058
6059 - `processed_at: string`
6060
6061 Timestamp when this event was processed.
6062
6063 format: date-time
6064
6065 - `workflow_run_id: string`
6066
6067 Identifier of the run. The same value is on all of the run's `workflow_run.*` events.
6068
6069 - `workflow_run_phase_id: string`
6070
6071 Identifier of the phase, as in `phases` on the run's `workflow_run.created` event.
6072
6073 - `BetaManagedAgentsWorkflowRunPhaseEndedEvent object`
6074
6075 A workflow run's plan left a phase, or the run's end closed it. Emitted once for every `workflow_run.phase_started` event, before the run's `workflow_run.status_ended` event. The event does not say whether the plan finished the phase's work, or why it left.
6076
6077 - `type: "workflow_run.phase_ended"`
6078
6079 - `id: string`
6080
6081 Unique identifier for this event.
6082
6083 - `phase_started_id: string`
6084
6085 Identifier of the `workflow_run.phase_started` event that opened the phase.
6086
6087 - `processed_at: string`
6088
6089 Timestamp when this event was processed.
6090
6091 format: date-time
6092
6093 - `workflow_run_id: string`
6094
6095 Identifier of the run. The same value is on all of the run's `workflow_run.*` events.
6096
6097 - `workflow_run_phase_id: string`
6098
6099 Identifier of the phase, as in `phases` on the run's `workflow_run.created` event.
6100
6101 - `BetaManagedAgentsWorkflowRunStatusRunningEvent object`
6102
6103 A workflow run is running. Emitted when the run starts to execute, and each time it resumes after being idle. A run that starts idle emits `workflow_run.status_idle` first.
6104
6105 - `type: "workflow_run.status_running"`
6106
6107 - `id: string`
6108
6109 Unique identifier for this event.
6110
6111 - `processed_at: string`
6112
6113 Timestamp when this event was processed.
6114
6115 format: date-time
6116
6117 - `workflow_run_id: string`
6118
6119 Identifier of the run. The same value is on all of the run's `workflow_run.*` events.
6120
6121 - `BetaManagedAgentsWorkflowRunStatusIdleEvent object`
6122
6123 A workflow run is idle. Emitted each time the run goes idle, whatever the cause. If the run ends while idle, no `workflow_run.status_running` comes between this event and its `workflow_run.status_ended`.
6124
6125 - `type: "workflow_run.status_idle"`
6126
6127 - `id: string`
6128
6129 Unique identifier for this event.
6130
6131 - `processed_at: string`
6132
6133 Timestamp when this event was processed.
6134
6135 format: date-time
6136
6137 - `workflow_run_id: string`
6138
6139 Identifier of the run. The same value is on all of the run's `workflow_run.*` events.
6140
6141 - `BetaManagedAgentsWorkflowRunErrorEvent object`
6142
6143 A workflow run met an error, or an error kept a run from being created. A run that ends with a `result.type` of `error` emits this event before its `workflow_run.status_ended`, with the same `error`.
6144
6145 - `type: "workflow_run.error"`
6146
6147 - `id: string`
6148
6149 Unique identifier for this event.
6150
6151 - `error: BetaManagedAgentsWorkflowRunError`
6152
6153 Why the run did not finish, or was not created.
6154
6155 - `processed_at: string`
6156
6157 Timestamp when this event was processed.
6158
6159 format: date-time
6160
6161 - `workflow_run_id: string or null`
6162
6163 Identifier of the run that met the error, or `null` when the error kept a run from being created.
53766164
53776165### Example
53786166
53796167
api/beta/sessions/threads/events/list Changed · +833 / -439 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 381
381381
382382 - `custom_tool_use_id: string`
383383
384 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.
384 The id of the `agent.custom_tool_use` event this result corresponds to. It is also listed 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.
385385
386386 - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock`
387387
from line 453
453453
454454 - `BetaManagedAgentsAgentCustomToolUseEvent object`
455455
456 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.
456 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. The client can send it as soon as this event arrives, without waiting for `session.status_idle`.
457457
458458 - `type: "agent.custom_tool_use"`
459459
from line 1395
13951395
13961396 Public `sthr_` ID of the newly created thread.
13971397
1398 - `workflow_run_id: string or null`
1399
1400 Identifier of the workflow run that created the thread, or `null` for any other thread.
1401
13981402 - `BetaManagedAgentsSpanOutcomeEvaluationStartEvent object`
13991403
14001404 Emitted when an outcome evaluation cycle begins.
from line 1899
18951899
18961900 - `"claude-haiku-4-5"`
18971901
1898 Fastest model with near-frontier intelligence
1899
19001902 - `"claude-haiku-4-5-20251001"`
19011903
1902 Fastest model with near-frontier intelligence
1903
19041904 - `"claude-opus-4-5"`
19051905
19061906 Powerful intelligence for long-running agents and coding
from line 1969
19691969
19701970 - `"fast"`
19711971
1972 - `multiagent: BetaManagedAgentsSessionMultiagentCoordinator or null`
1972 - `multiagent: BetaManagedAgentsSessionMultiagent or null`
19731973
19741974 Resolved multiagent orchestration configuration. Null when the agent is single-threaded.
19751975
1976 - `type: "coordinator"`
1977
1978 - `agents: array of BetaManagedAgentsSessionThreadAgent or BetaManagedAgentsAdvisor`
1979
1980 Full `agent` definitions the coordinator may spawn as session threads.
1981
1982 - `BetaManagedAgentsSessionThreadAgent object`
1983
1984 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`.
1985
1986 - `type: "agent"`
1987
1988 - `id: string`
1989
1990 - `description: string or null`
1991
1992 - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition`
1993
1994 - `type: "url"`
1976 - `BetaManagedAgentsSessionMultiagentCoordinator object`
1977
1978 Resolved coordinator topology with full agent definitions for each roster member.
1979
1980 - `type: "coordinator"`
1981
1982 - `agents: array of BetaManagedAgentsSessionThreadAgent or BetaManagedAgentsAdvisor`
1983
1984 Full `agent` definitions the coordinator may spawn as session threads.
1985
1986 - `BetaManagedAgentsSessionThreadAgent object`
1987
1988 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`.
1989
1990 - `type: "agent"`
1991
1992 - `id: string`
1993
1994 - `description: string or null`
1995
1996 - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition`
1997
1998 - `type: "url"`
1999
2000 - `name: string`
2001
2002 - `url: string`
2003
2004 - `model: BetaManagedAgentsModelConfig`
2005
2006 Model identifier and configuration.
19952007
19962008 - `name: string`
19972009
1998 - `url: string`
1999
2000 - `model: BetaManagedAgentsModelConfig`
2001
2002 Model identifier and configuration.
2003
2004 - `name: string`
2005
2006 - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill`
2007
2008 - `BetaManagedAgentsAnthropicSkill object`
2009
2010 A resolved Anthropic-managed skill.
2011
2012 - `type: "anthropic"`
2013
2014 - `skill_id: string`
2015
2016 - `version: string`
2017
2018 - `BetaManagedAgentsCustomSkill object`
2019
2020 A resolved user-created custom skill.
2021
2022 - `type: "custom"`
2023
2024 - `skill_id: string`
2025
2026 - `version: string`
2027
2028 - `system: string or null`
2029
2030 - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool`
2031
2032 - `BetaManagedAgentsAgentToolset20260401 object`
2033
2034 - `type: "agent_toolset_20260401"`
2035
2036 - `configs: array of BetaManagedAgentsAgentToolConfig`
2037
2038 - `BetaManagedAgentsBashToolConfig object`
2039
2040 Configuration for the bash tool.
2041
2042 - `type: "bash"`
2010 - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill`
2011
2012 - `BetaManagedAgentsAnthropicSkill object`
2013
2014 A resolved Anthropic-managed skill.
2015
2016 - `type: "anthropic"`
2017
2018 - `skill_id: string`
2019
2020 - `version: string`
2021
2022 - `BetaManagedAgentsCustomSkill object`
2023
2024 A resolved user-created custom skill.
2025
2026 - `type: "custom"`
2027
2028 - `skill_id: string`
2029
2030 - `version: string`
2031
2032 - `system: string or null`
2033
2034 - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool`
2035
2036 - `BetaManagedAgentsAgentToolset20260401 object`
2037
2038 - `type: "agent_toolset_20260401"`
2039
2040 - `configs: array of BetaManagedAgentsAgentToolConfig`
2041
2042 - `BetaManagedAgentsBashToolConfig object`
2043
2044 Configuration for the bash tool.
2045
2046 - `type: "bash"`
2047
2048 - `enabled: boolean`
2049
2050 - `name: "bash"`
2051
2052 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
2053
2054 Permission policy for tool execution.
2055
2056 - `BetaManagedAgentsAlwaysAllowPolicy object`
2057
2058 Tool calls are automatically approved without user confirmation.
2059
2060 - `type: "always_allow"`
2061
2062 - `BetaManagedAgentsAlwaysAskPolicy object`
2063
2064 Tool calls require user confirmation before execution.
2065
2066 - `type: "always_ask"`
2067
2068 - `BetaManagedAgentsAutoPolicy object`
2069
2070 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.
2071
2072 - `type: "auto"`
2073
2074 - `BetaManagedAgentsEditToolConfig object`
2075
2076 Configuration for the edit tool.
2077
2078 - `type: "edit"`
2079
2080 - `enabled: boolean`
2081
2082 - `name: "edit"`
2083
2084 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
2085
2086 Permission policy for tool execution.
2087
2088 - `BetaManagedAgentsAlwaysAllowPolicy object`
2089
2090 Tool calls are automatically approved without user confirmation.
2091
2092 - `BetaManagedAgentsAlwaysAskPolicy object`
2093
2094 Tool calls require user confirmation before execution.
2095
2096 - `BetaManagedAgentsAutoPolicy object`
2097
2098 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.
2099
2100 - `BetaManagedAgentsReadToolConfig object`
2101
2102 Configuration for the read tool.
2103
2104 - `type: "read"`
2105
2106 - `enabled: boolean`
2107
2108 - `name: "read"`
2109
2110 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
2111
2112 Permission policy for tool execution.
2113
2114 - `BetaManagedAgentsAlwaysAllowPolicy object`
2115
2116 Tool calls are automatically approved without user confirmation.
2117
2118 - `BetaManagedAgentsAlwaysAskPolicy object`
2119
2120 Tool calls require user confirmation before execution.
2121
2122 - `BetaManagedAgentsAutoPolicy object`
2123
2124 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.
2125
2126 - `BetaManagedAgentsWriteToolConfig object`
2127
2128 Configuration for the write tool.
2129
2130 - `type: "write"`
2131
2132 - `enabled: boolean`
2133
2134 - `name: "write"`
2135
2136 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
2137
2138 Permission policy for tool execution.
2139
2140 - `BetaManagedAgentsAlwaysAllowPolicy object`
2141
2142 Tool calls are automatically approved without user confirmation.
2143
2144 - `BetaManagedAgentsAlwaysAskPolicy object`
2145
2146 Tool calls require user confirmation before execution.
2147
2148 - `BetaManagedAgentsAutoPolicy object`
2149
2150 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.
2151
2152 - `BetaManagedAgentsGlobToolConfig object`
2153
2154 Configuration for the glob tool.
2155
2156 - `type: "glob"`
2157
2158 - `enabled: boolean`
2159
2160 - `name: "glob"`
2161
2162 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
2163
2164 Permission policy for tool execution.
2165
2166 - `BetaManagedAgentsAlwaysAllowPolicy object`
2167
2168 Tool calls are automatically approved without user confirmation.
2169
2170 - `BetaManagedAgentsAlwaysAskPolicy object`
2171
2172 Tool calls require user confirmation before execution.
2173
2174 - `BetaManagedAgentsAutoPolicy object`
2175
2176 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.
2177
2178 - `BetaManagedAgentsGrepToolConfig object`
2179
2180 Configuration for the grep tool.
2181
2182 - `type: "grep"`
2183
2184 - `enabled: boolean`
2185
2186 - `name: "grep"`
2187
2188 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
2189
2190 Permission policy for tool execution.
2191
2192 - `BetaManagedAgentsAlwaysAllowPolicy object`
2193
2194 Tool calls are automatically approved without user confirmation.
2195
2196 - `BetaManagedAgentsAlwaysAskPolicy object`
2197
2198 Tool calls require user confirmation before execution.
2199
2200 - `BetaManagedAgentsAutoPolicy object`
2201
2202 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.
2203
2204 - `BetaManagedAgentsWebFetchToolConfig object`
2205
2206 Configuration for the web_fetch tool.
2207
2208 - `type: "web_fetch"`
2209
2210 - `enabled: boolean`
2211
2212 - `name: "web_fetch"`
2213
2214 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
2215
2216 Permission policy for tool execution.
2217
2218 - `BetaManagedAgentsAlwaysAllowPolicy object`
2219
2220 Tool calls are automatically approved without user confirmation.
2221
2222 - `BetaManagedAgentsAlwaysAskPolicy object`
2223
2224 Tool calls require user confirmation before execution.
2225
2226 - `BetaManagedAgentsAutoPolicy object`
2227
2228 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.
2229
2230 - `url_sources: BetaManagedAgentsWebFetchURLSources or null`
2231
2232 Which sources contribute URLs the tool may fetch, always in the object form. Null when not set, which allows every source.
2233
2234 - `client_tool_results: BetaManagedAgentsWebFetchURLSourceToolFilter or null`
2235
2236 Which custom tools' results contribute URLs that may be fetched. Null when not set, which allows every custom tool's results.
2237
2238 - `BetaManagedAgentsWebFetchURLSourceAll object`
2239
2240 Every URL from this source may be fetched. This is the default.
2241
2242 - `type: "all"`
2243
2244 - `BetaManagedAgentsWebFetchURLSourceNone object`
2245
2246 This source contributes no URLs that may be fetched.
2247
2248 - `type: "none"`
2249
2250 - `BetaManagedAgentsWebFetchURLSourceOnly object`
2251
2252 Only the named tools' results contribute URLs that may be fetched.
2253
2254 - `type: "only"`
2255
2256 - `tools: array of BetaManagedAgentsWebFetchURLSourceToolReference`
2257
2258 The tools whose results contribute. Between 1 and 128 entries, each with a different name. An empty list is rejected; use "none" to allow no tool's results.
2259
2260 - `type: "tool_reference"`
2261
2262 Must be "tool_reference".
2263
2264 - `name: string`
2265
2266 Name of the tool. Compared exactly, so upper and lower case letters are different.
2267
2268 minLength: 1, maxLength: 128
2269
2270 - `BetaManagedAgentsWebFetchURLSourceExcept object`
2271
2272 Every tool's results contribute URLs that may be fetched, except the named tools' results.
2273
2274 - `type: "except"`
2275
2276 - `tools: array of BetaManagedAgentsWebFetchURLSourceToolReference`
2277
2278 The tools whose results do not contribute. Between 1 and 128 entries, each with a different name. An empty list is rejected; use "all" to leave out no tool's results.
2279
2280 - `type: "tool_reference"`
2281
2282 Must be "tool_reference".
2283
2284 - `name: string`
2285
2286 Name of the tool. Compared exactly, so upper and lower case letters are different.
2287
2288 minLength: 1, maxLength: 128
2289
2290 - `server_tool_results: BetaManagedAgentsWebFetchURLSourceToolFilter or null`
2291
2292 Which of the web_search and web_fetch tools' results contribute URLs that may be fetched. Null when not set, which allows both.
2293
2294 - `user_input: BetaManagedAgentsWebFetchURLSourceUserInput or null`
2295
2296 Whether URLs in the text of user messages may be fetched. Null when not set, which allows them.
2297
2298 - `BetaManagedAgentsWebFetchURLSourceAll object`
2299
2300 Every URL from this source may be fetched. This is the default.
2301
2302 - `BetaManagedAgentsWebFetchURLSourceNone object`
2303
2304 This source contributes no URLs that may be fetched.
2305
2306 - `allowed_domains: optional array of string`
2307
2308 - `blocked_domains: optional array of string`
2309
2310 - `max_content_tokens: optional number or null`
2311
2312 format: int32
2313
2314 - `BetaManagedAgentsWebSearchToolConfig object`
2315
2316 Configuration for the web_search tool.
2317
2318 - `type: "web_search"`
2319
2320 - `enabled: boolean`
2321
2322 - `name: "web_search"`
2323
2324 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
2325
2326 Permission policy for tool execution.
2327
2328 - `BetaManagedAgentsAlwaysAllowPolicy object`
2329
2330 Tool calls are automatically approved without user confirmation.
2331
2332 - `BetaManagedAgentsAlwaysAskPolicy object`
2333
2334 Tool calls require user confirmation before execution.
2335
2336 - `BetaManagedAgentsAutoPolicy object`
2337
2338 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.
2339
2340 - `allowed_domains: optional array of string`
2341
2342 - `blocked_domains: optional array of string`
2343
2344 - `user_location: optional BetaManagedAgentsUserLocation or null`
2345
2346 Approximate user location for search result localization.
2347
2348 - `type: "approximate"`
2349
2350 Location precision. Only "approximate" is supported.
2351
2352 - `city: optional string or null`
2353
2354 City name.
2355
2356 minLength: 1, maxLength: 255
2357
2358 - `country: optional string or null`
2359
2360 Two-letter ISO 3166-1 country code, uppercase.
2361
2362 - `region: optional string or null`
2363
2364 Region or state name.
2365
2366 minLength: 1, maxLength: 255
2367
2368 - `timezone: optional string or null`
2369
2370 IANA timezone identifier, e.g. "America/Los_Angeles".
2371
2372 minLength: 1, maxLength: 255
2373
2374 - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig`
2375
2376 Resolved default configuration for agent tools.
20432377
20442378 - `enabled: boolean`
20452379
2046 - `name: "bash"`
2047
20482380 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
20492381
20502382 Permission policy for tool execution.
from line 2385
20532385
20542386 Tool calls are automatically approved without user confirmation.
20552387
2056 - `type: "always_allow"`
2057
20582388 - `BetaManagedAgentsAlwaysAskPolicy object`
20592389
20602390 Tool calls require user confirmation before execution.
20612391
2062 - `type: "always_ask"`
2063
20642392 - `BetaManagedAgentsAutoPolicy object`
20652393
20662394 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.
20672395
2068 - `type: "auto"`
2069
2070 - `BetaManagedAgentsEditToolConfig object`
2071
2072 Configuration for the edit tool.
2073
2074 - `type: "edit"`
2396 - `BetaManagedAgentsMCPToolset object`
2397
2398 - `type: "mcp_toolset"`
2399
2400 - `configs: array of BetaManagedAgentsMCPToolConfig`
20752401
20762402 - `enabled: boolean`
20772403
2078 - `name: "edit"`
2404 - `name: string`
20792405
20802406 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
20812407
from line 2419
20932419
20942420 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.
20952421
2096 - `BetaManagedAgentsReadToolConfig object`
2097
2098 Configuration for the read tool.
2099
2100 - `type: "read"`
2422 - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig`
2423
2424 Resolved default configuration for all tools from an MCP server.
21012425
21022426 - `enabled: boolean`
21032427
2104 - `name: "read"`
2105
21062428 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
21072429
21082430 Permission policy for tool execution.
from line 2441
21192441
21202442 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.
21212443
2122 - `BetaManagedAgentsWriteToolConfig object`
2123
2124 Configuration for the write tool.
2125
2126 - `type: "write"`
2127
2128 - `enabled: boolean`
2129
2130 - `name: "write"`
2131
2132 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
2133
2134 Permission policy for tool execution.
2135
2136 - `BetaManagedAgentsAlwaysAllowPolicy object`
2137
2138 Tool calls are automatically approved without user confirmation.
2139
2140 - `BetaManagedAgentsAlwaysAskPolicy object`
2141
2142 Tool calls require user confirmation before execution.
2143
2144 - `BetaManagedAgentsAutoPolicy object`
2145
2146 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.
2147
2148 - `BetaManagedAgentsGlobToolConfig object`
2149
2150 Configuration for the glob tool.
2151
2152 - `type: "glob"`
2153
2154 - `enabled: boolean`
2155
2156 - `name: "glob"`
2157
2158 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
2159
2160 Permission policy for tool execution.
2161
2162 - `BetaManagedAgentsAlwaysAllowPolicy object`
2163
2164 Tool calls are automatically approved without user confirmation.
2165
2166 - `BetaManagedAgentsAlwaysAskPolicy object`
2167
2168 Tool calls require user confirmation before execution.
2169
2170 - `BetaManagedAgentsAutoPolicy object`
2171
2172 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.
2173
2174 - `BetaManagedAgentsGrepToolConfig object`
2175
2176 Configuration for the grep tool.
2177
2178 - `type: "grep"`
2179
2180 - `enabled: boolean`
2181
2182 - `name: "grep"`
2183
2184 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
2185
2186 Permission policy for tool execution.
2187
2188 - `BetaManagedAgentsAlwaysAllowPolicy object`
2189
2190 Tool calls are automatically approved without user confirmation.
2191
2192 - `BetaManagedAgentsAlwaysAskPolicy object`
2193
2194 Tool calls require user confirmation before execution.
2195
2196 - `BetaManagedAgentsAutoPolicy object`
2197
2198 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.
2199
2200 - `BetaManagedAgentsWebFetchToolConfig object`
2201
2202 Configuration for the web_fetch tool.
2203
2204 - `type: "web_fetch"`
2205
2206 - `enabled: boolean`
2207
2208 - `name: "web_fetch"`
2209
2210 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
2211
2212 Permission policy for tool execution.
2213
2214 - `BetaManagedAgentsAlwaysAllowPolicy object`
2215
2216 Tool calls are automatically approved without user confirmation.
2217
2218 - `BetaManagedAgentsAlwaysAskPolicy object`
2219
2220 Tool calls require user confirmation before execution.
2221
2222 - `BetaManagedAgentsAutoPolicy object`
2223
2224 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.
2225
2226 - `url_sources: BetaManagedAgentsWebFetchURLSources or null`
2227
2228 Which sources contribute URLs the tool may fetch, always in the object form. Null when not set, which allows every source.
2229
2230 - `client_tool_results: BetaManagedAgentsWebFetchURLSourceToolFilter or null`
2231
2232 Which custom tools' results contribute URLs that may be fetched. Null when not set, which allows every custom tool's results.
2233
2234 - `BetaManagedAgentsWebFetchURLSourceAll object`
2235
2236 Every URL from this source may be fetched. This is the default.
2237
2238 - `type: "all"`
2239
2240 - `BetaManagedAgentsWebFetchURLSourceNone object`
2241
2242 This source contributes no URLs that may be fetched.
2243
2244 - `type: "none"`
2245
2246 - `BetaManagedAgentsWebFetchURLSourceOnly object`
2247
2248 Only the named tools' results contribute URLs that may be fetched.
2249
2250 - `type: "only"`
2251
2252 - `tools: array of BetaManagedAgentsWebFetchURLSourceToolReference`
2253
2254 The tools whose results contribute. Between 1 and 128 entries, each with a different name. An empty list is rejected; use "none" to allow no tool's results.
2255
2256 - `type: "tool_reference"`
2257
2258 Must be "tool_reference".
2259
2260 - `name: string`
2261
2262 Name of the tool. Compared exactly, so upper and lower case letters are different.
2263
2264 minLength: 1, maxLength: 128
2265
2266 - `BetaManagedAgentsWebFetchURLSourceExcept object`
2267
2268 Every tool's results contribute URLs that may be fetched, except the named tools' results.
2269
2270 - `type: "except"`
2271
2272 - `tools: array of BetaManagedAgentsWebFetchURLSourceToolReference`
2273
2274 The tools whose results do not contribute. Between 1 and 128 entries, each with a different name. An empty list is rejected; use "all" to leave out no tool's results.
2275
2276 - `type: "tool_reference"`
2277
2278 Must be "tool_reference".
2279
2280 - `name: string`
2281
2282 Name of the tool. Compared exactly, so upper and lower case letters are different.
2283
2284 minLength: 1, maxLength: 128
2285
2286 - `server_tool_results: BetaManagedAgentsWebFetchURLSourceToolFilter or null`
2287
2288 Which of the web_search and web_fetch tools' results contribute URLs that may be fetched. Null when not set, which allows both.
2289
2290 - `user_input: BetaManagedAgentsWebFetchURLSourceUserInput or null`
2291
2292 Whether URLs in the text of user messages may be fetched. Null when not set, which allows them.
2293
2294 - `BetaManagedAgentsWebFetchURLSourceAll object`
2295
2296 Every URL from this source may be fetched. This is the default.
2297
2298 - `BetaManagedAgentsWebFetchURLSourceNone object`
2299
2300 This source contributes no URLs that may be fetched.
2301
2302 - `allowed_domains: optional array of string`
2303
2304 - `blocked_domains: optional array of string`
2305
2306 - `max_content_tokens: optional number or null`
2307
2308 format: int32
2309
2310 - `BetaManagedAgentsWebSearchToolConfig object`
2311
2312 Configuration for the web_search tool.
2313
2314 - `type: "web_search"`
2315
2316 - `enabled: boolean`
2317
2318 - `name: "web_search"`
2319
2320 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
2321
2322 Permission policy for tool execution.
2323
2324 - `BetaManagedAgentsAlwaysAllowPolicy object`
2325
2326 Tool calls are automatically approved without user confirmation.
2327
2328 - `BetaManagedAgentsAlwaysAskPolicy object`
2329
2330 Tool calls require user confirmation before execution.
2331
2332 - `BetaManagedAgentsAutoPolicy object`
2333
2334 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.
2335
2336 - `allowed_domains: optional array of string`
2337
2338 - `blocked_domains: optional array of string`
2339
2340 - `user_location: optional BetaManagedAgentsUserLocation or null`
2341
2342 Approximate user location for search result localization.
2343
2344 - `type: "approximate"`
2345
2346 Location precision. Only "approximate" is supported.
2347
2348 - `city: optional string or null`
2349
2350 City name.
2351
2352 minLength: 1, maxLength: 255
2353
2354 - `country: optional string or null`
2355
2356 Two-letter ISO 3166-1 country code, uppercase.
2357
2358 - `region: optional string or null`
2359
2360 Region or state name.
2361
2362 minLength: 1, maxLength: 255
2363
2364 - `timezone: optional string or null`
2365
2366 IANA timezone identifier, e.g. "America/Los_Angeles".
2367
2368 minLength: 1, maxLength: 255
2369
2370 - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig`
2371
2372 Resolved default configuration for agent tools.
2373
2374 - `enabled: boolean`
2375
2376 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
2377
2378 Permission policy for tool execution.
2379
2380 - `BetaManagedAgentsAlwaysAllowPolicy object`
2381
2382 Tool calls are automatically approved without user confirmation.
2383
2384 - `BetaManagedAgentsAlwaysAskPolicy object`
2385
2386 Tool calls require user confirmation before execution.
2387
2388 - `BetaManagedAgentsAutoPolicy object`
2389
2390 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.
2391
2392 - `BetaManagedAgentsMCPToolset object`
2393
2394 - `type: "mcp_toolset"`
2395
2396 - `configs: array of BetaManagedAgentsMCPToolConfig`
2397
2398 - `enabled: boolean`
2444 - `mcp_server_name: string`
2445
2446 - `BetaManagedAgentsCustomTool object`
2447
2448 A custom tool as returned in API responses.
2449
2450 - `type: "custom"`
2451
2452 - `description: string`
2453
2454 - `input_schema: BetaManagedAgentsCustomToolInputSchema`
2455
2456 JSON Schema for custom tool input parameters.
2457
2458 - `type: "object"`
2459
2460 - `properties: optional map[unknown] or null`
2461
2462 - `required: optional array of string or null`
23992463
24002464 - `name: string`
24012465
2402 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
2403
2404 Permission policy for tool execution.
2405
2406 - `BetaManagedAgentsAlwaysAllowPolicy object`
2407
2408 Tool calls are automatically approved without user confirmation.
2409
2410 - `BetaManagedAgentsAlwaysAskPolicy object`
2411
2412 Tool calls require user confirmation before execution.
2413
2414 - `BetaManagedAgentsAutoPolicy object`
2415
2416 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.
2417
2418 - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig`
2419
2420 Resolved default configuration for all tools from an MCP server.
2421
2422 - `enabled: boolean`
2423
2424 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
2425
2426 Permission policy for tool execution.
2427
2428 - `BetaManagedAgentsAlwaysAllowPolicy object`
2429
2430 Tool calls are automatically approved without user confirmation.
2431
2432 - `BetaManagedAgentsAlwaysAskPolicy object`
2433
2434 Tool calls require user confirmation before execution.
2435
2436 - `BetaManagedAgentsAutoPolicy object`
2437
2438 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.
2439
2440 - `mcp_server_name: string`
2441
2442 - `BetaManagedAgentsCustomTool object`
2443
2444 A custom tool as returned in API responses.
2445
2446 - `type: "custom"`
2447
2448 - `description: string`
2449
2450 - `input_schema: BetaManagedAgentsCustomToolInputSchema`
2451
2452 JSON Schema for custom tool input parameters.
2453
2454 - `type: "object"`
2455
2456 - `properties: optional map[unknown] or null`
2457
2458 - `required: optional array of string or null`
2466 - `version: number`
2467
2468 format: int32
2469
2470 - `BetaManagedAgentsAdvisor object`
2471
2472 Platform advisor roster entry: a model the session's primary thread may consult mid-turn.
2473
2474 - `type: "advisor"`
2475
2476 - `model: string`
2477
2478 The advisor model id.
2479
2480 - `BetaManagedAgentsSessionMultiagent20261001 object`
2481
2482 Resolved multiagent configuration with three members, as copied to the `session` at creation.
2483
2484 - `type: "multiagent_20261001"`
2485
2486 - `advisor: BetaManagedAgentsMultiagentAdvisor`
2487
2488 Whether the session's primary thread can consult an advisor model.
2489
2490 - `BetaManagedAgentsMultiagentAdvisorEnabled object`
2491
2492 The session's primary thread can consult `model` mid-turn.
2493
2494 - `type: "enabled"`
2495
2496 - `model: string`
2497
2498 The advisor model id.
2499
2500 - `BetaManagedAgentsMultiagentAdvisorDisabled object`
2501
2502 The agent has no advisor.
2503
2504 - `type: "disabled"`
2505
2506 - `subagents: BetaManagedAgentsSessionMultiagentSubagents`
2507
2508 Whether the agent can spawn session threads.
2509
2510 - `BetaManagedAgentsSessionMultiagentSubagentsEnabled object`
2511
2512 The agent can spawn session threads.
2513
2514 - `type: "enabled"`
2515
2516 - `inline_agents: BetaManagedAgentsMultiagentInlineAgents`
2517
2518 Whether the agent can define inline agents, which are not saved, when it spawns session threads.
2519
2520 - `BetaManagedAgentsMultiagentInlineAgentsEnabled object`
2521
2522 The agent can define inline agents.
2523
2524 - `type: "enabled"`
2525
2526 - `BetaManagedAgentsMultiagentInlineAgentsDisabled object`
2527
2528 The agent cannot define inline agents.
2529
2530 - `type: "disabled"`
2531
2532 - `predefined_agents: array of BetaManagedAgentsSessionThreadAgent`
2533
2534 Full `agent` definitions of the predefined agents, which are saved agents that this agent can spawn as session threads.
2535
2536 - `type: "agent"`
2537
2538 - `id: string`
2539
2540 - `description: string or null`
2541
2542 - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition`
2543
2544 - `model: BetaManagedAgentsModelConfig`
2545
2546 Model identifier and configuration.
24592547
24602548 - `name: string`
24612549
2462 - `version: number`
2463
2464 format: int32
2465
2466 - `BetaManagedAgentsAdvisor object`
2467
2468 Platform advisor roster entry: a model the session's primary thread may consult mid-turn.
2469
2470 - `type: "advisor"`
2471
2472 - `model: string`
2473
2474 The advisor model id.
2550 - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill`
2551
2552 - `system: string or null`
2553
2554 - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool`
2555
2556 - `version: number`
2557
2558 format: int32
2559
2560 - `BetaManagedAgentsMultiagentSubagentsDisabled object`
2561
2562 The agent cannot spawn session threads.
2563
2564 - `type: "disabled"`
2565
2566 - `workflows: BetaManagedAgentsSessionMultiagentWorkflows`
2567
2568 Whether the agent can start workflow runs.
2569
2570 - `BetaManagedAgentsSessionMultiagentWorkflowsEnabled object`
2571
2572 The agent can start workflow runs.
2573
2574 - `type: "enabled"`
2575
2576 - `inline_agents: BetaManagedAgentsMultiagentInlineAgents`
2577
2578 Whether a run's plan can define inline agents, which are not saved.
2579
2580 - `predefined_agents: array of BetaManagedAgentsSessionThreadAgent`
2581
2582 Full `agent` definitions of the predefined agents, which are saved agents that a run's plan can use.
2583
2584 - `type: "agent"`
2585
2586 - `id: string`
2587
2588 - `description: string or null`
2589
2590 - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition`
2591
2592 - `model: BetaManagedAgentsModelConfig`
2593
2594 Model identifier and configuration.
2595
2596 - `name: string`
2597
2598 - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill`
2599
2600 - `system: string or null`
2601
2602 - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool`
2603
2604 - `version: number`
2605
2606 format: int32
2607
2608 - `BetaManagedAgentsMultiagentWorkflowsDisabled object`
2609
2610 The agent cannot start workflow runs.
2611
2612 - `type: "disabled"`
24752613
24762614 - `name: string`
24772615
from line 2776
26382776 - `budget: optional BetaManagedAgentsBudgetLimit or null`
26392777
26402778 The session's configured budget at the snapshot time, or null when the session has no budget.
2779
2780 - `BetaManagedAgentsWorkflowRunCreatedEvent object`
2781
2782 A workflow run was created. A workflow run is background work that the session's agent starts. Emitted once per run, before the run's other `workflow_run.*` events.
2783
2784 - `type: "workflow_run.created"`
2785
2786 - `id: string`
2787
2788 Unique identifier for this event.
2789
2790 - `description: string or null`
2791
2792 Description that the agent gave the run, passed on as written, or `null` if it gave none.
2793
2794 - `name: string`
2795
2796 Name that the agent gave the run, passed on as written, or a name that the server assigned.
2797
2798 - `phases: array of BetaManagedAgentsWorkflowRunPhase`
2799
2800 The phases that the run's plan declares, in the plan's order. Can be empty.
2801
2802 - `id: string`
2803
2804 Unique identifier for the phase.
2805
2806 - `description: string or null`
2807
2808 Description that the agent gave the phase, passed on as written, or `null` if it gave none.
2809
2810 - `name: string`
2811
2812 Name that the agent gave the phase, passed on as written.
2813
2814 - `processed_at: string`
2815
2816 Timestamp when this event was processed.
2817
2818 format: date-time
2819
2820 - `workflow_run_id: string`
2821
2822 Identifier of the run. The same value is on all of the run's `workflow_run.*` events.
2823
2824 - `BetaManagedAgentsWorkflowRunStatusEndedEvent object`
2825
2826 A workflow run ended. Emitted once per run, as the last of the run's `workflow_run.*` events.
2827
2828 - `type: "workflow_run.status_ended"`
2829
2830 - `id: string`
2831
2832 Unique identifier for this event.
2833
2834 - `processed_at: string`
2835
2836 Timestamp when this event was processed.
2837
2838 format: date-time
2839
2840 - `result: BetaManagedAgentsWorkflowRunResult`
2841
2842 How the run ended.
2843
2844 - `BetaManagedAgentsWorkflowRunResultCompleted object`
2845
2846 The run's plan, a program that the agent wrote, finished. This does not say whether the work succeeded.
2847
2848 - `type: "completed"`
2849
2850 - `BetaManagedAgentsWorkflowRunResultError object`
2851
2852 The run failed or reached its time limit.
2853
2854 - `type: "error"`
2855
2856 - `error: BetaManagedAgentsWorkflowRunError`
2857
2858 Why the run did not finish.
2859
2860 - `BetaManagedAgentsTimeoutWorkflowRunError object`
2861
2862 The run reached its time limit.
2863
2864 - `type: "timeout_error"`
2865
2866 - `message: string`
2867
2868 Short explanation written by the server. It never contains content from the run or its agents.
2869
2870 - `BetaManagedAgentsProgramWorkflowRunError object`
2871
2872 The plan, a program that the agent wrote, failed, or the server refused it.
2873
2874 - `type: "program_error"`
2875
2876 - `message: string`
2877
2878 Short explanation written by the server. It never contains content from the run or its agents.
2879
2880 - `BetaManagedAgentsUnknownWorkflowRunError object`
2881
2882 A failure that has no type of its own.
2883
2884 - `type: "unknown_error"`
2885
2886 - `message: string`
2887
2888 Short explanation written by the server. It never contains content from the run or its agents.
2889
2890 - `BetaManagedAgentsThreadLimitWorkflowRunError object`
2891
2892 The run exceeded the limit on the number of threads that a run can create.
2893
2894 - `type: "thread_limit_error"`
2895
2896 - `message: string`
2897
2898 Short explanation written by the server. It never contains content from the run or its agents.
2899
2900 - `BetaManagedAgentsMaxWorkflowRunsWorkflowRunError object`
2901
2902 No run was created, because the session was at its limit of open workflow runs, which are runs that have not ended. Only `workflow_run.error` carries this type.
2903
2904 - `type: "max_workflow_runs_error"`
2905
2906 - `message: string`
2907
2908 Short explanation written by the server. It never contains content from the run or its agents.
2909
2910 - `BetaManagedAgentsWorkflowRunResultStopped object`
2911
2912 The agent stopped the run.
2913
2914 - `type: "stopped"`
2915
2916 - `workflow_run_id: string`
2917
2918 Identifier of the run. The same value is on all of the run's `workflow_run.*` events.
2919
2920 - `BetaManagedAgentsWorkflowRunPhaseStartedEvent object`
2921
2922 A workflow run's plan entered a phase.
2923
2924 - `type: "workflow_run.phase_started"`
2925
2926 - `id: string`
2927
2928 Unique identifier for this event.
2929
2930 - `processed_at: string`
2931
2932 Timestamp when this event was processed.
2933
2934 format: date-time
2935
2936 - `workflow_run_id: string`
2937
2938 Identifier of the run. The same value is on all of the run's `workflow_run.*` events.
2939
2940 - `workflow_run_phase_id: string`
2941
2942 Identifier of the phase, as in `phases` on the run's `workflow_run.created` event.
2943
2944 - `BetaManagedAgentsWorkflowRunPhaseEndedEvent object`
2945
2946 A workflow run's plan left a phase, or the run's end closed it. Emitted once for every `workflow_run.phase_started` event, before the run's `workflow_run.status_ended` event. The event does not say whether the plan finished the phase's work, or why it left.
2947
2948 - `type: "workflow_run.phase_ended"`
2949
2950 - `id: string`
2951
2952 Unique identifier for this event.
2953
2954 - `phase_started_id: string`
2955
2956 Identifier of the `workflow_run.phase_started` event that opened the phase.
2957
2958 - `processed_at: string`
2959
2960 Timestamp when this event was processed.
2961
2962 format: date-time
2963
2964 - `workflow_run_id: string`
2965
2966 Identifier of the run. The same value is on all of the run's `workflow_run.*` events.
2967
2968 - `workflow_run_phase_id: string`
2969
2970 Identifier of the phase, as in `phases` on the run's `workflow_run.created` event.
2971
2972 - `BetaManagedAgentsWorkflowRunStatusRunningEvent object`
2973
2974 A workflow run is running. Emitted when the run starts to execute, and each time it resumes after being idle. A run that starts idle emits `workflow_run.status_idle` first.
2975
2976 - `type: "workflow_run.status_running"`
2977
2978 - `id: string`
2979
2980 Unique identifier for this event.
2981
2982 - `processed_at: string`
2983
2984 Timestamp when this event was processed.
2985
2986 format: date-time
2987
2988 - `workflow_run_id: string`
2989
2990 Identifier of the run. The same value is on all of the run's `workflow_run.*` events.
2991
2992 - `BetaManagedAgentsWorkflowRunStatusIdleEvent object`
2993
2994 A workflow run is idle. Emitted each time the run goes idle, whatever the cause. If the run ends while idle, no `workflow_run.status_running` comes between this event and its `workflow_run.status_ended`.
2995
2996 - `type: "workflow_run.status_idle"`
2997
2998 - `id: string`
2999
3000 Unique identifier for this event.
3001
3002 - `processed_at: string`
3003
3004 Timestamp when this event was processed.
3005
3006 format: date-time
3007
3008 - `workflow_run_id: string`
3009
3010 Identifier of the run. The same value is on all of the run's `workflow_run.*` events.
3011
3012 - `BetaManagedAgentsWorkflowRunErrorEvent object`
3013
3014 A workflow run met an error, or an error kept a run from being created. A run that ends with a `result.type` of `error` emits this event before its `workflow_run.status_ended`, with the same `error`.
3015
3016 - `type: "workflow_run.error"`
3017
3018 - `id: string`
3019
3020 Unique identifier for this event.
3021
3022 - `error: BetaManagedAgentsWorkflowRunError`
3023
3024 Why the run did not finish, or was not created.
3025
3026 - `processed_at: string`
3027
3028 Timestamp when this event was processed.
3029
3030 format: date-time
3031
3032 - `workflow_run_id: string or null`
3033
3034 Identifier of the run that met the error, or `null` when the error kept a run from being created.
26413035
26423036- `next_page: optional string or null`
26433037
26443038
api/beta/sessions/threads/events/stream Changed · +834 / -440 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 143
143143
144144## Returns
145145
146- `BetaManagedAgentsStreamSessionThreadEvents = BetaManagedAgentsUserMessageEvent or BetaManagedAgentsUserInterruptEvent or BetaManagedAgentsUserToolConfirmationEvent or 34 more`
146- `BetaManagedAgentsStreamSessionThreadEvents = BetaManagedAgentsUserMessageEvent or BetaManagedAgentsUserInterruptEvent or BetaManagedAgentsUserToolConfirmationEvent or 41 more`
147147
148148 Server-sent event in a single thread's stream.
149149
from line 383
383383
384384 - `custom_tool_use_id: string`
385385
386 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.
386 The id of the `agent.custom_tool_use` event this result corresponds to. It is also listed 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.
387387
388388 - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock`
389389
from line 455
455455
456456 - `BetaManagedAgentsAgentCustomToolUseEvent object`
457457
458 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.
458 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. The client can send it as soon as this event arrives, without waiting for `session.status_idle`.
459459
460460 - `type: "agent.custom_tool_use"`
461461
from line 1397
13971397
13981398 Public `sthr_` ID of the newly created thread.
13991399
1400 - `workflow_run_id: string or null`
1401
1402 Identifier of the workflow run that created the thread, or `null` for any other thread.
1403
14001404 - `BetaManagedAgentsSpanOutcomeEvaluationStartEvent object`
14011405
14021406 Emitted when an outcome evaluation cycle begins.
from line 1901
18971901
18981902 - `"claude-haiku-4-5"`
18991903
1900 Fastest model with near-frontier intelligence
1901
19021904 - `"claude-haiku-4-5-20251001"`
19031905
1904 Fastest model with near-frontier intelligence
1905
19061906 - `"claude-opus-4-5"`
19071907
19081908 Powerful intelligence for long-running agents and coding
from line 1971
19711971
19721972 - `"fast"`
19731973
1974 - `multiagent: BetaManagedAgentsSessionMultiagentCoordinator or null`
1974 - `multiagent: BetaManagedAgentsSessionMultiagent or null`
19751975
19761976 Resolved multiagent orchestration configuration. Null when the agent is single-threaded.
19771977
1978 - `type: "coordinator"`
1979
1980 - `agents: array of BetaManagedAgentsSessionThreadAgent or BetaManagedAgentsAdvisor`
1981
1982 Full `agent` definitions the coordinator may spawn as session threads.
1983
1984 - `BetaManagedAgentsSessionThreadAgent object`
1985
1986 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`.
1987
1988 - `type: "agent"`
1989
1990 - `id: string`
1991
1992 - `description: string or null`
1993
1994 - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition`
1995
1996 - `type: "url"`
1978 - `BetaManagedAgentsSessionMultiagentCoordinator object`
1979
1980 Resolved coordinator topology with full agent definitions for each roster member.
1981
1982 - `type: "coordinator"`
1983
1984 - `agents: array of BetaManagedAgentsSessionThreadAgent or BetaManagedAgentsAdvisor`
1985
1986 Full `agent` definitions the coordinator may spawn as session threads.
1987
1988 - `BetaManagedAgentsSessionThreadAgent object`
1989
1990 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`.
1991
1992 - `type: "agent"`
1993
1994 - `id: string`
1995
1996 - `description: string or null`
1997
1998 - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition`
1999
2000 - `type: "url"`
2001
2002 - `name: string`
2003
2004 - `url: string`
2005
2006 - `model: BetaManagedAgentsModelConfig`
2007
2008 Model identifier and configuration.
19972009
19982010 - `name: string`
19992011
2000 - `url: string`
2001
2002 - `model: BetaManagedAgentsModelConfig`
2003
2004 Model identifier and configuration.
2005
2006 - `name: string`
2007
2008 - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill`
2009
2010 - `BetaManagedAgentsAnthropicSkill object`
2011
2012 A resolved Anthropic-managed skill.
2013
2014 - `type: "anthropic"`
2015
2016 - `skill_id: string`
2017
2018 - `version: string`
2019
2020 - `BetaManagedAgentsCustomSkill object`
2021
2022 A resolved user-created custom skill.
2023
2024 - `type: "custom"`
2025
2026 - `skill_id: string`
2027
2028 - `version: string`
2029
2030 - `system: string or null`
2031
2032 - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool`
2033
2034 - `BetaManagedAgentsAgentToolset20260401 object`
2035
2036 - `type: "agent_toolset_20260401"`
2037
2038 - `configs: array of BetaManagedAgentsAgentToolConfig`
2039
2040 - `BetaManagedAgentsBashToolConfig object`
2041
2042 Configuration for the bash tool.
2043
2044 - `type: "bash"`
2012 - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill`
2013
2014 - `BetaManagedAgentsAnthropicSkill object`
2015
2016 A resolved Anthropic-managed skill.
2017
2018 - `type: "anthropic"`
2019
2020 - `skill_id: string`
2021
2022 - `version: string`
2023
2024 - `BetaManagedAgentsCustomSkill object`
2025
2026 A resolved user-created custom skill.
2027
2028 - `type: "custom"`
2029
2030 - `skill_id: string`
2031
2032 - `version: string`
2033
2034 - `system: string or null`
2035
2036 - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool`
2037
2038 - `BetaManagedAgentsAgentToolset20260401 object`
2039
2040 - `type: "agent_toolset_20260401"`
2041
2042 - `configs: array of BetaManagedAgentsAgentToolConfig`
2043
2044 - `BetaManagedAgentsBashToolConfig object`
2045
2046 Configuration for the bash tool.
2047
2048 - `type: "bash"`
2049
2050 - `enabled: boolean`
2051
2052 - `name: "bash"`
2053
2054 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
2055
2056 Permission policy for tool execution.
2057
2058 - `BetaManagedAgentsAlwaysAllowPolicy object`
2059
2060 Tool calls are automatically approved without user confirmation.
2061
2062 - `type: "always_allow"`
2063
2064 - `BetaManagedAgentsAlwaysAskPolicy object`
2065
2066 Tool calls require user confirmation before execution.
2067
2068 - `type: "always_ask"`
2069
2070 - `BetaManagedAgentsAutoPolicy object`
2071
2072 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.
2073
2074 - `type: "auto"`
2075
2076 - `BetaManagedAgentsEditToolConfig object`
2077
2078 Configuration for the edit tool.
2079
2080 - `type: "edit"`
2081
2082 - `enabled: boolean`
2083
2084 - `name: "edit"`
2085
2086 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
2087
2088 Permission policy for tool execution.
2089
2090 - `BetaManagedAgentsAlwaysAllowPolicy object`
2091
2092 Tool calls are automatically approved without user confirmation.
2093
2094 - `BetaManagedAgentsAlwaysAskPolicy object`
2095
2096 Tool calls require user confirmation before execution.
2097
2098 - `BetaManagedAgentsAutoPolicy object`
2099
2100 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.
2101
2102 - `BetaManagedAgentsReadToolConfig object`
2103
2104 Configuration for the read tool.
2105
2106 - `type: "read"`
2107
2108 - `enabled: boolean`
2109
2110 - `name: "read"`
2111
2112 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
2113
2114 Permission policy for tool execution.
2115
2116 - `BetaManagedAgentsAlwaysAllowPolicy object`
2117
2118 Tool calls are automatically approved without user confirmation.
2119
2120 - `BetaManagedAgentsAlwaysAskPolicy object`
2121
2122 Tool calls require user confirmation before execution.
2123
2124 - `BetaManagedAgentsAutoPolicy object`
2125
2126 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.
2127
2128 - `BetaManagedAgentsWriteToolConfig object`
2129
2130 Configuration for the write tool.
2131
2132 - `type: "write"`
2133
2134 - `enabled: boolean`
2135
2136 - `name: "write"`
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 - `BetaManagedAgentsGlobToolConfig object`
2155
2156 Configuration for the glob tool.
2157
2158 - `type: "glob"`
2159
2160 - `enabled: boolean`
2161
2162 - `name: "glob"`
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 - `BetaManagedAgentsGrepToolConfig object`
2181
2182 Configuration for the grep tool.
2183
2184 - `type: "grep"`
2185
2186 - `enabled: boolean`
2187
2188 - `name: "grep"`
2189
2190 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
2191
2192 Permission policy for tool execution.
2193
2194 - `BetaManagedAgentsAlwaysAllowPolicy object`
2195
2196 Tool calls are automatically approved without user confirmation.
2197
2198 - `BetaManagedAgentsAlwaysAskPolicy object`
2199
2200 Tool calls require user confirmation before execution.
2201
2202 - `BetaManagedAgentsAutoPolicy object`
2203
2204 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.
2205
2206 - `BetaManagedAgentsWebFetchToolConfig object`
2207
2208 Configuration for the web_fetch tool.
2209
2210 - `type: "web_fetch"`
2211
2212 - `enabled: boolean`
2213
2214 - `name: "web_fetch"`
2215
2216 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
2217
2218 Permission policy for tool execution.
2219
2220 - `BetaManagedAgentsAlwaysAllowPolicy object`
2221
2222 Tool calls are automatically approved without user confirmation.
2223
2224 - `BetaManagedAgentsAlwaysAskPolicy object`
2225
2226 Tool calls require user confirmation before execution.
2227
2228 - `BetaManagedAgentsAutoPolicy object`
2229
2230 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.
2231
2232 - `url_sources: BetaManagedAgentsWebFetchURLSources or null`
2233
2234 Which sources contribute URLs the tool may fetch, always in the object form. Null when not set, which allows every source.
2235
2236 - `client_tool_results: BetaManagedAgentsWebFetchURLSourceToolFilter or null`
2237
2238 Which custom tools' results contribute URLs that may be fetched. Null when not set, which allows every custom tool's results.
2239
2240 - `BetaManagedAgentsWebFetchURLSourceAll object`
2241
2242 Every URL from this source may be fetched. This is the default.
2243
2244 - `type: "all"`
2245
2246 - `BetaManagedAgentsWebFetchURLSourceNone object`
2247
2248 This source contributes no URLs that may be fetched.
2249
2250 - `type: "none"`
2251
2252 - `BetaManagedAgentsWebFetchURLSourceOnly object`
2253
2254 Only the named tools' results contribute URLs that may be fetched.
2255
2256 - `type: "only"`
2257
2258 - `tools: array of BetaManagedAgentsWebFetchURLSourceToolReference`
2259
2260 The tools whose results contribute. Between 1 and 128 entries, each with a different name. An empty list is rejected; use "none" to allow no tool's results.
2261
2262 - `type: "tool_reference"`
2263
2264 Must be "tool_reference".
2265
2266 - `name: string`
2267
2268 Name of the tool. Compared exactly, so upper and lower case letters are different.
2269
2270 minLength: 1, maxLength: 128
2271
2272 - `BetaManagedAgentsWebFetchURLSourceExcept object`
2273
2274 Every tool's results contribute URLs that may be fetched, except the named tools' results.
2275
2276 - `type: "except"`
2277
2278 - `tools: array of BetaManagedAgentsWebFetchURLSourceToolReference`
2279
2280 The tools whose results do not contribute. Between 1 and 128 entries, each with a different name. An empty list is rejected; use "all" to leave out no tool's results.
2281
2282 - `type: "tool_reference"`
2283
2284 Must be "tool_reference".
2285
2286 - `name: string`
2287
2288 Name of the tool. Compared exactly, so upper and lower case letters are different.
2289
2290 minLength: 1, maxLength: 128
2291
2292 - `server_tool_results: BetaManagedAgentsWebFetchURLSourceToolFilter or null`
2293
2294 Which of the web_search and web_fetch tools' results contribute URLs that may be fetched. Null when not set, which allows both.
2295
2296 - `user_input: BetaManagedAgentsWebFetchURLSourceUserInput or null`
2297
2298 Whether URLs in the text of user messages may be fetched. Null when not set, which allows them.
2299
2300 - `BetaManagedAgentsWebFetchURLSourceAll object`
2301
2302 Every URL from this source may be fetched. This is the default.
2303
2304 - `BetaManagedAgentsWebFetchURLSourceNone object`
2305
2306 This source contributes no URLs that may be fetched.
2307
2308 - `allowed_domains: optional array of string`
2309
2310 - `blocked_domains: optional array of string`
2311
2312 - `max_content_tokens: optional number or null`
2313
2314 format: int32
2315
2316 - `BetaManagedAgentsWebSearchToolConfig object`
2317
2318 Configuration for the web_search tool.
2319
2320 - `type: "web_search"`
2321
2322 - `enabled: boolean`
2323
2324 - `name: "web_search"`
2325
2326 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
2327
2328 Permission policy for tool execution.
2329
2330 - `BetaManagedAgentsAlwaysAllowPolicy object`
2331
2332 Tool calls are automatically approved without user confirmation.
2333
2334 - `BetaManagedAgentsAlwaysAskPolicy object`
2335
2336 Tool calls require user confirmation before execution.
2337
2338 - `BetaManagedAgentsAutoPolicy object`
2339
2340 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.
2341
2342 - `allowed_domains: optional array of string`
2343
2344 - `blocked_domains: optional array of string`
2345
2346 - `user_location: optional BetaManagedAgentsUserLocation or null`
2347
2348 Approximate user location for search result localization.
2349
2350 - `type: "approximate"`
2351
2352 Location precision. Only "approximate" is supported.
2353
2354 - `city: optional string or null`
2355
2356 City name.
2357
2358 minLength: 1, maxLength: 255
2359
2360 - `country: optional string or null`
2361
2362 Two-letter ISO 3166-1 country code, uppercase.
2363
2364 - `region: optional string or null`
2365
2366 Region or state name.
2367
2368 minLength: 1, maxLength: 255
2369
2370 - `timezone: optional string or null`
2371
2372 IANA timezone identifier, e.g. "America/Los_Angeles".
2373
2374 minLength: 1, maxLength: 255
2375
2376 - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig`
2377
2378 Resolved default configuration for agent tools.
20452379
20462380 - `enabled: boolean`
20472381
2048 - `name: "bash"`
2049
20502382 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
20512383
20522384 Permission policy for tool execution.
from line 2387
20552387
20562388 Tool calls are automatically approved without user confirmation.
20572389
2058 - `type: "always_allow"`
2059
20602390 - `BetaManagedAgentsAlwaysAskPolicy object`
20612391
20622392 Tool calls require user confirmation before execution.
20632393
2064 - `type: "always_ask"`
2065
20662394 - `BetaManagedAgentsAutoPolicy object`
20672395
20682396 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.
20692397
2070 - `type: "auto"`
2071
2072 - `BetaManagedAgentsEditToolConfig object`
2073
2074 Configuration for the edit tool.
2075
2076 - `type: "edit"`
2398 - `BetaManagedAgentsMCPToolset object`
2399
2400 - `type: "mcp_toolset"`
2401
2402 - `configs: array of BetaManagedAgentsMCPToolConfig`
20772403
20782404 - `enabled: boolean`
20792405
2080 - `name: "edit"`
2406 - `name: string`
20812407
20822408 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
20832409
from line 2421
20952421
20962422 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.
20972423
2098 - `BetaManagedAgentsReadToolConfig object`
2099
2100 Configuration for the read tool.
2101
2102 - `type: "read"`
2424 - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig`
2425
2426 Resolved default configuration for all tools from an MCP server.
21032427
21042428 - `enabled: boolean`
21052429
2106 - `name: "read"`
2107
21082430 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
21092431
21102432 Permission policy for tool execution.
from line 2443
21212443
21222444 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.
21232445
2124 - `BetaManagedAgentsWriteToolConfig object`
2125
2126 Configuration for the write tool.
2127
2128 - `type: "write"`
2129
2130 - `enabled: boolean`
2131
2132 - `name: "write"`
2133
2134 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
2135
2136 Permission policy for tool execution.
2137
2138 - `BetaManagedAgentsAlwaysAllowPolicy object`
2139
2140 Tool calls are automatically approved without user confirmation.
2141
2142 - `BetaManagedAgentsAlwaysAskPolicy object`
2143
2144 Tool calls require user confirmation before execution.
2145
2146 - `BetaManagedAgentsAutoPolicy object`
2147
2148 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.
2149
2150 - `BetaManagedAgentsGlobToolConfig object`
2151
2152 Configuration for the glob tool.
2153
2154 - `type: "glob"`
2155
2156 - `enabled: boolean`
2157
2158 - `name: "glob"`
2159
2160 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
2161
2162 Permission policy for tool execution.
2163
2164 - `BetaManagedAgentsAlwaysAllowPolicy object`
2165
2166 Tool calls are automatically approved without user confirmation.
2167
2168 - `BetaManagedAgentsAlwaysAskPolicy object`
2169
2170 Tool calls require user confirmation before execution.
2171
2172 - `BetaManagedAgentsAutoPolicy object`
2173
2174 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.
2175
2176 - `BetaManagedAgentsGrepToolConfig object`
2177
2178 Configuration for the grep tool.
2179
2180 - `type: "grep"`
2181
2182 - `enabled: boolean`
2183
2184 - `name: "grep"`
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 - `BetaManagedAgentsWebFetchToolConfig object`
2203
2204 Configuration for the web_fetch tool.
2205
2206 - `type: "web_fetch"`
2207
2208 - `enabled: boolean`
2209
2210 - `name: "web_fetch"`
2211
2212 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
2213
2214 Permission policy for tool execution.
2215
2216 - `BetaManagedAgentsAlwaysAllowPolicy object`
2217
2218 Tool calls are automatically approved without user confirmation.
2219
2220 - `BetaManagedAgentsAlwaysAskPolicy object`
2221
2222 Tool calls require user confirmation before execution.
2223
2224 - `BetaManagedAgentsAutoPolicy object`
2225
2226 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.
2227
2228 - `url_sources: BetaManagedAgentsWebFetchURLSources or null`
2229
2230 Which sources contribute URLs the tool may fetch, always in the object form. Null when not set, which allows every source.
2231
2232 - `client_tool_results: BetaManagedAgentsWebFetchURLSourceToolFilter or null`
2233
2234 Which custom tools' results contribute URLs that may be fetched. Null when not set, which allows every custom tool's results.
2235
2236 - `BetaManagedAgentsWebFetchURLSourceAll object`
2237
2238 Every URL from this source may be fetched. This is the default.
2239
2240 - `type: "all"`
2241
2242 - `BetaManagedAgentsWebFetchURLSourceNone object`
2243
2244 This source contributes no URLs that may be fetched.
2245
2246 - `type: "none"`
2247
2248 - `BetaManagedAgentsWebFetchURLSourceOnly object`
2249
2250 Only the named tools' results contribute URLs that may be fetched.
2251
2252 - `type: "only"`
2253
2254 - `tools: array of BetaManagedAgentsWebFetchURLSourceToolReference`
2255
2256 The tools whose results contribute. Between 1 and 128 entries, each with a different name. An empty list is rejected; use "none" to allow no tool's results.
2257
2258 - `type: "tool_reference"`
2259
2260 Must be "tool_reference".
2261
2262 - `name: string`
2263
2264 Name of the tool. Compared exactly, so upper and lower case letters are different.
2265
2266 minLength: 1, maxLength: 128
2267
2268 - `BetaManagedAgentsWebFetchURLSourceExcept object`
2269
2270 Every tool's results contribute URLs that may be fetched, except the named tools' results.
2271
2272 - `type: "except"`
2273
2274 - `tools: array of BetaManagedAgentsWebFetchURLSourceToolReference`
2275
2276 The tools whose results do not contribute. Between 1 and 128 entries, each with a different name. An empty list is rejected; use "all" to leave out no tool's results.
2277
2278 - `type: "tool_reference"`
2279
2280 Must be "tool_reference".
2281
2282 - `name: string`
2283
2284 Name of the tool. Compared exactly, so upper and lower case letters are different.
2285
2286 minLength: 1, maxLength: 128
2287
2288 - `server_tool_results: BetaManagedAgentsWebFetchURLSourceToolFilter or null`
2289
2290 Which of the web_search and web_fetch tools' results contribute URLs that may be fetched. Null when not set, which allows both.
2291
2292 - `user_input: BetaManagedAgentsWebFetchURLSourceUserInput or null`
2293
2294 Whether URLs in the text of user messages may be fetched. Null when not set, which allows them.
2295
2296 - `BetaManagedAgentsWebFetchURLSourceAll object`
2297
2298 Every URL from this source may be fetched. This is the default.
2299
2300 - `BetaManagedAgentsWebFetchURLSourceNone object`
2301
2302 This source contributes no URLs that may be fetched.
2303
2304 - `allowed_domains: optional array of string`
2305
2306 - `blocked_domains: optional array of string`
2307
2308 - `max_content_tokens: optional number or null`
2309
2310 format: int32
2311
2312 - `BetaManagedAgentsWebSearchToolConfig object`
2313
2314 Configuration for the web_search tool.
2315
2316 - `type: "web_search"`
2317
2318 - `enabled: boolean`
2319
2320 - `name: "web_search"`
2321
2322 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
2323
2324 Permission policy for tool execution.
2325
2326 - `BetaManagedAgentsAlwaysAllowPolicy object`
2327
2328 Tool calls are automatically approved without user confirmation.
2329
2330 - `BetaManagedAgentsAlwaysAskPolicy object`
2331
2332 Tool calls require user confirmation before execution.
2333
2334 - `BetaManagedAgentsAutoPolicy object`
2335
2336 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.
2337
2338 - `allowed_domains: optional array of string`
2339
2340 - `blocked_domains: optional array of string`
2341
2342 - `user_location: optional BetaManagedAgentsUserLocation or null`
2343
2344 Approximate user location for search result localization.
2345
2346 - `type: "approximate"`
2347
2348 Location precision. Only "approximate" is supported.
2349
2350 - `city: optional string or null`
2351
2352 City name.
2353
2354 minLength: 1, maxLength: 255
2355
2356 - `country: optional string or null`
2357
2358 Two-letter ISO 3166-1 country code, uppercase.
2359
2360 - `region: optional string or null`
2361
2362 Region or state name.
2363
2364 minLength: 1, maxLength: 255
2365
2366 - `timezone: optional string or null`
2367
2368 IANA timezone identifier, e.g. "America/Los_Angeles".
2369
2370 minLength: 1, maxLength: 255
2371
2372 - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig`
2373
2374 Resolved default configuration for agent tools.
2375
2376 - `enabled: boolean`
2377
2378 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
2379
2380 Permission policy for tool execution.
2381
2382 - `BetaManagedAgentsAlwaysAllowPolicy object`
2383
2384 Tool calls are automatically approved without user confirmation.
2385
2386 - `BetaManagedAgentsAlwaysAskPolicy object`
2387
2388 Tool calls require user confirmation before execution.
2389
2390 - `BetaManagedAgentsAutoPolicy object`
2391
2392 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.
2393
2394 - `BetaManagedAgentsMCPToolset object`
2395
2396 - `type: "mcp_toolset"`
2397
2398 - `configs: array of BetaManagedAgentsMCPToolConfig`
2399
2400 - `enabled: boolean`
2446 - `mcp_server_name: string`
2447
2448 - `BetaManagedAgentsCustomTool object`
2449
2450 A custom tool as returned in API responses.
2451
2452 - `type: "custom"`
2453
2454 - `description: string`
2455
2456 - `input_schema: BetaManagedAgentsCustomToolInputSchema`
2457
2458 JSON Schema for custom tool input parameters.
2459
2460 - `type: "object"`
2461
2462 - `properties: optional map[unknown] or null`
2463
2464 - `required: optional array of string or null`
24012465
24022466 - `name: string`
24032467
2404 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
2405
2406 Permission policy for tool execution.
2407
2408 - `BetaManagedAgentsAlwaysAllowPolicy object`
2409
2410 Tool calls are automatically approved without user confirmation.
2411
2412 - `BetaManagedAgentsAlwaysAskPolicy object`
2413
2414 Tool calls require user confirmation before execution.
2415
2416 - `BetaManagedAgentsAutoPolicy object`
2417
2418 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.
2419
2420 - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig`
2421
2422 Resolved default configuration for all tools from an MCP server.
2423
2424 - `enabled: boolean`
2425
2426 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
2427
2428 Permission policy for tool execution.
2429
2430 - `BetaManagedAgentsAlwaysAllowPolicy object`
2431
2432 Tool calls are automatically approved without user confirmation.
2433
2434 - `BetaManagedAgentsAlwaysAskPolicy object`
2435
2436 Tool calls require user confirmation before execution.
2437
2438 - `BetaManagedAgentsAutoPolicy object`
2439
2440 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.
2441
2442 - `mcp_server_name: string`
2443
2444 - `BetaManagedAgentsCustomTool object`
2445
2446 A custom tool as returned in API responses.
2447
2448 - `type: "custom"`
2449
2450 - `description: string`
2451
2452 - `input_schema: BetaManagedAgentsCustomToolInputSchema`
2453
2454 JSON Schema for custom tool input parameters.
2455
2456 - `type: "object"`
2457
2458 - `properties: optional map[unknown] or null`
2459
2460 - `required: optional array of string or null`
2468 - `version: number`
2469
2470 format: int32
2471
2472 - `BetaManagedAgentsAdvisor object`
2473
2474 Platform advisor roster entry: a model the session's primary thread may consult mid-turn.
2475
2476 - `type: "advisor"`
2477
2478 - `model: string`
2479
2480 The advisor model id.
2481
2482 - `BetaManagedAgentsSessionMultiagent20261001 object`
2483
2484 Resolved multiagent configuration with three members, as copied to the `session` at creation.
2485
2486 - `type: "multiagent_20261001"`
2487
2488 - `advisor: BetaManagedAgentsMultiagentAdvisor`
2489
2490 Whether the session's primary thread can consult an advisor model.
2491
2492 - `BetaManagedAgentsMultiagentAdvisorEnabled object`
2493
2494 The session's primary thread can consult `model` mid-turn.
2495
2496 - `type: "enabled"`
2497
2498 - `model: string`
2499
2500 The advisor model id.
2501
2502 - `BetaManagedAgentsMultiagentAdvisorDisabled object`
2503
2504 The agent has no advisor.
2505
2506 - `type: "disabled"`
2507
2508 - `subagents: BetaManagedAgentsSessionMultiagentSubagents`
2509
2510 Whether the agent can spawn session threads.
2511
2512 - `BetaManagedAgentsSessionMultiagentSubagentsEnabled object`
2513
2514 The agent can spawn session threads.
2515
2516 - `type: "enabled"`
2517
2518 - `inline_agents: BetaManagedAgentsMultiagentInlineAgents`
2519
2520 Whether the agent can define inline agents, which are not saved, when it spawns session threads.
2521
2522 - `BetaManagedAgentsMultiagentInlineAgentsEnabled object`
2523
2524 The agent can define inline agents.
2525
2526 - `type: "enabled"`
2527
2528 - `BetaManagedAgentsMultiagentInlineAgentsDisabled object`
2529
2530 The agent cannot define inline agents.
2531
2532 - `type: "disabled"`
2533
2534 - `predefined_agents: array of BetaManagedAgentsSessionThreadAgent`
2535
2536 Full `agent` definitions of the predefined agents, which are saved agents that this agent can spawn as session threads.
2537
2538 - `type: "agent"`
2539
2540 - `id: string`
2541
2542 - `description: string or null`
2543
2544 - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition`
2545
2546 - `model: BetaManagedAgentsModelConfig`
2547
2548 Model identifier and configuration.
24612549
24622550 - `name: string`
24632551
2464 - `version: number`
2465
2466 format: int32
2467
2468 - `BetaManagedAgentsAdvisor object`
2469
2470 Platform advisor roster entry: a model the session's primary thread may consult mid-turn.
2471
2472 - `type: "advisor"`
2473
2474 - `model: string`
2475
2476 The advisor model id.
2552 - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill`
2553
2554 - `system: string or null`
2555
2556 - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool`
2557
2558 - `version: number`
2559
2560 format: int32
2561
2562 - `BetaManagedAgentsMultiagentSubagentsDisabled object`
2563
2564 The agent cannot spawn session threads.
2565
2566 - `type: "disabled"`
2567
2568 - `workflows: BetaManagedAgentsSessionMultiagentWorkflows`
2569
2570 Whether the agent can start workflow runs.
2571
2572 - `BetaManagedAgentsSessionMultiagentWorkflowsEnabled object`
2573
2574 The agent can start workflow runs.
2575
2576 - `type: "enabled"`
2577
2578 - `inline_agents: BetaManagedAgentsMultiagentInlineAgents`
2579
2580 Whether a run's plan can define inline agents, which are not saved.
2581
2582 - `predefined_agents: array of BetaManagedAgentsSessionThreadAgent`
2583
2584 Full `agent` definitions of the predefined agents, which are saved agents that a run's plan can use.
2585
2586 - `type: "agent"`
2587
2588 - `id: string`
2589
2590 - `description: string or null`
2591
2592 - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition`
2593
2594 - `model: BetaManagedAgentsModelConfig`
2595
2596 Model identifier and configuration.
2597
2598 - `name: string`
2599
2600 - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill`
2601
2602 - `system: string or null`
2603
2604 - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool`
2605
2606 - `version: number`
2607
2608 format: int32
2609
2610 - `BetaManagedAgentsMultiagentWorkflowsDisabled object`
2611
2612 The agent cannot start workflow runs.
2613
2614 - `type: "disabled"`
24772615
24782616 - `name: string`
24792617
from line 2828
26902828 - `budget: optional BetaManagedAgentsBudgetLimit or null`
26912829
26922830 The session's configured budget at the snapshot time, or null when the session has no budget.
2831
2832 - `BetaManagedAgentsWorkflowRunCreatedEvent object`
2833
2834 A workflow run was created. A workflow run is background work that the session's agent starts. Emitted once per run, before the run's other `workflow_run.*` events.
2835
2836 - `type: "workflow_run.created"`
2837
2838 - `id: string`
2839
2840 Unique identifier for this event.
2841
2842 - `description: string or null`
2843
2844 Description that the agent gave the run, passed on as written, or `null` if it gave none.
2845
2846 - `name: string`
2847
2848 Name that the agent gave the run, passed on as written, or a name that the server assigned.
2849
2850 - `phases: array of BetaManagedAgentsWorkflowRunPhase`
2851
2852 The phases that the run's plan declares, in the plan's order. Can be empty.
2853
2854 - `id: string`
2855
2856 Unique identifier for the phase.
2857
2858 - `description: string or null`
2859
2860 Description that the agent gave the phase, passed on as written, or `null` if it gave none.
2861
2862 - `name: string`
2863
2864 Name that the agent gave the phase, passed on as written.
2865
2866 - `processed_at: string`
2867
2868 Timestamp when this event was processed.
2869
2870 format: date-time
2871
2872 - `workflow_run_id: string`
2873
2874 Identifier of the run. The same value is on all of the run's `workflow_run.*` events.
2875
2876 - `BetaManagedAgentsWorkflowRunStatusEndedEvent object`
2877
2878 A workflow run ended. Emitted once per run, as the last of the run's `workflow_run.*` events.
2879
2880 - `type: "workflow_run.status_ended"`
2881
2882 - `id: string`
2883
2884 Unique identifier for this event.
2885
2886 - `processed_at: string`
2887
2888 Timestamp when this event was processed.
2889
2890 format: date-time
2891
2892 - `result: BetaManagedAgentsWorkflowRunResult`
2893
2894 How the run ended.
2895
2896 - `BetaManagedAgentsWorkflowRunResultCompleted object`
2897
2898 The run's plan, a program that the agent wrote, finished. This does not say whether the work succeeded.
2899
2900 - `type: "completed"`
2901
2902 - `BetaManagedAgentsWorkflowRunResultError object`
2903
2904 The run failed or reached its time limit.
2905
2906 - `type: "error"`
2907
2908 - `error: BetaManagedAgentsWorkflowRunError`
2909
2910 Why the run did not finish.
2911
2912 - `BetaManagedAgentsTimeoutWorkflowRunError object`
2913
2914 The run reached its time limit.
2915
2916 - `type: "timeout_error"`
2917
2918 - `message: string`
2919
2920 Short explanation written by the server. It never contains content from the run or its agents.
2921
2922 - `BetaManagedAgentsProgramWorkflowRunError object`
2923
2924 The plan, a program that the agent wrote, failed, or the server refused it.
2925
2926 - `type: "program_error"`
2927
2928 - `message: string`
2929
2930 Short explanation written by the server. It never contains content from the run or its agents.
2931
2932 - `BetaManagedAgentsUnknownWorkflowRunError object`
2933
2934 A failure that has no type of its own.
2935
2936 - `type: "unknown_error"`
2937
2938 - `message: string`
2939
2940 Short explanation written by the server. It never contains content from the run or its agents.
2941
2942 - `BetaManagedAgentsThreadLimitWorkflowRunError object`
2943
2944 The run exceeded the limit on the number of threads that a run can create.
2945
2946 - `type: "thread_limit_error"`
2947
2948 - `message: string`
2949
2950 Short explanation written by the server. It never contains content from the run or its agents.
2951
2952 - `BetaManagedAgentsMaxWorkflowRunsWorkflowRunError object`
2953
2954 No run was created, because the session was at its limit of open workflow runs, which are runs that have not ended. Only `workflow_run.error` carries this type.
2955
2956 - `type: "max_workflow_runs_error"`
2957
2958 - `message: string`
2959
2960 Short explanation written by the server. It never contains content from the run or its agents.
2961
2962 - `BetaManagedAgentsWorkflowRunResultStopped object`
2963
2964 The agent stopped the run.
2965
2966 - `type: "stopped"`
2967
2968 - `workflow_run_id: string`
2969
2970 Identifier of the run. The same value is on all of the run's `workflow_run.*` events.
2971
2972 - `BetaManagedAgentsWorkflowRunPhaseStartedEvent object`
2973
2974 A workflow run's plan entered a phase.
2975
2976 - `type: "workflow_run.phase_started"`
2977
2978 - `id: string`
2979
2980 Unique identifier for this event.
2981
2982 - `processed_at: string`
2983
2984 Timestamp when this event was processed.
2985
2986 format: date-time
2987
2988 - `workflow_run_id: string`
2989
2990 Identifier of the run. The same value is on all of the run's `workflow_run.*` events.
2991
2992 - `workflow_run_phase_id: string`
2993
2994 Identifier of the phase, as in `phases` on the run's `workflow_run.created` event.
2995
2996 - `BetaManagedAgentsWorkflowRunPhaseEndedEvent object`
2997
2998 A workflow run's plan left a phase, or the run's end closed it. Emitted once for every `workflow_run.phase_started` event, before the run's `workflow_run.status_ended` event. The event does not say whether the plan finished the phase's work, or why it left.
2999
3000 - `type: "workflow_run.phase_ended"`
3001
3002 - `id: string`
3003
3004 Unique identifier for this event.
3005
3006 - `phase_started_id: string`
3007
3008 Identifier of the `workflow_run.phase_started` event that opened the phase.
3009
3010 - `processed_at: string`
3011
3012 Timestamp when this event was processed.
3013
3014 format: date-time
3015
3016 - `workflow_run_id: string`
3017
3018 Identifier of the run. The same value is on all of the run's `workflow_run.*` events.
3019
3020 - `workflow_run_phase_id: string`
3021
3022 Identifier of the phase, as in `phases` on the run's `workflow_run.created` event.
3023
3024 - `BetaManagedAgentsWorkflowRunStatusRunningEvent object`
3025
3026 A workflow run is running. Emitted when the run starts to execute, and each time it resumes after being idle. A run that starts idle emits `workflow_run.status_idle` first.
3027
3028 - `type: "workflow_run.status_running"`
3029
3030 - `id: string`
3031
3032 Unique identifier for this event.
3033
3034 - `processed_at: string`
3035
3036 Timestamp when this event was processed.
3037
3038 format: date-time
3039
3040 - `workflow_run_id: string`
3041
3042 Identifier of the run. The same value is on all of the run's `workflow_run.*` events.
3043
3044 - `BetaManagedAgentsWorkflowRunStatusIdleEvent object`
3045
3046 A workflow run is idle. Emitted each time the run goes idle, whatever the cause. If the run ends while idle, no `workflow_run.status_running` comes between this event and its `workflow_run.status_ended`.
3047
3048 - `type: "workflow_run.status_idle"`
3049
3050 - `id: string`
3051
3052 Unique identifier for this event.
3053
3054 - `processed_at: string`
3055
3056 Timestamp when this event was processed.
3057
3058 format: date-time
3059
3060 - `workflow_run_id: string`
3061
3062 Identifier of the run. The same value is on all of the run's `workflow_run.*` events.
3063
3064 - `BetaManagedAgentsWorkflowRunErrorEvent object`
3065
3066 A workflow run met an error, or an error kept a run from being created. A run that ends with a `result.type` of `error` emits this event before its `workflow_run.status_ended`, with the same `error`.
3067
3068 - `type: "workflow_run.error"`
3069
3070 - `id: string`
3071
3072 Unique identifier for this event.
3073
3074 - `error: BetaManagedAgentsWorkflowRunError`
3075
3076 Why the run did not finish, or was not created.
3077
3078 - `processed_at: string`
3079
3080 Timestamp when this event was processed.
3081
3082 format: date-time
3083
3084 - `workflow_run_id: string or null`
3085
3086 Identifier of the run that met the error, or `null` when the error kept a run from being created.
26933087
26943088## Example
26953089
26963090
api/beta/sessions/threads/list Changed · +67 / -6 lines
from line 25
2525
2626 Opaque pagination cursor from a previous response's `next_page`. Forward-only.
2727
28- `statuses: optional array of BetaManagedAgentsSessionThreadStatus`
29
30 Return only threads that have one of these statuses.
31
32 Repeat the parameter to give more than one status. Leave it out to return threads of every status.
33
34 - `"running"`
35
36 - `"idle"`
37
38 - `"rescheduling"`
39
40 - `"terminated"`
41
2842## Headers
2943
3044- `"anthropic-version": optional string`
from line 167
153167
154168 Unique identifier for this thread.
155169
156 - `agent: BetaManagedAgentsSessionThreadAgent or BetaManagedAgentsAdvisor`
170 - `agent: BetaManagedAgentsSessionThreadAgent or BetaManagedAgentsAdvisor or BetaManagedAgentsInlineAgent`
157171
158172 Resolved agent definition for this thread. Snapshot of the agent at thread creation time.
159173
from line 245
231245
232246 - `"claude-haiku-4-5"`
233247
234 Fastest model with near-frontier intelligence
235
236248 - `"claude-haiku-4-5-20251001"`
237249
238 Fastest model with near-frontier intelligence
239
240250 - `"claude-opus-4-5"`
241251
242252 Powerful intelligence for long-running agents and coding
from line 787
777787
778788 The advisor model id.
779789
790 - `BetaManagedAgentsInlineAgent object`
791
792 An agent that has no Agent resource, and so no `id` or `version`. It is defined inline, in a workflow run's plan or when a session thread is spawned, and is not saved.
793
794 - `type: "inline"`
795
796 - `description: string or null`
797
798 - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition`
799
800 - `type: "url"`
801
802 - `name: string`
803
804 - `url: string`
805
806 - `model: BetaManagedAgentsModelConfig`
807
808 Model identifier and configuration.
809
810 - `name: string`
811
812 The name that the agent's definition gave, or one that the server assigned.
813
814 - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill`
815
816 - `BetaManagedAgentsAnthropicSkill object`
817
818 A resolved Anthropic-managed skill.
819
820 - `BetaManagedAgentsCustomSkill object`
821
822 A resolved user-created custom skill.
823
824 - `system: string or null`
825
826 - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool`
827
828 - `BetaManagedAgentsAgentToolset20260401 object`
829
830 - `BetaManagedAgentsMCPToolset object`
831
832 - `BetaManagedAgentsCustomTool object`
833
834 A custom tool as returned in API responses.
835
780836 - `archived_at: string or null`
781837
782838 When the thread was archived. Null if not archived.
from line 965
909965
910966 format: int32
911967
968 - `workflow_run_id: string or null`
969
970 Identifier of the workflow run that created the thread, or `null` for any other thread.
971
912972- `next_page: optional string or null`
913973
914974 Opaque cursor for the next page. Null when no more results.
from line 1069
10091069 "web_fetch_requests": 0,
10101070 "web_search_requests": 3
10111071 }
1012 }
1072 },
1073 "workflow_run_id": null
10131074 }
10141075 ],
10151076 "next_page": "page_MjAyNS0wNS0xNFQwMDowMDowMFo="
api/beta/sessions/threads/retrieve Changed · +53 / -6 lines
from line 143
143143
144144 Unique identifier for this thread.
145145
146 - `agent: BetaManagedAgentsSessionThreadAgent or BetaManagedAgentsAdvisor`
146 - `agent: BetaManagedAgentsSessionThreadAgent or BetaManagedAgentsAdvisor or BetaManagedAgentsInlineAgent`
147147
148148 Resolved agent definition for this thread. Snapshot of the agent at thread creation time.
149149
from line 221
221221
222222 - `"claude-haiku-4-5"`
223223
224 Fastest model with near-frontier intelligence
225
226224 - `"claude-haiku-4-5-20251001"`
227225
228 Fastest model with near-frontier intelligence
229
230226 - `"claude-opus-4-5"`
231227
232228 Powerful intelligence for long-running agents and coding
from line 763
767763
768764 The advisor model id.
769765
766 - `BetaManagedAgentsInlineAgent object`
767
768 An agent that has no Agent resource, and so no `id` or `version`. It is defined inline, in a workflow run's plan or when a session thread is spawned, and is not saved.
769
770 - `type: "inline"`
771
772 - `description: string or null`
773
774 - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition`
775
776 - `type: "url"`
777
778 - `name: string`
779
780 - `url: string`
781
782 - `model: BetaManagedAgentsModelConfig`
783
784 Model identifier and configuration.
785
786 - `name: string`
787
788 The name that the agent's definition gave, or one that the server assigned.
789
790 - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill`
791
792 - `BetaManagedAgentsAnthropicSkill object`
793
794 A resolved Anthropic-managed skill.
795
796 - `BetaManagedAgentsCustomSkill object`
797
798 A resolved user-created custom skill.
799
800 - `system: string or null`
801
802 - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool`
803
804 - `BetaManagedAgentsAgentToolset20260401 object`
805
806 - `BetaManagedAgentsMCPToolset object`
807
808 - `BetaManagedAgentsCustomTool object`
809
810 A custom tool as returned in API responses.
811
770812 - `archived_at: string or null`
771813
772814 When the thread was archived. Null if not archived.
from line 941
899941
900942 format: int32
901943
944 - `workflow_run_id: string or null`
945
946 Identifier of the workflow run that created the thread, or `null` for any other thread.
947
902948## Example
903949
904950```bash
from line 1039
9931039 "web_fetch_requests": 0,
9941040 "web_search_requests": 3
9951041 }
996 }
1042 },
1043 "workflow_run_id": null
9971044}
9981045```
9991046
api/beta/sessions/update Changed · +571 / -437 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 795
795795
796796 - `"claude-haiku-4-5"`
797797
798 Fastest model with near-frontier intelligence
799
800798 - `"claude-haiku-4-5-20251001"`
801799
802 Fastest model with near-frontier intelligence
803
804800 - `"claude-opus-4-5"`
805801
806802 Powerful intelligence for long-running agents and coding
from line 865
869865
870866 - `"fast"`
871867
872 - `multiagent: BetaManagedAgentsSessionMultiagentCoordinator or null`
868 - `multiagent: BetaManagedAgentsSessionMultiagent or null`
873869
874870 Resolved multiagent orchestration configuration. Null when the agent is single-threaded.
875871
876 - `type: "coordinator"`
877
878 - `agents: array of BetaManagedAgentsSessionThreadAgent or BetaManagedAgentsAdvisor`
879
880 Full `agent` definitions the coordinator may spawn as session threads.
881
882 - `BetaManagedAgentsSessionThreadAgent object`
883
884 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`.
885
886 - `type: "agent"`
887
888 - `id: string`
889
890 - `description: string or null`
891
892 - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition`
893
894 - `type: "url"`
872 - `BetaManagedAgentsSessionMultiagentCoordinator object`
873
874 Resolved coordinator topology with full agent definitions for each roster member.
875
876 - `type: "coordinator"`
877
878 - `agents: array of BetaManagedAgentsSessionThreadAgent or BetaManagedAgentsAdvisor`
879
880 Full `agent` definitions the coordinator may spawn as session threads.
881
882 - `BetaManagedAgentsSessionThreadAgent object`
883
884 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`.
885
886 - `type: "agent"`
887
888 - `id: string`
889
890 - `description: string or null`
891
892 - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition`
893
894 - `type: "url"`
895
896 - `name: string`
897
898 - `url: string`
899
900 - `model: BetaManagedAgentsModelConfig`
901
902 Model identifier and configuration.
895903
896904 - `name: string`
897905
898 - `url: string`
899
900 - `model: BetaManagedAgentsModelConfig`
901
902 Model identifier and configuration.
903
904 - `name: string`
905
906 - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill`
907
908 - `BetaManagedAgentsAnthropicSkill object`
909
910 A resolved Anthropic-managed skill.
911
912 - `type: "anthropic"`
913
914 - `skill_id: string`
915
916 - `version: string`
917
918 - `BetaManagedAgentsCustomSkill object`
919
920 A resolved user-created custom skill.
921
922 - `type: "custom"`
923
924 - `skill_id: string`
925
926 - `version: string`
927
928 - `system: string or null`
929
930 - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool`
931
932 - `BetaManagedAgentsAgentToolset20260401 object`
933
934 - `type: "agent_toolset_20260401"`
935
936 - `configs: array of BetaManagedAgentsAgentToolConfig`
937
938 - `BetaManagedAgentsBashToolConfig object`
939
940 Configuration for the bash tool.
941
942 - `type: "bash"`
906 - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill`
907
908 - `BetaManagedAgentsAnthropicSkill object`
909
910 A resolved Anthropic-managed skill.
911
912 - `type: "anthropic"`
913
914 - `skill_id: string`
915
916 - `version: string`
917
918 - `BetaManagedAgentsCustomSkill object`
919
920 A resolved user-created custom skill.
921
922 - `type: "custom"`
923
924 - `skill_id: string`
925
926 - `version: string`
927
928 - `system: string or null`
929
930 - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool`
931
932 - `BetaManagedAgentsAgentToolset20260401 object`
933
934 - `type: "agent_toolset_20260401"`
935
936 - `configs: array of BetaManagedAgentsAgentToolConfig`
937
938 - `BetaManagedAgentsBashToolConfig object`
939
940 Configuration for the bash tool.
941
942 - `type: "bash"`
943
944 - `enabled: boolean`
945
946 - `name: "bash"`
947
948 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
949
950 Permission policy for tool execution.
951
952 - `BetaManagedAgentsAlwaysAllowPolicy object`
953
954 Tool calls are automatically approved without user confirmation.
955
956 - `type: "always_allow"`
957
958 - `BetaManagedAgentsAlwaysAskPolicy object`
959
960 Tool calls require user confirmation before execution.
961
962 - `type: "always_ask"`
963
964 - `BetaManagedAgentsAutoPolicy object`
965
966 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.
967
968 - `type: "auto"`
969
970 - `BetaManagedAgentsEditToolConfig object`
971
972 Configuration for the edit tool.
973
974 - `type: "edit"`
975
976 - `enabled: boolean`
977
978 - `name: "edit"`
979
980 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
981
982 Permission policy for tool execution.
983
984 - `BetaManagedAgentsAlwaysAllowPolicy object`
985
986 Tool calls are automatically approved without user confirmation.
987
988 - `BetaManagedAgentsAlwaysAskPolicy object`
989
990 Tool calls require user confirmation before execution.
991
992 - `BetaManagedAgentsAutoPolicy object`
993
994 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.
995
996 - `BetaManagedAgentsReadToolConfig object`
997
998 Configuration for the read tool.
999
1000 - `type: "read"`
1001
1002 - `enabled: boolean`
1003
1004 - `name: "read"`
1005
1006 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
1007
1008 Permission policy for tool execution.
1009
1010 - `BetaManagedAgentsAlwaysAllowPolicy object`
1011
1012 Tool calls are automatically approved without user confirmation.
1013
1014 - `BetaManagedAgentsAlwaysAskPolicy object`
1015
1016 Tool calls require user confirmation before execution.
1017
1018 - `BetaManagedAgentsAutoPolicy object`
1019
1020 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.
1021
1022 - `BetaManagedAgentsWriteToolConfig object`
1023
1024 Configuration for the write tool.
1025
1026 - `type: "write"`
1027
1028 - `enabled: boolean`
1029
1030 - `name: "write"`
1031
1032 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
1033
1034 Permission policy for tool execution.
1035
1036 - `BetaManagedAgentsAlwaysAllowPolicy object`
1037
1038 Tool calls are automatically approved without user confirmation.
1039
1040 - `BetaManagedAgentsAlwaysAskPolicy object`
1041
1042 Tool calls require user confirmation before execution.
1043
1044 - `BetaManagedAgentsAutoPolicy object`
1045
1046 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.
1047
1048 - `BetaManagedAgentsGlobToolConfig object`
1049
1050 Configuration for the glob tool.
1051
1052 - `type: "glob"`
1053
1054 - `enabled: boolean`
1055
1056 - `name: "glob"`
1057
1058 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
1059
1060 Permission policy for tool execution.
1061
1062 - `BetaManagedAgentsAlwaysAllowPolicy object`
1063
1064 Tool calls are automatically approved without user confirmation.
1065
1066 - `BetaManagedAgentsAlwaysAskPolicy object`
1067
1068 Tool calls require user confirmation before execution.
1069
1070 - `BetaManagedAgentsAutoPolicy object`
1071
1072 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.
1073
1074 - `BetaManagedAgentsGrepToolConfig object`
1075
1076 Configuration for the grep tool.
1077
1078 - `type: "grep"`
1079
1080 - `enabled: boolean`
1081
1082 - `name: "grep"`
1083
1084 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
1085
1086 Permission policy for tool execution.
1087
1088 - `BetaManagedAgentsAlwaysAllowPolicy object`
1089
1090 Tool calls are automatically approved without user confirmation.
1091
1092 - `BetaManagedAgentsAlwaysAskPolicy object`
1093
1094 Tool calls require user confirmation before execution.
1095
1096 - `BetaManagedAgentsAutoPolicy object`
1097
1098 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.
1099
1100 - `BetaManagedAgentsWebFetchToolConfig object`
1101
1102 Configuration for the web_fetch tool.
1103
1104 - `type: "web_fetch"`
1105
1106 - `enabled: boolean`
1107
1108 - `name: "web_fetch"`
1109
1110 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
1111
1112 Permission policy for tool execution.
1113
1114 - `BetaManagedAgentsAlwaysAllowPolicy object`
1115
1116 Tool calls are automatically approved without user confirmation.
1117
1118 - `BetaManagedAgentsAlwaysAskPolicy object`
1119
1120 Tool calls require user confirmation before execution.
1121
1122 - `BetaManagedAgentsAutoPolicy object`
1123
1124 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.
1125
1126 - `url_sources: BetaManagedAgentsWebFetchURLSources or null`
1127
1128 Which sources contribute URLs the tool may fetch, always in the object form. Null when not set, which allows every source.
1129
1130 - `client_tool_results: BetaManagedAgentsWebFetchURLSourceToolFilter or null`
1131
1132 Which custom tools' results contribute URLs that may be fetched. Null when not set, which allows every custom tool's results.
1133
1134 - `BetaManagedAgentsWebFetchURLSourceAll object`
1135
1136 Every URL from this source may be fetched. This is the default.
1137
1138 - `type: "all"`
1139
1140 - `BetaManagedAgentsWebFetchURLSourceNone object`
1141
1142 This source contributes no URLs that may be fetched.
1143
1144 - `type: "none"`
1145
1146 - `BetaManagedAgentsWebFetchURLSourceOnly object`
1147
1148 Only the named tools' results contribute URLs that may be fetched.
1149
1150 - `type: "only"`
1151
1152 - `tools: array of BetaManagedAgentsWebFetchURLSourceToolReference`
1153
1154 The tools whose results contribute. Between 1 and 128 entries, each with a different name. An empty list is rejected; use "none" to allow no tool's results.
1155
1156 - `type: "tool_reference"`
1157
1158 Must be "tool_reference".
1159
1160 - `name: string`
1161
1162 Name of the tool. Compared exactly, so upper and lower case letters are different.
1163
1164 minLength: 1, maxLength: 128
1165
1166 - `BetaManagedAgentsWebFetchURLSourceExcept object`
1167
1168 Every tool's results contribute URLs that may be fetched, except the named tools' results.
1169
1170 - `type: "except"`
1171
1172 - `tools: array of BetaManagedAgentsWebFetchURLSourceToolReference`
1173
1174 The tools whose results do not contribute. Between 1 and 128 entries, each with a different name. An empty list is rejected; use "all" to leave out no tool's results.
1175
1176 - `type: "tool_reference"`
1177
1178 Must be "tool_reference".
1179
1180 - `name: string`
1181
1182 Name of the tool. Compared exactly, so upper and lower case letters are different.
1183
1184 minLength: 1, maxLength: 128
1185
1186 - `server_tool_results: BetaManagedAgentsWebFetchURLSourceToolFilter or null`
1187
1188 Which of the web_search and web_fetch tools' results contribute URLs that may be fetched. Null when not set, which allows both.
1189
1190 - `user_input: BetaManagedAgentsWebFetchURLSourceUserInput or null`
1191
1192 Whether URLs in the text of user messages may be fetched. Null when not set, which allows them.
1193
1194 - `BetaManagedAgentsWebFetchURLSourceAll object`
1195
1196 Every URL from this source may be fetched. This is the default.
1197
1198 - `BetaManagedAgentsWebFetchURLSourceNone object`
1199
1200 This source contributes no URLs that may be fetched.
1201
1202 - `allowed_domains: optional array of string`
1203
1204 - `blocked_domains: optional array of string`
1205
1206 - `max_content_tokens: optional number or null`
1207
1208 format: int32
1209
1210 - `BetaManagedAgentsWebSearchToolConfig object`
1211
1212 Configuration for the web_search tool.
1213
1214 - `type: "web_search"`
1215
1216 - `enabled: boolean`
1217
1218 - `name: "web_search"`
1219
1220 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
1221
1222 Permission policy for tool execution.
1223
1224 - `BetaManagedAgentsAlwaysAllowPolicy object`
1225
1226 Tool calls are automatically approved without user confirmation.
1227
1228 - `BetaManagedAgentsAlwaysAskPolicy object`
1229
1230 Tool calls require user confirmation before execution.
1231
1232 - `BetaManagedAgentsAutoPolicy object`
1233
1234 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.
1235
1236 - `allowed_domains: optional array of string`
1237
1238 - `blocked_domains: optional array of string`
1239
1240 - `user_location: optional BetaManagedAgentsUserLocation or null`
1241
1242 Approximate user location for search result localization.
1243
1244 - `type: "approximate"`
1245
1246 Location precision. Only "approximate" is supported.
1247
1248 - `city: optional string or null`
1249
1250 City name.
1251
1252 minLength: 1, maxLength: 255
1253
1254 - `country: optional string or null`
1255
1256 Two-letter ISO 3166-1 country code, uppercase.
1257
1258 - `region: optional string or null`
1259
1260 Region or state name.
1261
1262 minLength: 1, maxLength: 255
1263
1264 - `timezone: optional string or null`
1265
1266 IANA timezone identifier, e.g. "America/Los_Angeles".
1267
1268 minLength: 1, maxLength: 255
1269
1270 - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig`
1271
1272 Resolved default configuration for agent tools.
9431273
9441274 - `enabled: boolean`
9451275
946 - `name: "bash"`
947
9481276 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
9491277
9501278 Permission policy for tool execution.
from line 1281
9531281
9541282 Tool calls are automatically approved without user confirmation.
9551283
956 - `type: "always_allow"`
957
9581284 - `BetaManagedAgentsAlwaysAskPolicy object`
9591285
9601286 Tool calls require user confirmation before execution.
9611287
962 - `type: "always_ask"`
963
9641288 - `BetaManagedAgentsAutoPolicy object`
9651289
9661290 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.
9671291
968 - `type: "auto"`
969
970 - `BetaManagedAgentsEditToolConfig object`
971
972 Configuration for the edit tool.
973
974 - `type: "edit"`
1292 - `BetaManagedAgentsMCPToolset object`
1293
1294 - `type: "mcp_toolset"`
1295
1296 - `configs: array of BetaManagedAgentsMCPToolConfig`
9751297
9761298 - `enabled: boolean`
9771299
978 - `name: "edit"`
1300 - `name: string`
9791301
9801302 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
9811303
from line 1315
9931315
9941316 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.
9951317
996 - `BetaManagedAgentsReadToolConfig object`
997
998 Configuration for the read tool.
999
1000 - `type: "read"`
1318 - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig`
1319
1320 Resolved default configuration for all tools from an MCP server.
10011321
10021322 - `enabled: boolean`
10031323
1004 - `name: "read"`
1005
10061324 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
10071325
10081326 Permission policy for tool execution.
from line 1337
10191337
10201338 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.
10211339
1022 - `BetaManagedAgentsWriteToolConfig object`
1023
1024 Configuration for the write tool.
1025
1026 - `type: "write"`
1027
1028 - `enabled: boolean`
1029
1030 - `name: "write"`
1031
1032 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
1033
1034 Permission policy for tool execution.
1035
1036 - `BetaManagedAgentsAlwaysAllowPolicy object`
1037
1038 Tool calls are automatically approved without user confirmation.
1039
1040 - `BetaManagedAgentsAlwaysAskPolicy object`
1041
1042 Tool calls require user confirmation before execution.
1043
1044 - `BetaManagedAgentsAutoPolicy object`
1045
1046 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.
1047
1048 - `BetaManagedAgentsGlobToolConfig object`
1049
1050 Configuration for the glob tool.
1051
1052 - `type: "glob"`
1053
1054 - `enabled: boolean`
1055
1056 - `name: "glob"`
1057
1058 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
1059
1060 Permission policy for tool execution.
1061
1062 - `BetaManagedAgentsAlwaysAllowPolicy object`
1063
1064 Tool calls are automatically approved without user confirmation.
1065
1066 - `BetaManagedAgentsAlwaysAskPolicy object`
1067
1068 Tool calls require user confirmation before execution.
1069
1070 - `BetaManagedAgentsAutoPolicy object`
1071
1072 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.
1073
1074 - `BetaManagedAgentsGrepToolConfig object`
1075
1076 Configuration for the grep tool.
1077
1078 - `type: "grep"`
1079
1080 - `enabled: boolean`
1081
1082 - `name: "grep"`
1083
1084 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
1085
1086 Permission policy for tool execution.
1087
1088 - `BetaManagedAgentsAlwaysAllowPolicy object`
1089
1090 Tool calls are automatically approved without user confirmation.
1091
1092 - `BetaManagedAgentsAlwaysAskPolicy object`
1093
1094 Tool calls require user confirmation before execution.
1095
1096 - `BetaManagedAgentsAutoPolicy object`
1097
1098 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.
1099
1100 - `BetaManagedAgentsWebFetchToolConfig object`
1101
1102 Configuration for the web_fetch tool.
1103
1104 - `type: "web_fetch"`
1105
1106 - `enabled: boolean`
1107
1108 - `name: "web_fetch"`
1109
1110 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
1111
1112 Permission policy for tool execution.
1113
1114 - `BetaManagedAgentsAlwaysAllowPolicy object`
1115
1116 Tool calls are automatically approved without user confirmation.
1117
1118 - `BetaManagedAgentsAlwaysAskPolicy object`
1119
1120 Tool calls require user confirmation before execution.
1121
1122 - `BetaManagedAgentsAutoPolicy object`
1123
1124 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.
1125
1126 - `url_sources: BetaManagedAgentsWebFetchURLSources or null`
1127
1128 Which sources contribute URLs the tool may fetch, always in the object form. Null when not set, which allows every source.
1129
1130 - `client_tool_results: BetaManagedAgentsWebFetchURLSourceToolFilter or null`
1131
1132 Which custom tools' results contribute URLs that may be fetched. Null when not set, which allows every custom tool's results.
1133
1134 - `BetaManagedAgentsWebFetchURLSourceAll object`
1135
1136 Every URL from this source may be fetched. This is the default.
1137
1138 - `type: "all"`
1139
1140 - `BetaManagedAgentsWebFetchURLSourceNone object`
1141
1142 This source contributes no URLs that may be fetched.
1143
1144 - `type: "none"`
1145
1146 - `BetaManagedAgentsWebFetchURLSourceOnly object`
1147
1148 Only the named tools' results contribute URLs that may be fetched.
1149
1150 - `type: "only"`
1151
1152 - `tools: array of BetaManagedAgentsWebFetchURLSourceToolReference`
1153
1154 The tools whose results contribute. Between 1 and 128 entries, each with a different name. An empty list is rejected; use "none" to allow no tool's results.
1155
1156 - `type: "tool_reference"`
1157
1158 Must be "tool_reference".
1159
1160 - `name: string`
1161
1162 Name of the tool. Compared exactly, so upper and lower case letters are different.
1163
1164 minLength: 1, maxLength: 128
1165
1166 - `BetaManagedAgentsWebFetchURLSourceExcept object`
1167
1168 Every tool's results contribute URLs that may be fetched, except the named tools' results.
1169
1170 - `type: "except"`
1171
1172 - `tools: array of BetaManagedAgentsWebFetchURLSourceToolReference`
1173
1174 The tools whose results do not contribute. Between 1 and 128 entries, each with a different name. An empty list is rejected; use "all" to leave out no tool's results.
1175
1176 - `type: "tool_reference"`
1177
1178 Must be "tool_reference".
1179
1180 - `name: string`
1181
1182 Name of the tool. Compared exactly, so upper and lower case letters are different.
1183
1184 minLength: 1, maxLength: 128
1185
1186 - `server_tool_results: BetaManagedAgentsWebFetchURLSourceToolFilter or null`
1187
1188 Which of the web_search and web_fetch tools' results contribute URLs that may be fetched. Null when not set, which allows both.
1189
1190 - `user_input: BetaManagedAgentsWebFetchURLSourceUserInput or null`
1191
1192 Whether URLs in the text of user messages may be fetched. Null when not set, which allows them.
1193
1194 - `BetaManagedAgentsWebFetchURLSourceAll object`
1195
1196 Every URL from this source may be fetched. This is the default.
1197
1198 - `BetaManagedAgentsWebFetchURLSourceNone object`
1199
1200 This source contributes no URLs that may be fetched.
1201
1202 - `allowed_domains: optional array of string`
1203
1204 - `blocked_domains: optional array of string`
1205
1206 - `max_content_tokens: optional number or null`
1207
1208 format: int32
1209
1210 - `BetaManagedAgentsWebSearchToolConfig object`
1211
1212 Configuration for the web_search tool.
1213
1214 - `type: "web_search"`
1215
1216 - `enabled: boolean`
1217
1218 - `name: "web_search"`
1219
1220 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
1221
1222 Permission policy for tool execution.
1223
1224 - `BetaManagedAgentsAlwaysAllowPolicy object`
1225
1226 Tool calls are automatically approved without user confirmation.
1227
1228 - `BetaManagedAgentsAlwaysAskPolicy object`
1229
1230 Tool calls require user confirmation before execution.
1231
1232 - `BetaManagedAgentsAutoPolicy object`
1233
1234 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.
1235
1236 - `allowed_domains: optional array of string`
1237
1238 - `blocked_domains: optional array of string`
1239
1240 - `user_location: optional BetaManagedAgentsUserLocation or null`
1241
1242 Approximate user location for search result localization.
1243
1244 - `type: "approximate"`
1245
1246 Location precision. Only "approximate" is supported.
1247
1248 - `city: optional string or null`
1249
1250 City name.
1251
1252 minLength: 1, maxLength: 255
1253
1254 - `country: optional string or null`
1255
1256 Two-letter ISO 3166-1 country code, uppercase.
1257
1258 - `region: optional string or null`
1259
1260 Region or state name.
1261
1262 minLength: 1, maxLength: 255
1263
1264 - `timezone: optional string or null`
1265
1266 IANA timezone identifier, e.g. "America/Los_Angeles".
1267
1268 minLength: 1, maxLength: 255
1269
1270 - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig`
1271
1272 Resolved default configuration for agent tools.
1273
1274 - `enabled: boolean`
1275
1276 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
1277
1278 Permission policy for tool execution.
1279
1280 - `BetaManagedAgentsAlwaysAllowPolicy object`
1281
1282 Tool calls are automatically approved without user confirmation.
1283
1284 - `BetaManagedAgentsAlwaysAskPolicy object`
1285
1286 Tool calls require user confirmation before execution.
1287
1288 - `BetaManagedAgentsAutoPolicy object`
1289
1290 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.
1291
1292 - `BetaManagedAgentsMCPToolset object`
1293
1294 - `type: "mcp_toolset"`
1295
1296 - `configs: array of BetaManagedAgentsMCPToolConfig`
1297
1298 - `enabled: boolean`
1340 - `mcp_server_name: string`
1341
1342 - `BetaManagedAgentsCustomTool object`
1343
1344 A custom tool as returned in API responses.
1345
1346 - `type: "custom"`
1347
1348 - `description: string`
1349
1350 - `input_schema: BetaManagedAgentsCustomToolInputSchema`
1351
1352 JSON Schema for custom tool input parameters.
1353
1354 - `type: "object"`
1355
1356 - `properties: optional map[unknown] or null`
1357
1358 - `required: optional array of string or null`
12991359
13001360 - `name: string`
13011361
1302 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
1303
1304 Permission policy for tool execution.
1305
1306 - `BetaManagedAgentsAlwaysAllowPolicy object`
1307
1308 Tool calls are automatically approved without user confirmation.
1309
1310 - `BetaManagedAgentsAlwaysAskPolicy object`
1311
1312 Tool calls require user confirmation before execution.
1313
1314 - `BetaManagedAgentsAutoPolicy object`
1315
1316 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.
1317
1318 - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig`
1319
1320 Resolved default configuration for all tools from an MCP server.
1321
1322 - `enabled: boolean`
1323
1324 - `permission_policy: BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy`
1325
1326 Permission policy for tool execution.
1327
1328 - `BetaManagedAgentsAlwaysAllowPolicy object`
1329
1330 Tool calls are automatically approved without user confirmation.
1331
1332 - `BetaManagedAgentsAlwaysAskPolicy object`
1333
1334 Tool calls require user confirmation before execution.
1335
1336 - `BetaManagedAgentsAutoPolicy object`
1337
1338 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.
1339
1340 - `mcp_server_name: string`
1341
1342 - `BetaManagedAgentsCustomTool object`
1343
1344 A custom tool as returned in API responses.
1345
1346 - `type: "custom"`
1347
1348 - `description: string`
1349
1350 - `input_schema: BetaManagedAgentsCustomToolInputSchema`
1351
1352 JSON Schema for custom tool input parameters.
1353
1354 - `type: "object"`
1355
1356 - `properties: optional map[unknown] or null`
1357
1358 - `required: optional array of string or null`
1362 - `version: number`
1363
1364 format: int32
1365
1366 - `BetaManagedAgentsAdvisor object`
1367
1368 Platform advisor roster entry: a model the session's primary thread may consult mid-turn.
1369
1370 - `type: "advisor"`
1371
1372 - `model: string`
1373
1374 The advisor model id.
1375
1376 - `BetaManagedAgentsSessionMultiagent20261001 object`
1377
1378 Resolved multiagent configuration with three members, as copied to the `session` at creation.
1379
1380 - `type: "multiagent_20261001"`
1381
1382 - `advisor: BetaManagedAgentsMultiagentAdvisor`
1383
1384 Whether the session's primary thread can consult an advisor model.
1385
1386 - `BetaManagedAgentsMultiagentAdvisorEnabled object`
1387
1388 The session's primary thread can consult `model` mid-turn.
1389
1390 - `type: "enabled"`
1391
1392 - `model: string`
1393
1394 The advisor model id.
1395
1396 - `BetaManagedAgentsMultiagentAdvisorDisabled object`
1397
1398 The agent has no advisor.
1399
1400 - `type: "disabled"`
1401
1402 - `subagents: BetaManagedAgentsSessionMultiagentSubagents`
1403
1404 Whether the agent can spawn session threads.
1405
1406 - `BetaManagedAgentsSessionMultiagentSubagentsEnabled object`
1407
1408 The agent can spawn session threads.
1409
1410 - `type: "enabled"`
1411
1412 - `inline_agents: BetaManagedAgentsMultiagentInlineAgents`
1413
1414 Whether the agent can define inline agents, which are not saved, when it spawns session threads.
1415
1416 - `BetaManagedAgentsMultiagentInlineAgentsEnabled object`
1417
1418 The agent can define inline agents.
1419
1420 - `type: "enabled"`
1421
1422 - `BetaManagedAgentsMultiagentInlineAgentsDisabled object`
1423
1424 The agent cannot define inline agents.
1425
1426 - `type: "disabled"`
1427
1428 - `predefined_agents: array of BetaManagedAgentsSessionThreadAgent`
1429
1430 Full `agent` definitions of the predefined agents, which are saved agents that this agent can spawn as session threads.
1431
1432 - `type: "agent"`
1433
1434 - `id: string`
1435
1436 - `description: string or null`
1437
1438 - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition`
1439
1440 - `model: BetaManagedAgentsModelConfig`
1441
1442 Model identifier and configuration.
13591443
13601444 - `name: string`
13611445
1362 - `version: number`
1363
1364 format: int32
1365
1366 - `BetaManagedAgentsAdvisor object`
1367
1368 Platform advisor roster entry: a model the session's primary thread may consult mid-turn.
1369
1370 - `type: "advisor"`
1371
1372 - `model: string`
1373
1374 The advisor model id.
1446 - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill`
1447
1448 - `system: string or null`
1449
1450 - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool`
1451
1452 - `version: number`
1453
1454 format: int32
1455
1456 - `BetaManagedAgentsMultiagentSubagentsDisabled object`
1457
1458 The agent cannot spawn session threads.
1459
1460 - `type: "disabled"`
1461
1462 - `workflows: BetaManagedAgentsSessionMultiagentWorkflows`
1463
1464 Whether the agent can start workflow runs.
1465
1466 - `BetaManagedAgentsSessionMultiagentWorkflowsEnabled object`
1467
1468 The agent can start workflow runs.
1469
1470 - `type: "enabled"`
1471
1472 - `inline_agents: BetaManagedAgentsMultiagentInlineAgents`
1473
1474 Whether a run's plan can define inline agents, which are not saved.
1475
1476 - `predefined_agents: array of BetaManagedAgentsSessionThreadAgent`
1477
1478 Full `agent` definitions of the predefined agents, which are saved agents that a run's plan can use.
1479
1480 - `type: "agent"`
1481
1482 - `id: string`
1483
1484 - `description: string or null`
1485
1486 - `mcp_servers: array of BetaManagedAgentsMCPServerURLDefinition`
1487
1488 - `model: BetaManagedAgentsModelConfig`
1489
1490 Model identifier and configuration.
1491
1492 - `name: string`
1493
1494 - `skills: array of BetaManagedAgentsAnthropicSkill or BetaManagedAgentsCustomSkill`
1495
1496 - `system: string or null`
1497
1498 - `tools: array of BetaManagedAgentsAgentToolset20260401 or BetaManagedAgentsMCPToolset or BetaManagedAgentsCustomTool`
1499
1500 - `version: number`
1501
1502 format: int32
1503
1504 - `BetaManagedAgentsMultiagentWorkflowsDisabled object`
1505
1506 The agent cannot start workflow runs.
1507
1508 - `type: "disabled"`
13751509
13761510 - `name: string`
13771511
13781512
api/completions Changed · +0 / -12 lines
from line 209
209209
210210 - `"claude-haiku-4-5"`
211211
212 Fastest model with near-frontier intelligence
213
214212 - `"claude-haiku-4-5-20251001"`
215213
216 Fastest model with near-frontier intelligence
217
218214 - `"claude-opus-4-5"`
219215
220216 Powerful intelligence for long-running agents and coding
from line 405
409405
410406 - `"claude-haiku-4-5"`
411407
412 Fastest model with near-frontier intelligence
413
414408 - `"claude-haiku-4-5-20251001"`
415409
416 Fastest model with near-frontier intelligence
417
418410 - `"claude-opus-4-5"`
419411
420412 Powerful intelligence for long-running agents and coding
from line 558
566558
567559 - `"claude-haiku-4-5"`
568560
569 Fastest model with near-frontier intelligence
570
571561 - `"claude-haiku-4-5-20251001"`
572
573 Fastest model with near-frontier intelligence
574562
575563 - `"claude-opus-4-5"`
576564
api/completions/create Changed · +0 / -8 lines
from line 207
207207
208208 - `"claude-haiku-4-5"`
209209
210 Fastest model with near-frontier intelligence
211
212210 - `"claude-haiku-4-5-20251001"`
213211
214 Fastest model with near-frontier intelligence
215
216212 - `"claude-opus-4-5"`
217213
218214 Powerful intelligence for long-running agents and coding
from line 403
407403
408404 - `"claude-haiku-4-5"`
409405
410 Fastest model with near-frontier intelligence
411
412406 - `"claude-haiku-4-5-20251001"`
413
414 Fastest model with near-frontier intelligence
415407
416408 - `"claude-opus-4-5"`
417409
api/messages Changed · +28 / -64 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.
from line 55
5555
5656 Each input message must be an object with a `role` and `content`. You can specify a single `user`-role message, or you can include multiple `user` and `assistant` messages.
5757
58 If the final message uses the `assistant` role, the response content will continue immediately from the content in that message. This can be used to constrain part of the model's response.
58 If the final message uses the `assistant` role, the response content will continue immediately from the content in that message. This can be used to constrain part of the model's response. This is called prefill. On models that don't support prefill, creating a message that ends with a partial `assistant` response returns a 400 error. See [Prefill not supported](https://platform.claude.com/docs/en/api/errors#prefill-not-supported).
5959
6060 Example with a single `user` message:
6161
from line 73
7373 ]
7474 ```
7575
76 Example with a partially-filled response from Claude:
76 Example with a partially-filled response from Claude, for models that support prefill:
7777
7878 ```json
7979 [
from line 1135
11351135
11361136 - `"claude-haiku-4-5"`
11371137
1138 Fastest model with near-frontier intelligence
1139
11401138 - `"claude-haiku-4-5-20251001"`
11411139
1142 Fastest model with near-frontier intelligence
1143
11441140 - `"claude-opus-4-5"`
11451141
11461142 Powerful intelligence for long-running agents and coding
from line 1313
13171313
13181314- `thinking: optional ThinkingConfigParam`
13191315
1320 Configuration for enabling Claude's extended thinking.
1316 Configuration for Claude's thinking.
13211317
1322 When enabled, responses include `thinking` content blocks showing Claude's thinking process before the final answer. Requires a minimum budget of 1,024 tokens and counts towards your `max_tokens` limit.
1318 With `{"type": "adaptive"}`, Claude decides when and how much to think. With `{"type": "enabled"}` (manual extended thinking), you set a `budget_tokens` of at least 1,024. Thinking tokens count toward your `max_tokens` limit.
13231319
1324 See [extended thinking](https://platform.claude.com/docs/en/build-with-claude/extended-thinking) for details.
1320 Which `type` values are accepted, and what happens when you omit `thinking`, depend on the model. See [thinking](https://platform.claude.com/docs/en/build-with-claude/thinking#configuring-thinking) for each model's behavior.
13251321
13261322 - `ThinkingConfigEnabled object`
13271323
from line 1335
13391335
13401336 - `display: optional "summarized" or "omitted" or null`
13411337
1342 Controls how thinking content appears in the response. When set to `summarized`, thinking is returned normally. When set to `omitted`, thinking content is redacted but a signature is returned for multi-turn continuity. Defaults to `summarized`.
1338 Controls how thinking content appears in the response. When set to `summarized`, thinking is returned normally. When set to `omitted`, thinking content is redacted but a signature is returned for multi-turn continuity. The default depends on the model; see [Controlling thinking display](https://platform.claude.com/docs/en/build-with-claude/thinking#controlling-thinking-display).
13431339
13441340 - `"summarized"`
13451341
from line 1355
13591355
13601356 - `display: optional "summarized" or "omitted" or null`
13611357
1362 Controls how thinking content appears in the response. When set to `summarized`, thinking is returned normally. When set to `omitted`, thinking content is redacted but a signature is returned for multi-turn continuity. Defaults to `summarized`.
1358 Controls how thinking content appears in the response. When set to `summarized`, thinking is returned normally. When set to `omitted`, thinking content is redacted but a signature is returned for multi-turn continuity. The default depends on the model; see [Controlling thinking display](https://platform.claude.com/docs/en/build-with-claude/thinking#controlling-thinking-display).
13631359
13641360 - `"summarized"`
13651361
from line 3980
39843980
39853981 - `"claude-haiku-4-5"`
39863982
3987 Fastest model with near-frontier intelligence
3988
39893983 - `"claude-haiku-4-5-20251001"`
39903984
3991 Fastest model with near-frontier intelligence
3992
39933985 - `"claude-opus-4-5"`
39943986
39953987 Powerful intelligence for long-running agents and coding
from line 4552
45604552
45614553 Each input message must be an object with a `role` and `content`. You can specify a single `user`-role message, or you can include multiple `user` and `assistant` messages.
45624554
4563 If the final message uses the `assistant` role, the response content will continue immediately from the content in that message. This can be used to constrain part of the model's response.
4555 If the final message uses the `assistant` role, the response content will continue immediately from the content in that message. This can be used to constrain part of the model's response. This is called prefill. On models that don't support prefill, creating a message that ends with a partial `assistant` response returns a 400 error. See [Prefill not supported](https://platform.claude.com/docs/en/api/errors#prefill-not-supported).
45644556
45654557 Example with a single `user` message:
45664558
from line 4570
45784570 ]
45794571 ```
45804572
4581 Example with a partially-filled response from Claude:
4573 Example with a partially-filled response from Claude, for models that support prefill:
45824574
45834575 ```json
45844576 [
from line 5632
56405632
56415633 - `"claude-haiku-4-5"`
56425634
5643 Fastest model with near-frontier intelligence
5644
56455635 - `"claude-haiku-4-5-20251001"`
56465636
5647 Fastest model with near-frontier intelligence
5648
56495637 - `"claude-opus-4-5"`
56505638
56515639 Powerful intelligence for long-running agents and coding
from line 5720
57325720
57335721- `thinking: optional ThinkingConfigParam`
57345722
5735 Configuration for enabling Claude's extended thinking.
5723 Configuration for Claude's thinking.
57365724
5737 When enabled, responses include `thinking` content blocks showing Claude's thinking process before the final answer. Requires a minimum budget of 1,024 tokens and counts towards your `max_tokens` limit.
5725 With `{"type": "adaptive"}`, Claude decides when and how much to think. With `{"type": "enabled"}` (manual extended thinking), you set a `budget_tokens` of at least 1,024. Thinking tokens count toward your `max_tokens` limit.
57385726
5739 See [extended thinking](https://platform.claude.com/docs/en/build-with-claude/extended-thinking) for details.
5727 Which `type` values are accepted, and what happens when you omit `thinking`, depend on the model. See [thinking](https://platform.claude.com/docs/en/build-with-claude/thinking#configuring-thinking) for each model's behavior.
57405728
57415729 - `ThinkingConfigEnabled object`
57425730
from line 5742
57545742
57555743 - `display: optional "summarized" or "omitted" or null`
57565744
5757 Controls how thinking content appears in the response. When set to `summarized`, thinking is returned normally. When set to `omitted`, thinking content is redacted but a signature is returned for multi-turn continuity. Defaults to `summarized`.
5745 Controls how thinking content appears in the response. When set to `summarized`, thinking is returned normally. When set to `omitted`, thinking content is redacted but a signature is returned for multi-turn continuity. The default depends on the model; see [Controlling thinking display](https://platform.claude.com/docs/en/build-with-claude/thinking#controlling-thinking-display).
57585746
57595747 - `"summarized"`
57605748
from line 5762
57745762
57755763 - `display: optional "summarized" or "omitted" or null`
57765764
5777 Controls how thinking content appears in the response. When set to `summarized`, thinking is returned normally. When set to `omitted`, thinking content is redacted but a signature is returned for multi-turn continuity. Defaults to `summarized`.
5765 Controls how thinking content appears in the response. When set to `summarized`, thinking is returned normally. When set to `omitted`, thinking content is redacted but a signature is returned for multi-turn continuity. The default depends on the model; see [Controlling thinking display](https://platform.claude.com/docs/en/build-with-claude/thinking#controlling-thinking-display).
57785766
57795767 - `"summarized"`
57805768
from line 8603
86158603
86168604- `BrowserHoverInput object`
86178605
8618 Move the cursor to a coordinate or element without clicking.
8619
8620 - `target: BrowserClickTarget`
8621
8622 Where to act: either a viewport coordinate or an element reference.
8623
8624 - `BrowserCoordinateTarget object`
8625
8626 A point in the browser viewport, in viewport pixels (the same frame as a
8627 full-viewport screenshot).
8628
8629 - `type: "coordinate"`
8630
8631 - `x: number`
8632
8633 Pixels from the left edge of the viewport.
8634
8635 minimum: 0
8636
8637 - `y: number`
8638
8639 Pixels from the top edge of the viewport.
8640
8641 minimum: 0
8642
8643 - `BrowserRefTarget object`
8644
8645 An element on the page, identified by a reference from a prior `read_page` or
8646 `find` result. References are scoped to the tab that produced them and become
8647 stale after navigation or a major re-render.
8648
8649 - `type: "ref"`
8650
8651 - `ref: string`
8652
8653 An element reference (e.g. "ref_7") returned by a prior `read_page` or `find` result.
8654
8655 - `tab_id: optional string or null`
8656
8657 Tab to act on. Defaults to the active tab when omitted.
8658
8659### Browser Hover Tool Use Block
8660
8661- `BrowserH
8606 Move the cursor to a coordinate or ele
api/messages/batches Changed · +9 / -29 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.
from line 75
7575
7676 Each input message must be an object with a `role` and `content`. You can specify a single `user`-role message, or you can include multiple `user` and `assistant` messages.
7777
78 If the final message uses the `assistant` role, the response content will continue immediately from the content in that message. This can be used to constrain part of the model's response.
78 If the final message uses the `assistant` role, the response content will continue immediately from the content in that message. This can be used to constrain part of the model's response. This is called prefill. On models that don't support prefill, creating a message that ends with a partial `assistant` response returns a 400 error. See [Prefill not supported](https://platform.claude.com/docs/en/api/errors#prefill-not-supported).
7979
8080 Example with a single `user` message:
8181
from line 93
9393 ]
9494 ```
9595
96 Example with a partially-filled response from Claude:
96 Example with a partially-filled response from Claude, for models that support prefill:
9797
9898 ```json
9999 [
from line 1155
11551155
11561156 - `"claude-haiku-4-5"`
11571157
1158 Fastest model with near-frontier intelligence
1159
11601158 - `"claude-haiku-4-5-20251001"`
11611159
1162 Fastest model with near-frontier intelligence
1163
11641160 - `"claude-opus-4-5"`
11651161
11661162 Powerful intelligence for long-running agents and coding
from line 1333
13371333
13381334 - `thinking: optional ThinkingConfigParam`
13391335
1340 Configuration for enabling Claude's extended thinking.
1336 Configuration for Claude's thinking.
13411337
1342 When enabled, responses include `thinking` content blocks showing Claude's thinking process before the final answer. Requires a minimum budget of 1,024 tokens and counts towards your `max_tokens` limit.
1338 With `{"type": "adaptive"}`, Claude decides when and how much to think. With `{"type": "enabled"}` (manual extended thinking), you set a `budget_tokens` of at least 1,024. Thinking tokens count toward your `max_tokens` limit.
13431339
1344 See [extended thinking](https://platform.claude.com/docs/en/build-with-claude/extended-thinking) for details.
1340 Which `type` values are accepted, and what happens when you omit `thinking`, depend on the model. See [thinking](https://platform.claude.com/docs/en/build-with-claude/thinking#configuring-thinking) for each model's behavior.
13451341
13461342 - `ThinkingConfigEnabled object`
13471343
from line 1355
13591355
13601356 - `display: optional "summarized" or "omitted" or null`
13611357
1362 Controls how thinking content appears in the response. When set to `summarized`, thinking is returned normally. When set to `omitted`, thinking content is redacted but a signature is returned for multi-turn continuity. Defaults to `summarized`.
1358 Controls how thinking content appears in the response. When set to `summarized`, thinking is returned normally. When set to `omitted`, thinking content is redacted but a signature is returned for multi-turn continuity. The default depends on the model; see [Controlling thinking display](https://platform.claude.com/docs/en/build-with-claude/thinking#controlling-thinking-display).
13631359
13641360 - `"summarized"`
13651361
from line 1375
13791375
13801376 - `display: optional "summarized" or "omitted" or null`
13811377
1382 Controls how thinking content appears in the response. When set to `summarized`, thinking is returned normally. When set to `omitted`, thinking content is redacted but a signature is returned for multi-turn continuity. Defaults to `summarized`.
1378 Controls how thinking content appears in the response. When set to `summarized`, thinking is returned normally. When set to `omitted`, thinking content is redacted but a signature is returned for multi-turn continuity. The default depends on the model; see [Controlling thinking display](https://platform.claude.com/docs/en/build-with-claude/thinking#controlling-thinking-display).
13831379
13841380 - `"summarized"`
13851381
from line 4816
48204816
48214817 - `"claude-haiku-4-5"`
48224818
4823 Fastest model with near-frontier intelligence
4824
48254819 - `"claude-haiku-4-5-20251001"`
48264820
4827 Fastest model with near-frontier intelligence
4828
48294821 - `"claude-opus-4-5"`
48304822
48314823 Powerful intelligence for long-running agents and coding
from line 6329
63376329
63386330 - `"claude-haiku-4-5"`
63396331
6340 Fastest model with near-frontier intelligence
6341
63426332 - `"claude-haiku-4-5-20251001"`
63436333
6344 Fastest model with near-frontier intelligence
6345
63466334 - `"claude-opus-4-5"`
63476335
63486336 Powerful intelligence for long-running agents and coding
from line 7614
76267614
76277615 - `"claude-haiku-4-5"`
76287616
7629 Fastest model with near-frontier intelligence
7630
76317617 - `"claude-haiku-4-5-20251001"`
76327618
7633 Fastest model with near-frontier intelligence
7634
76357619 - `"claude-opus-4-5"`
76367620
76377621 Powerful intelligence for long-running agents and coding
from line 8675
86918675
86928676 pattern: ^srvtoolu_[a-zA-Z0-9_]+$
86938677
8694 - `ToolSearchToolResultBlock object`
8695
8696 - `type: "tool_search_tool_result"`
8697
8698 default: tool_search_tool_result
8699
8700 - `content: ToolSearchToolResultError or ToolSearchToolSearchResultBlock`
8701
8702 - `ToolSearc
8678 - `ToolSearchToolR
api/messages/batches/create Changed · +9 / -13 lines
from line 73
7373
7474 Each input message must be an object with a `role` and `content`. You can specify a single `user`-role message, or you can include multiple `user` and `assistant` messages.
7575
76 If the final message uses the `assistant` role, the response content will continue immediately from the content in that message. This can be used to constrain part of the model's response.
76 If the final message uses the `assistant` role, the response content will continue immediately from the content in that message. This can be used to constrain part of the model's response. This is called prefill. On models that don't support prefill, creating a message that ends with a partial `assistant` response returns a 400 error. See [Prefill not supported](https://platform.claude.com/docs/en/api/errors#prefill-not-supported).
7777
7878 Example with a single `user` message:
7979
from line 91
9191 ]
9292 ```
9393
94 Example with a partially-filled response from Claude:
94 Example with a partially-filled response from Claude, for models that support prefill:
9595
9696 ```json
9797 [
from line 1153
11531153
11541154 - `"claude-haiku-4-5"`
11551155
1156 Fastest model with near-frontier intelligence
1157
11581156 - `"claude-haiku-4-5-20251001"`
11591157
1160 Fastest model with near-frontier intelligence
1161
11621158 - `"claude-opus-4-5"`
11631159
11641160 Powerful intelligence for long-running agents and coding
from line 1331
13351331
13361332 - `thinking: optional ThinkingConfigParam`
13371333
1338 Configuration for enabling Claude's extended thinking.
1334 Configuration for Claude's thinking.
13391335
1340 When enabled, responses include `thinking` content blocks showing Claude's thinking process before the final answer. Requires a minimum budget of 1,024 tokens and counts towards your `max_tokens` limit.
1336 With `{"type": "adaptive"}`, Claude decides when and how much to think. With `{"type": "enabled"}` (manual extended thinking), you set a `budget_tokens` of at least 1,024. Thinking tokens count toward your `max_tokens` limit.
13411337
1342 See [extended thinking](https://platform.claude.com/docs/en/build-with-claude/extended-thinking) for details.
1338 Which `type` values are accepted, and what happens when you omit `thinking`, depend on the model. See [thinking](https://platform.claude.com/docs/en/build-with-claude/thinking#configuring-thinking) for each model's behavior.
13431339
13441340 - `ThinkingConfigEnabled object`
13451341
from line 1353
13571353
13581354 - `display: optional "summarized" or "omitted" or null`
13591355
1360 Controls how thinking content appears in the response. When set to `summarized`, thinking is returned normally. When set to `omitted`, thinking content is redacted but a signature is returned for multi-turn continuity. Defaults to `summarized`.
1356 Controls how thinking content appears in the response. When set to `summarized`, thinking is returned normally. When set to `omitted`, thinking content is redacted but a signature is returned for multi-turn continuity. The default depends on the model; see [Controlling thinking display](https://platform.claude.com/docs/en/build-with-claude/thinking#controlling-thinking-display).
13611357
13621358 - `"summarized"`
13631359
from line 1373
13771373
13781374 - `display: optional "summarized" or "omitted" or null`
13791375
1380 Controls how thinking content appears in the response. When set to `summarized`, thinking is returned normally. When set to `omitted`, thinking content is redacted but a signature is returned for multi-turn continuity. Defaults to `summarized`.
1376 Controls how thinking content appears in the response. When set to `summarized`, thinking is returned normally. When set to `omitted`, thinking content is redacted but a signature is returned for multi-turn continuity. The default depends on the model; see [Controlling thinking display](https://platform.claude.com/docs/en/build-with-claude/thinking#controlling-thinking-display).
13811377
13821378 - `"summarized"`
13831379
api/messages/count_tokens Changed · +9 / -13 lines
from line 41
4141
4242 Each input message must be an object with a `role` and `content`. You can specify a single `user`-role message, or you can include multiple `user` and `assistant` messages.
4343
44 If the final message uses the `assistant` role, the response content will continue immediately from the content in that message. This can be used to constrain part of the model's response.
44 If the final message uses the `assistant` role, the response content will continue immediately from the content in that message. This can be used to constrain part of the model's response. This is called prefill. On models that don't support prefill, creating a message that ends with a partial `assistant` response returns a 400 error. See [Prefill not supported](https://platform.claude.com/docs/en/api/errors#prefill-not-supported).
4545
4646 Example with a single `user` message:
4747
from line 59
5959 ]
6060 ```
6161
62 Example with a partially-filled response from Claude:
62 Example with a partially-filled response from Claude, for models that support prefill:
6363
6464 ```json
6565 [
from line 1121
11211121
11221122 - `"claude-haiku-4-5"`
11231123
1124 Fastest model with near-frontier intelligence
1125
11261124 - `"claude-haiku-4-5-20251001"`
11271125
1128 Fastest model with near-frontier intelligence
1129
11301126 - `"claude-opus-4-5"`
11311127
11321128 Powerful intelligence for long-running agents and coding
from line 1209
12131209
12141210- `thinking: optional ThinkingConfigParam`
12151211
1216 Configuration for enabling Claude's extended thinking.
1212 Configuration for Claude's thinking.
12171213
1218 When enabled, responses include `thinking` content blocks showing Claude's thinking process before the final answer. Requires a minimum budget of 1,024 tokens and counts towards your `max_tokens` limit.
1214 With `{"type": "adaptive"}`, Claude decides when and how much to think. With `{"type": "enabled"}` (manual extended thinking), you set a `budget_tokens` of at least 1,024. Thinking tokens count toward your `max_tokens` limit.
12191215
1220 See [extended thinking](https://platform.claude.com/docs/en/build-with-claude/extended-thinking) for details.
1216 Which `type` values are accepted, and what happens when you omit `thinking`, depend on the model. See [thinking](https://platform.claude.com/docs/en/build-with-claude/thinking#configuring-thinking) for each model's behavior.
12211217
12221218 - `ThinkingConfigEnabled object`
12231219
from line 1231
12351231
12361232 - `display: optional "summarized" or "omitted" or null`
12371233
1238 Controls how thinking content appears in the response. When set to `summarized`, thinking is returned normally. When set to `omitted`, thinking content is redacted but a signature is returned for multi-turn continuity. Defaults to `summarized`.
1234 Controls how thinking content appears in the response. When set to `summarized`, thinking is returned normally. When set to `omitted`, thinking content is redacted but a signature is returned for multi-turn continuity. The default depends on the model; see [Controlling thinking display](https://platform.claude.com/docs/en/build-with-claude/thinking#controlling-thinking-display).
12391235
12401236 - `"summarized"`
12411237
from line 1251
12551251
12561252 - `display: optional "summarized" or "omitted" or null`
12571253
1258 Controls how thinking content appears in the response. When set to `summarized`, thinking is returned normally. When set to `omitted`, thinking content is redacted but a signature is returned for multi-turn continuity. Defaults to `summarized`.
1254 Controls how thinking content appears in the response. When set to `summarized`, thinking is returned normally. When set to `omitted`, thinking content is redacted but a signature is returned for multi-turn continuity. The default depends on the model; see [Controlling thinking display](https://platform.claude.com/docs/en/build-with-claude/thinking#controlling-thinking-display).
12591255
12601256 - `"summarized"`
12611257
api/messages/create Changed · +9 / -17 lines
from line 53
5353
5454 Each input message must be an object with a `role` and `content`. You can specify a single `user`-role message, or you can include multiple `user` and `assistant` messages.
5555
56 If the final message uses the `assistant` role, the response content will continue immediately from the content in that message. This can be used to constrain part of the model's response.
56 If the final message uses the `assistant` role, the response content will continue immediately from the content in that message. This can be used to constrain part of the model's response. This is called prefill. On models that don't support prefill, creating a message that ends with a partial `assistant` response returns a 400 error. See [Prefill not supported](https://platform.claude.com/docs/en/api/errors#prefill-not-supported).
5757
5858 Example with a single `user` message:
5959
from line 71
7171 ]
7272 ```
7373
74 Example with a partially-filled response from Claude:
74 Example with a partially-filled response from Claude, for models that support prefill:
7575
7676 ```json
7777 [
from line 1133
11331133
11341134 - `"claude-haiku-4-5"`
11351135
1136 Fastest model with near-frontier intelligence
1137
11381136 - `"claude-haiku-4-5-20251001"`
11391137
1140 Fastest model with near-frontier intelligence
1141
11421138 - `"claude-opus-4-5"`
11431139
11441140 Powerful intelligence for long-running agents and coding
from line 1311
13151311
13161312- `thinking: optional ThinkingConfigParam`
13171313
1318 Configuration for enabling Claude's extended thinking.
1314 Configuration for Claude's thinking.
13191315
1320 When enabled, responses include `thinking` content blocks showing Claude's thinking process before the final answer. Requires a minimum budget of 1,024 tokens and counts towards your `max_tokens` limit.
1316 With `{"type": "adaptive"}`, Claude decides when and how much to think. With `{"type": "enabled"}` (manual extended thinking), you set a `budget_tokens` of at least 1,024. Thinking tokens count toward your `max_tokens` limit.
13211317
1322 See [extended thinking](https://platform.claude.com/docs/en/build-with-claude/extended-thinking) for details.
1318 Which `type` values are accepted, and what happens when you omit `thinking`, depend on the model. See [thinking](https://platform.claude.com/docs/en/build-with-claude/thinking#configuring-thinking) for each model's behavior.
13231319
13241320 - `ThinkingConfigEnabled object`
13251321
from line 1333
13371333
13381334 - `display: optional "summarized" or "omitted" or null`
13391335
1340 Controls how thinking content appears in the response. When set to `summarized`, thinking is returned normally. When set to `omitted`, thinking content is redacted but a signature is returned for multi-turn continuity. Defaults to `summarized`.
1336 Controls how thinking content appears in the response. When set to `summarized`, thinking is returned normally. When set to `omitted`, thinking content is redacted but a signature is returned for multi-turn continuity. The default depends on the model; see [Controlling thinking display](https://platform.claude.com/docs/en/build-with-claude/thinking#controlling-thinking-display).
13411337
13421338 - `"summarized"`
13431339
from line 1353
13571353
13581354 - `display: optional "summarized" or "omitted" or null`
13591355
1360 Controls how thinking content appears in the response. When set to `summarized`, thinking is returned normally. When set to `omitted`, thinking content is redacted but a signature is returned for multi-turn continuity. Defaults to `summarized`.
1356 Controls how thinking content appears in the response. When set to `summarized`, thinking is returned normally. When set to `omitted`, thinking content is redacted but a signature is returned for multi-turn continuity. The default depends on the model; see [Controlling thinking display](https://platform.claude.com/docs/en/build-with-claude/thinking#controlling-thinking-display).
13611357
13621358 - `"summarized"`
13631359
from line 3978
39823978
39833979 - `"claude-haiku-4-5"`
39843980
3985 Fastest model with near-frontier intelligence
3986
39873981 - `"claude-haiku-4-5-20251001"`
3988
3989 Fastest model with near-frontier intelligence
39903982
39913983 - `"claude-opus-4-5"`
39923984
build-with-claude/preserved-thinking Changed · +10 / -2 lines
#### Output-token cost of `"drop_block"`
from line 97
9797* **`"drop_block"`:** the API drops each failing block and every thinking block after it, and the request succeeds. Dropped blocks aren't billed. The model answers that turn without using reasoning from dropped blocks, and the prompt cache restarts at the edit. The response lists each dropped block in `input_transformations` (on the `message_start` event when streaming) with `reason: "prefix_binding_mismatch"`.
9898
9999<Warning>
100 `"drop_block"` hides the error but doesn't fix the edit that caused it. Dropped blocks aren't billed, but a session's token usage might still increase because Claude can sometimes think more to re-create the dropped thinking. The increase tends to be larger when more thinking blocks are dropped, or when blocks are dropped on more turns of a long session.
100 `"drop_block"` keeps requests succeeding, but it doesn't fix the edit that caused the mismatch, and it has a cost. Dropping blocks can significantly increase the output tokens generated, especially at higher effort levels or when blocks are dropped on every turn. For more information, see [Output-token cost of `"drop_block"`](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#drop-block-cost). Dropped blocks aren't billed, but Claude re-creates the reasoning it can no longer read, so it generates more output tokens. Output quality might also change on tasks where later turns build on earlier reasoning. Use `"drop_block"` as a stopgap while you fix the edit, but not as a long-term setting.
101101</Warning>
102102
103103Count the responses in each session whose `input_transformations` has a `prefix_binding_mismatch` entry, alert on them, and replace each edit with the matching pattern in [Make changes without editing the prefix](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#replace-prefix-edits). In the Message Batches API, an item that leaves the field unset doesn't fail. Where the API enforces the check by default, it drops the failing blocks instead. Set `"error"` explicitly there if you want batch items to fail.
from line 120
120120
121121A tampered or undecryptable signature is a different failure. It always returns a 400 (``Invalid `signature` in `thinking` block`` with no sentence about the conversation), and `prefix_mismatch_behavior` doesn't apply to it.
122122
123#### Output-token cost of `"drop_block"`
124
125In Anthropic's testing on a multi-turn coding benchmark, dropping thinking blocks once per session increased output tokens by 2.5% at low effort, 3.9% at medium, 4.5% at high, and 20.1% at max. Dropping them on every turn after the first increased output tokens by 4.6% at low effort, 9.7% at medium, 10.3% at high, and 67.1% at max. The exact impact depends on your harness.
126
127When Claude can no longer read reasoning from earlier turns, it re-creates that reasoning, so requests that drop thinking blocks generate more output tokens and can take longer to respond. A drop on every turn costs more than an occasional drop, and how much more depends on your harness: how often it edits the prefix and how much each turn builds on earlier reasoning.
128
129Before you rely on `"drop_block"`, run evals on your own workload to measure the increase. If it's small, `"drop_block"` can keep requests succeeding while you fix the edit. Either way, fixing the edit with a pattern from [Make changes without editing the prefix](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#replace-prefix-edits) is a better long-term solution.
130
123131#### Handle the error in code
124132
125This is the 400 `invalid_request_error` shown earlier in this section. Don't resend the same body: it fails the same way every time. Retry once with the beta header and `prefix_mismatch_behavior: "drop_block"`, and store that choice with the session so every later request sends it too, including after a restart. On Claude Sonnet 5.5 and Claude Haiku 5.5, `block_binding` works only with `thinking: {"type": "adaptive"}`. With `between_tools` on Claude Sonnet 5.5, or `thinking: {"type": "disabled"}` on Claude Haiku 5.5, keep the history append-only, or strip the thinking blocks from the edited turn on. If you can't send the beta header, remove every `thinking` and `redacted_thinking` block from the history once, leave them out, and continue. Then fix the edit that caused the mismatch.
133This is the 400 `invalid_request_error` shown earlier in this section. Don't resend the same body: it fails the same way every time. Retry once with the beta header and `prefix_mismatch_behavior: "drop_block"`, as a stopgap ([`"drop_block"` can raise output tokens](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#drop-block-cost)), and store that choice with the session so every later request sends it too, including after a restart. On Claude Sonnet 5.5 and Claude Haiku 5.5, `block_binding` works only with `thinking: {"type": "adaptive"}`. With `between_tools` on Claude Sonnet 5.5, or `thinking: {"type": "disabled"}` on Claude Haiku 5.5, keep the history append-only, or strip the thinking blocks from the edited turn on. If you can't send the beta header, remove every `thinking` and `redacted_thinking` block from the history once, leave them out, and continue. Then fix the edit that caused the mismatch.
126134
127135### Set the mismatch behavior and read `input_transformations`
128136
cli-sdks-libraries/sdks/typescript Changed · +4 / -4 lines
from line 478
478478 Consider using the streaming [Messages API](https://platform.claude.com/docs/en/cli-sdks-libraries/sdks/typescript#streaming-responses) for longer running requests.
479479</Warning>
480480
481Avoid setting a large `max_tokens` value without using streaming. Some networks may drop idle connections after a certain period of time, which can cause the request to fail or [timeout](https://platform.claude.com/docs/en/cli-sdks-libraries/sdks/typescript#timeouts) without receiving a response from Anthropic.
481Avoid setting a large `max_tokens` value without using streaming. Some networks may drop idle connections after a certain period of time, which can cause the request to fail or [time out](https://platform.claude.com/docs/en/cli-sdks-libraries/sdks/typescript#timeouts) without receiving a response from Anthropic.
482482
483483This SDK also throws an error if a non-streaming request is expected to be above roughly 10 minutes long. Passing `stream: true` or [overriding](https://platform.claude.com/docs/en/cli-sdks-libraries/sdks/typescript#timeouts) the `timeout` option at the client or request level disables this error.
484484
from line 726
726726
727727## Beta features
728728
729Beta features are available before general release to get early feedback and test new functionality. You can check the availability of all of Claude's capabilities and tools in the [build with Claude overview](https://platform.claude.com/docs/en/build-with-claude/overview).
729Beta features are available before general release to get early feedback and test new functionality. You can check the availability of all of Claude's capabilities and tools in the [Features overview](https://platform.claude.com/docs/en/build-with-claude/overview).
730730
731You can access most beta API features through the beta property of the client. To enable a particular beta feature, you need to add the appropriate [beta header](https://platform.claude.com/docs/en/api/beta-headers) to the `betas` field when creating a message.
731You can access most beta API features through the `beta` property of the client. To enable a particular beta feature, you need to add the appropriate [beta header](https://platform.claude.com/docs/en/api/beta-headers) to the `betas` field when creating a message.
732732
733733For example, to enable [context editing](https://platform.claude.com/docs/en/build-with-claude/context-editing):
734734
managed-agents/budgets Changed · +10 / -6 lines
from line 10
1010 betaHeader: managed-agents-2026-04-01
1111---
1212
13A session budget is an optional hard spend ceiling you set when you [create a session](https://platform.claude.com/docs/en/managed-agents/sessions). The platform continuously prices everything the session consumes at public list rates (the session's **list cost**) and stops issuing new model requests once that cost reaches the budget. The request in flight when the cap is crossed still finishes, so the final list cost can land [a fraction past the budget](https://platform.claude.com/docs/en/managed-agents/budgets#when-a-session-reaches-its-budget). A session at its budget pauses and goes [idle](https://platform.claude.com/docs/en/managed-agents/session-operations#session-statuses) rather than terminating; changing or removing the budget resumes its work automatically. Deployments accept the same budget and apply it to each session they start; see [Budgets on deployments](https://platform.claude.com/docs/en/managed-agents/budgets#budgets-on-deployments).
13A session budget is an optional hard spend ceiling you set when you [create a session](https://platform.claude.com/docs/en/managed-agents/sessions). The platform continuously prices everything the session consumes at public list rates (the session's **list cost**) and stops issuing new model requests once that cost reaches the budget. The request in flight when the cap is crossed still finishes, so the final list cost can land [a fraction past the budget](https://platform.claude.com/docs/en/managed-agents/budgets#when-a-session-reaches-its-budget). A session at its budget pauses and goes [idle](https://platform.claude.com/docs/en/managed-agents/session-operations#session-statuses) rather than terminating; changing or removing the budget resumes the work that the budget paused. Deployments accept the same budget and apply it to each session they start; see [Budgets on deployments](https://platform.claude.com/docs/en/managed-agents/budgets#budgets-on-deployments).
1414
1515## Set a budget at session creation
1616
from line 153
153153The platform prices what the session consumes, continuously, at public list rates:
154154
155155* **Model tokens**, at each served model's list price
156* **Web searches**, at $10 per 1,000 searches
157* **Session running time**, at $0.08 per hour
156* **Web searches**, at $10 USD per 1,000 searches
157* **Session running time**, at $0.08 USD per hour
158158
159159This running dollar total is the session's **list cost**, and it is what the budget compares against. List cost is not your contracted price: if your organization has negotiated discounts, the session reaches its cap when the list-price total does, and your billed spend might be lower than the cap.
160160
from line 185
185185
186186Any event that would start new work, such as `user.message`, is rejected with a 400 error naming this list. Settled results are recorded without triggering a new model request; the session stays paused at its budget.
187187
188A `user.interrupt` sent while the session is paused at its budget (all threads paused at the cap) is accepted and ignored: it does not appear in the event list and changes nothing. Change or remove the budget to continue. It sends no [workflow run](https://platform.claude.com/docs/en/managed-agents/workflow-runs#budgets-and-limits) event either: the budget has already paused every open run.
188A `user.interrupt` sent while the session is paused at its budget (all threads paused at the cap) is accepted, and it does not appear in the event list. It stops no thread, because every thread is already paused. Change or remove the budget to continue.
189189
190If the session has open [workflow runs](https://platform.claude.com/docs/en/managed-agents/workflow-runs#interrupt-a-session-with-runs-open), the interrupt can pause them, as an interrupt at any other time can. A run that an interrupt paused doesn't resume when you change or remove the budget. To continue it, change or remove the budget, then send a `user.message` asking the agent to continue its runs.
191
190192## Resume a session at its budget
191193
192Change or remove the budget with a session update. An accepted update resumes the session's paused work automatically; no further client action is needed. Each [workflow run](https://platform.claude.com/docs/en/managed-agents/workflow-runs#budgets-and-limits) that the budget paused also gets a `workflow_run.status_running` event.
194Change or remove the budget with a session update. An accepted update automatically resumes the work that the budget paused; no further client action is needed.
193195
196Each [workflow run](https://platform.claude.com/docs/en/managed-agents/workflow-runs#budgets-and-limits) that the budget paused also gets a `workflow_run.status_running` event. A run that an interrupt paused, even an interrupt sent while the session was at its budget, stays paused and gets no `workflow_run.status_running` event from the update. To continue it, send a `user.message` asking the agent to continue its runs. See [Interrupt a session with runs open](https://platform.claude.com/docs/en/managed-agents/workflow-runs#interrupt-a-session-with-runs-open).
197
194198### Change the budget
195199
196200Update the session with a new `max_list_cost`. The new value can be higher or lower than the current cap, but it must be strictly greater than the session's consumed list cost; otherwise the update is rejected with a 400 error: `budget.max_list_cost must be greater than the session's consumed list cost`. Because the consumed cost usually sits [a fraction past the old cap](https://platform.claude.com/docs/en/managed-agents/budgets#when-a-session-reaches-its-budget) when the session pauses, base the new value on the session's reported `usage.list_cost`, not on the old `max_list_cost`. Set it a cent or more above that figure: the reported value is rounded and can sit a fraction below the exact consumed cost the check uses.
from line 307
303307
304308### Remove the budget
305309
306Set `budget` to `null` to remove the cap entirely. The session's paused work resumes, and the resulting `session.updated` event carries `budget` set to `null`.
310Set `budget` to `null` to remove the cap entirely. The work that the budget paused resumes, and the resulting `session.updated` event carries `budget` set to `null`.
307311
308312<CodeGroup>
309313 ```bash cURL
managed-agents/session-threads New page · 815 lines, new page
## Primary thread and session threads ## List threads ## Interrupt a session thread ## Archive a session thread ## Primary thread events ## Session thread events ## Tool permissions and custom tools
A whole new page. There's nothing to diff it against, so here is what it says.
---
title: Session threads
url: https://platform.claude.com/docs/en/managed-agents/session-threads
description: List, interrupt, and archive the threads of a multiagent session, read their events, and handle tool permissions across them.
featureMetadata:
topic:
title: Managed Agents
url: https://platform.claude.com/docs/en/managed-agents/overview
status: beta
betaHeader: managed-agents-2026-04-01
---
In a [multiagent session](https://platform.claude.com/docs/en/managed-agents/multiagent-orchestration), each agent works in its own **session thread**. This page covers how to list, interrupt, and archive threads, the events they send, and how tool permissions work across them. A [workflow run](https://platform.claude.com/docs/en/managed-agents/workflow-runs) creates session threads too.
## Primary thread and session threads
The **session-level event stream** (`/v1/sessions/{session_id}/events/stream`) is considered the **primary thread**, containing a condensed view of all activity across all threads. You don't see the full activity from [subagents](https://platform.claude.com/docs/en/managed-agents/multiagent-orchestration#delegate-to-subagents), but you do see the start and end of their work, and blocking events such as tool permission requests.
**Session threads** are where you drill into a specific agent's activity.
The session `status` is an aggregation of all agent activity; if at least one thread is `running`, then the overall session status is `running` as well. A [workflow run](https://platform.claude.com/docs/en/managed-agents/workflow-runs) that's running can keep the session `running` too, even while none of its threads is working. When no thread is working and a thread waits on your client, the session is `idle`; see [Know when the work is done](https://platform.claude.com/docs/en/managed-agents/workflow-runs#know-when-the-work-is-done).
A [session budget](https://platform.claude.com/docs/en/managed-agents/budgets) is a single shared cap across all of a session's threads. As the cap is reached, threads pause independently, and each thread's cost is priced at the thread's own served model.
<Note>
A session can have at most 25 child threads at a time. Idle threads count until you archive them, and the primary thread doesn't count. The primary thread's agent can call multiple copies of a single subagent, creating multiple threads associated with one `agent`. [Advisor](https://platform.claude.com/docs/en/managed-agents/multiagent-orchestration#give-the-session-an-advisor) consultation threads are exempt from this limit. So are a [workflow run](https://platform.claude.com/docs/en/managed-agents/workflow-runs)'s threads.
</Note>
## List threads
List all threads associated with a session as follows:
<CodeGroup>
```bash cURL
curl -fsS "https://api.anthropic.com/v1/sessions/$SESSION_ID/threads" \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "anthropic-beta: managed-agents-2026-04-01"
```
```bash CLI
ant beta:sessions:threads list --session-id "$SESSION_ID"
```
```python Python
for thread in client.beta.sessions.threads.list(session.id):
agent = thread.agent
label = agent.type if agent.type == "advisor" else agent.name
print(f"[{label}] {thread.status}")
```
```typescript TypeScript
for await (const thread of client.beta.sessions.threads.list(session.id)) {
const label = thread.agent.type === "advisor" ? thread.agent.type : thread.agent.name;
console.log(`[${label}] ${thread.status}`);
}
```
```csharp C#
await foreach (var thread in (await client.Beta.Sessions.Threads.List(session.ID)).Paginate())
{
var label = thread.Agent.TryPickBetaManagedAgentsSessionThread(out var agent)
? agent.Name
: thread.Agent.Json.GetProperty("type").GetString();
Console.WriteLine($"[{label}] {thread.Status.Raw()}");
}
```
```go Go
threads := client.Beta.Sessions.Threads.ListAutoPaging(ctx, session.ID, anthropic.BetaSessionThreadListParams{})
for threads.Next() {
thread := threads.Current()
label := cmp.Or(thread.Agent.Name, thread.Agent.Type)
fmt.Printf("[%s] %s\n", label, thread.Status)
}
if err := threads.Err(); err != nil {
panic(err)
}
```
```java Java
for (var thread : client.beta().sessions().threads().list(session.id()).autoPager()) {
var agent = thread.agent();
var label = agent.isAgent() ? agent.asAgent().name() : agent.type().asString();
IO.println("[" + label + "] " + thread.status());
}
```
```php PHP
foreach ($client->beta->sessions->threads->list($session->id)->pagingEachItem() as $thread) {
$label = $thread->agent instanceof \Anthropic\Beta\Agents\BetaManagedAgentsAdvisor
? $thread->agent->type
: $thread->agent->name;
echo "[{$label}] {$thread->status}\n";
}
```
```ruby Ruby
client.beta.sessions.threads.list(session.id).auto_paging_each do |thread|
agent = thread.agent
label = agent.type == :advisor ? agent.type : agent.name
puts "[#{label}] #{thread.status}"
end
```
</CodeGroup>
The full list includes the primary thread. `parent_thread_id` is `null` for the primary thread. Every other thread is a child thread. `workflow_run_id` is `null` except on [a run's threads](https://platform.claude.com/docs/en/managed-agents/workflow-runs#a-runs-threads).
To list only threads that have certain statuses, add `statuses[]` to the request, and repeat it to give more than one status, as in `?statuses[]=running&statuses[]=idle`. Leave it out to return threads of every status.
## Interrupt a session thread
Send `user.interrupt` with `session_thread_id` to stop a specific thread. Omitting `session_thread_id` interrupts every non-archived thread in the session, including the primary. In a session with dynamic workflows, an interrupt ends no run, and one that names a run's thread stops nothing. An interrupt closes other child threads' pending tool calls, but don't rely on it to close a run thread's. See [Interrupt a session with runs open](https://platform.claude.com/docs/en/managed-agents/workflow-runs#interrupt-a-session-with-runs-open).
<CodeGroup>
```bash cURL
curl -fsS "https://api.anthropic.com/v1/sessions/$SESSION_ID/events?beta=true" \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "anthropic-beta: managed-agents-2026-04-01" \
-H "content-type: application/json" \
-d "{\"events\": [{\"type\": \"user.interrupt\", \"session_thread_id\": \"$THREAD_ID\"}]}"
```
```bash CLI
ant beta:sessions:events send \
--session-id "$SESSION_ID" \
--event "{type: user.interrupt, session_thread_id: $THREAD_ID}"
```
```python Python
client.beta.sessions.events.send(
session.id,
events=[{"type": "user.interrupt", "session_thread_id": thread.id}],
)
```
```typescript TypeScript
await client.beta.sessions.events.send(session.id, {
events: [{ type: "user.interrupt", session_thread_id: thread.id }],
});
```
```csharp C#
await client.Beta.Sessions.Events.Send(session.ID, new()
{
Events =
[
new BetaManagedAgentsUserInterruptEventParams
{
Type = BetaManagedAgentsUserInterruptEventParamsType.UserInterrupt,
SessionThreadID = thread.ID,
},
],
});
```
```go Go
if _, err := client.Beta.Sessions.Events.Send(ctx, session.ID, anthropic.BetaSessionEventSendParams{
Events: []anthropic.BetaManagedAgentsEventParamsUnion{{
OfUserInterrupt: &anthropic.BetaManagedAgentsUserInterruptEventParams{
Type: anthropic.BetaManagedAgentsUserInterruptEventParamsTypeUserInterrupt,
SessionThreadID: anthropic.String(thread.ID),
},
}},
}); err != nil {
panic(err)
}
```
```java Java
client.beta().sessions().events().send(
session.id(),
EventSendParams.builder()
.addEvent(BetaManagedAgentsUserInterruptEventParams.builder()
.type(BetaManagedAgentsUserInterruptEventParams.Type.USER_INTERRUPT)
.sessionThreadId(thread.id())
.build())
.build());
```
```php PHP
$client->beta->sessions->events->send(
$session->id,
events: [
['type' => 'user.interrupt', 'session_thread_id' => $thread->id],
],
);
```
```ruby Ruby
client.beta.sessions.events.send_(
session.id,
events: [{type: "user.interrupt", session_thread_id: thread.id}]
)
```
</CodeGroup>
Against a subagent's thread blocked on `requires_action`, the interrupt closes each pending tool call with an error tool result ("Tool execution was interrupted before completion. Please retry.") and re-emits `session.thread_status_idle` with `stop_reason: end_turn` directly; the model is not sampled. Against a child thread that's idle with `end_turn` or `budget_reached`, the interrupt is a no-op. An interrupt that names a terminated thread returns a 400 error. An interrupted child doesn't send the primary thread's agent the report it sends when a turn ends. While that agent waits on the child, it doesn't start another turn until something else reaches it, such as a `user.message` or another thread's report.
## Archive a session thread
Optionally archive a session thread when it has completed its work. Archiving a thread frees its place under the 25-child-thread limit. The server archives a [workflow run](https://platform.claude.com/docs/en/managed-agents/workflow-runs)'s threads itself. You don't need to archive them, and you can't while the run is open.
<CodeGroup>
```bash cURL
curl -fsS -X POST "https://api.anthropic.com/v1/sessions/$SESSION_ID/threads/$THREAD_ID/archive" \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "anthropic-beta: managed-agents-2026-04-01"
```
```bash CLI
ant beta:sessions:threads archive \
--session-id "$SESSION_ID" \
--thread-id "$THREAD_ID"
```
```python Python
archived = client.beta.sessions.threads.archive(thread.id, session_id=session.id)
print(archived.status, archived.archived_at)
```
```typescript TypeScript
const archived = await client.beta.sessions.threads.archive(thread.id, {
session_id: session.id,
});
console.log(archived.status, archived.archived_at);
```
```csharp C#
var archived = await client.Beta.Sessions.Threads.Archive(thread.ID, new() { SessionID = session.ID });
Console.WriteLine($"{archived.Status} {archived.ArchivedAt}");
```
```go Go
archived, err := client.Beta.Sessions.Threads.Archive(ctx, thread.ID, anthropic.BetaSessionThreadArchiveParams{
SessionID: session.ID,
})
if err != nil {
panic(err)
}
fmt.Println(archived.Status, archived.ArchivedAt)
```
```java Java
var archived = client.beta().sessions().threads().archive(
thread.id(),
ThreadArchiveParams.builder()
.sessionId(session.id())
.build());
IO.println(archived.status() + " " + archived.archivedAt().orElseThrow());
```
```php PHP
$archived = $client->beta->sessions->threads->archive($thread->id, sessionID: $session->id);
echo "{$archived->status} {$archived->archivedAt->format(DATE_ATOM)}\n";
```
```ruby Ruby
archived = client.beta.sessions.threads.archive(thread.id, session_id: session.id)
puts "#{archived.status} #{archived.archived_at}"
```
</CodeGroup>
Archive only succeeds if the thread is `idle`. A thread parked on `requires_action` counts as idle and can be archived directly; only a running thread must be interrupted first:
<CodeGroup>
```bash cURL
# Interrupt the thread, then archive it
curl -fsS "https://api.anthropic.com/v1/sessions/$SESSION_ID/events?beta=true" \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "anthropic-beta: managed-agents-2026-04-01" \
-H "content-type: application/json" \
-d "{\"events\": [{\"type\": \"user.interrupt\", \"session_thread_id\": \"$THREAD_ID\"}]}"
curl -fsS -X POST "https://api.anthropic.com/v1/sessions/$SESSION_ID/threads/$THREAD_ID/archive" \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "anthropic-beta: managed-agents-2026-04-01"
```
```bash CLI
ant beta:sessions:events send \
--session-id "$SESSION_ID" \
--event "{type: user.interrupt, session_thread_id: $THREAD_ID}"
ant beta:sessions:threads archive \
--session-id "$SESSION_ID" \
--thread-id "$THREAD_ID"
```
```python Python
client.beta.sessions.events.send(
session.id,
events=[{"type": "user.interrupt", "session_thread_id": thread.id}],
)
archived = client.beta.sessions.threads.archive(thread.id, session_id=session.id)
print(archived.status, archived.archived_at)
Cut at 300 lines. The page has the rest.
managed-agents/workflow-runs New page · 824 lines, new page
## How dynamic workflows work ## How a run moves through its states ## Run events ## A run's threads ## Know when the work is done ## Follow a run ## Interrupt a session with runs open ## While a run is open ### Rebuild run state after you reconnect ## Budgets and limits ### Rate limits
A whole new page. There's nothing to diff it against, so here is what it says.
---
title: Workflow runs
url: https://platform.claude.com/docs/en/managed-agents/workflow-runs
description: "Follow an agent's workflow runs: their states and events, when the work is done, what a run blocks, budgets, and limits."
featureMetadata:
topic:
title: Managed Agents
url: https://platform.claude.com/docs/en/managed-agents/overview
status: beta
betaHeader: managed-agents-2026-04-01
---
A **workflow** is a program that an agent writes to run many agents and combine what they return. A **workflow run** is the execution of one workflow. **[Dynamic workflows](https://platform.claude.com/docs/en/managed-agents/multiagent-orchestration#dynamic-workflows)** is the feature that lets an agent write workflows and start runs. You turn it on or off with the `workflows` setting in the agent's `multiagent` block.
The server runs a workflow in the background. Its agents work in [session threads](https://platform.claude.com/docs/en/managed-agents/session-threads) that the server creates as the workflow needs them. You follow runs on the session's [event stream](https://platform.claude.com/docs/en/managed-agents/events-and-streaming). Only the agent starts a run. No event you send ends one; archiving the session can.
## How dynamic workflows work
The agent that the session runs writes each workflow for the work that you describe. A workflow is a program: it runs other agents, collects what each one returns, and combines the results. That way, the agent can take on a task that is too large for one conversation, such as a review of hundreds of documents. During a run, the agent can keep working or end its turn, and it can check on the run.
<Frame>
</Frame>
The diagram shows one example. Each workflow that the agent writes has its own phases and agents. A run has these layers:
* **Workflow run:** The server runs the workflow in the background, as one workflow run. A session can have several runs open at the same time.
* **Phases:** A workflow can divide its work into phases. A phase is a named stage of the run, such as "Read the contracts". You follow a run's progress by its phase events.
* **Agent threads:** In a phase, the program runs agents. Each agent works in its own [session thread](https://platform.claude.com/docs/en/managed-agents/session-threads), on a prompt that the program wrote. An agent in a run can be an inline agent, which the program defines itself, or a predefined agent, which you list in [`workflows.predefined_agents`](https://platform.claude.com/docs/en/managed-agents/multiagent-orchestration#predefined-and-inline-agents). For what each thread shows, see [A run's threads](https://platform.claude.com/docs/en/managed-agents/workflow-runs#a-runs-threads).
The program can do the following:
* **Run agents at the same time:** The program can run many agents at the same time, which is called fanning out. In the diagram, three agents read contracts in the first phase.
* **Pass results from one agent to another:** Each agent returns its result to the program. The program can pass that result on to another agent. In the diagram, the agent in the second phase works with what the first three returned. A run's agents also work with the same files, in the session's sandbox.
* **Take the next step by itself:** An agent's result goes to the program, not to the agent that the session runs. The program determines which agents run next, and it writes their prompts.
* **Repeat and choose:** Inside a phase, the program can repeat work and choose its next step from what an agent returned. For example, it can have a draft revised until a review passes or a set number of rounds is used up. In the diagram, the program can repeat a step inside the second phase.
* **Handle a failed agent:** When one of its agents fails, the program can handle the failure or let it end the run.
When the run ends, the agent that the session runs gets a turn to read what the run did. It can then answer you or start another run. [Run events](https://platform.claude.com/docs/en/managed-agents/workflow-runs#run-events) lists the cases where that turn comes later or doesn't come.
You can guide how a run does the work, for example how it splits the work and what it does when an agent fails. See [Tell the agent when to use a run](https://platform.claude.com/docs/en/managed-agents/multiagent-orchestration#tell-the-agent-when-to-use-a-run).
## How a run moves through its states
<Frame>
</Frame>
A run starts as running or as idle. Reaching the budget, for example, pauses a running run, which makes it idle; raising or removing the budget then makes it run again, unless an interrupt paused it too. A running run ends when its workflow finishes, the agent stops it, it fails, its lifetime passes, or the session is archived. An idle run can end too, for example when the agent stops it or the session is archived.
A run is **open** from its `workflow_run.created` event until its `workflow_run.status_ended` event, whether it's running or idle. A run is idle while it's paused, for example at the session's budget. A run's lifetime is 24 hours by default. The agent can set a shorter lifetime when it starts the run. Time that a run spends waiting on your client counts toward that lifetime. A pause doesn't stop a run's lifetime from passing, so a run that stays paused can end with `timeout_error`. The following events report a run's start, its phases, and its end. A pause at the budget sends one too. A pause after an interrupt might send none. Every `workflow_run.*` event includes `workflow_run_id`, which is `null` only on a `workflow_run.error` when no run was created.
## Run events
Run events arrive on the session's event stream, which is the primary thread's stream, and listing the session's events returns them too. Run events don't trigger [webhooks](https://platform.claude.com/docs/en/managed-agents/webhooks). Status events from the run's threads arrive on the same stream. Each names its thread in `session_thread_id`, and a run's threads are the ones whose `session.thread_created` event had the run's `workflow_run_id`.
| Event | When it arrives | What to do |
| -------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `workflow_run.created` | The agent started a run. Includes `workflow_run_id` (`wrun_…`), the run's `name` and `description`, and `phases`, the phases the workflow declares, each with an `id`, a `name`, and a `description`. A `description` is `null` when the workflow gives none. `phases` is always present and can be empty. The run's and phases' `name` and `description` are text the model wrote, so they can repeat words from your request. A run's `name` can also be one the server assigned. | Track the run as open. Show its `name`, and progress against `phases`. |
| `workflow_run.status_running` | When the run starts to execute, which can be a while after `created`, and each time it resumes after a pause at the budget. A resume after an interrupt might not send it. A run that starts idle might get `workflow_run.status_idle` first. | Show the run as running. |
| `workflow_run.status_idle` | The run was paused, for example at the session's budget. The event doesn't say why. A pause after an interrupt might not send it. | To continue, see [Budgets and limits](https://platform.claude.com/docs/en/managed-agents/workflow-runs#budgets-and-limits) or [Interrupt a session with runs open](https://platform.claude.com/docs/en/managed-agents/workflow-runs#interrupt-a-session-with-runs-open). |
| `workflow_run.phase_started`, `workflow_run.phase_ended` | The workflow entered or left a phase, or the run's end closed a phase that was still open. The end event doesn't say whether the phase's work finished. Both include `workflow_run_phase_id`. The end also has `phase_started_id`, the `id` of the start event it closes. Neither has the phase's name: look it up by `workflow_run_phase_id` in the `phases` of `workflow_run.created`. | Update progress. Phases run one at a time, in the order of `phases`, each at most once, but the API doesn't guarantee it. Match a phase's end to its start by `phase_started_id`. Handle more than one open phase, a phase that isn't in `phases`, and a listed phase that never starts, even in a run that completes. Every phase that starts also ends, before the run's `workflow_run.status_ended`. |
| `workflow_run.status_ended` | The run ended. Always the last of the run's `workflow_run.*` events. Includes `result`. | Read `result` (next table). The agent then gets a turn to read how the run ended. At the budget, or while the primary thread waits on your client, that turn comes later. After an interrupt, that turn might not come: send a `user.message`, or read `result` yourself. After an archive or termination, it doesn't come. |
| `workflow_run.error` | The server reports an error of a run, or a start that it refused. A run that ends in `error` gets this event, with the same error, before its `workflow_run.status_ended`. Includes `error`: a `type` and a `message` that is safe to log. `workflow_run_id` is `null` when no run was created. | Log it, and don't take it as the run's end. If `workflow_run_id` is `null`, no run started. Otherwise keep tracking the run until its `workflow_run.status_ended`. |
| `result` | Meaning |
| --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `{"type": "completed"}` | The workflow finished running. The result doesn't say whether the work passed. A run can end `completed` even though work on its threads failed, or a thread couldn't be created. To find failed work, read the events of each of the [run's threads](https://platform.claude.com/docs/en/managed-agents/workflow-runs#a-runs-threads). |
| `{"type": "stopped"}` | The agent stopped the run, or the session was archived. The event doesn't say which, and later releases might add other causes. |
| `error` with `timeout_error` | The run reached its lifetime: 24 hours by default, or the one the agent set. |
| `error` with `program_error` | The workflow failed. Its code failed, or it broke a rule for workflows, other than a limit. Or one of the run's threads failed, or couldn't be created, and the workflow let that end the run. |
| `error` with `thread_limit_error` | The run went over its [limit on the agents that a workflow starts](https://platform.claude.com/docs/en/managed-agents/workflow-runs#budgets-and-limits). |
| `error` with `unknown_error` | The server couldn't continue the run, or the run went over one of the server's other limits on workflows. |
An error result looks like `{"type": "error", "error": {"type": "timeout_error", "message": "..."}}`, where `message` is safe to log. Treat an unrecognized `result.type` as a run that ended some other way, and an unrecognized `error.type` as an error. When something the session depends on fails, such as the model, an MCP server, credentials, or billing, the failing thread's stream gets a `session.error`. That doesn't end a run by itself. But if it makes one of the run's threads fail, and the workflow lets that end the run, the run ends with `program_error`.
For example, you ask the [contract-review agent](https://platform.claude.com/docs/en/managed-agents/multiagent-orchestration#turn-on-dynamic-workflows) which of 300 contracts have a change-of-control clause, and the agent starts a run:
1. `workflow_run.created` names the run "Find change-of-control clauses" and lists the phases "Read the contracts" and "Reconcile the findings" in `phases`. Then `workflow_run.status_running` follows.
2. Phase events mark each phase, and each thread the run creates sends `session.thread_created` with the run's `workflow_run_id`.
3. `workflow_run.status_ended` arrives with `result: {"type": "completed"}`.
4. The agent answers, "41 of the 300 contracts have one," and `session.status_idle` arrives with `end_turn`.
The run's first event lists its phases:
```json
{
"type": "workflow_run.created",
"id": "sevt_01abc...",
"workflow_run_id": "wrun_01J8XkN5uT3vHpLqRfWdY2",
"name": "Find change-of-control clauses",
"description": "Reads each contract and lists those that have the clause.",
"phases": [
{
"id": "wrph_01Kd3a1f3",
"name": "Read the contracts",
"description": "Reads each contract for the clause."
},
{ "id": "wrph_01Kd3b7c9", "name": "Reconcile the findings", "description": null }
],
"processed_at": "2026-10-09T14:01:45Z"
}
```
Each phase event names its phase by `workflow_run_phase_id`. That is an `id` in `phases`, but the API doesn't guarantee it:
```json
{
"type": "workflow_run.phase_started",
"id": "sevt_01def...",
"workflow_run_id": "wrun_01J8XkN5uT3vHpLqRfWdY2",
"workflow_run_phase_id": "wrph_01Kd3a1f3",
"processed_at": "2026-10-09T14:01:46Z"
}
```
The run's last event reports how it ended:
```json
{
"type": "workflow_run.status_ended",
"id": "sevt_01ghi...",
"workflow_run_id": "wrun_01J8XkN5uT3vHpLqRfWdY2",
"result": { "type": "completed" },
"processed_at": "2026-10-09T14:09:12Z"
}
```
## A run's threads
Each agent in a run works in its own [session thread](https://platform.claude.com/docs/en/managed-agents/session-threads), which the server creates as the workflow needs it. You can list, read, and stream a run's threads like any child thread, and answer their tool calls from the primary stream. To stop them, ask the agent to stop the run (see [Interrupt a session with runs open](https://platform.claude.com/docs/en/managed-agents/workflow-runs#interrupt-a-session-with-runs-open)). You can't stop one by its ID, or archive one while its run is open.
* **Grouping:** A run's thread carries the run's `workflow_run_id`, as does the `session.thread_created` event that announces it. Other threads, and the `session.thread_created` events that announce them, have `workflow_run_id` set to `null`.
* **Agent:** `agent` shows the agent the thread runs. For an agent you listed in [`multiagent.workflows.predefined_agents`](https://platform.claude.com/docs/en/managed-agents/multiagent-orchestration#turn-on-dynamic-workflows), `agent` has that agent's `id` and `version`, as on the thread of a subagent you listed. For an agent the workflow defines (an inline agent), `agent` has `type` `inline` and no `id` or `version`. It has the system prompt the workflow wrote, not the session agent's. It also has the name and description the workflow gave it; the server assigns a name if the workflow gave none. It uses the model of the session agent, the agent the session runs. Its tools, MCP servers, and skills are a subset of the session agent's. It gets all of them, but the API doesn't guarantee that. Its tools keep their permission policies.
* **What the threads share:** A run's threads work in the session's sandbox, so every thread works with the same files. That includes the files of a memory store the session mounts. An agent the workflow defines uses its MCP servers with the credentials the session resolves for them. Each thread has its own conversation history.
* **Events:** A run thread's `session.thread_created`, `session.thread_status_running`, `session.thread_status_idle`, and `session.thread_status_terminated` events also arrive on the primary stream (see [Run events](https://platform.claude.com/docs/en/managed-agents/workflow-runs#run-events)). Its message events stay on its own stream. Its thread webhooks are sent as for any child thread. For what the thread's own stream records, see [Session thread events](https://platform.claude.com/docs/en/managed-agents/session-threads#session-thread-events).
* **Phases:** No event or field says which phase a thread works in, and threads of one run can have the same `agent_name`. Follow a run's progress by its phase events, and tell its threads apart by `session_thread_id`.
* **Thread limit:** A run's threads are exempt from the session's [child-thread limit](https://platform.claude.com/docs/en/managed-agents/session-threads#primary-thread-and-session-threads).
* **Starting runs:** Only the agent on the session's primary thread starts runs. An agent working in a run's thread can't start a run of its own, so runs don't nest.
* **Archiving:** The server archives each thread no later than the end of its run. It can archive one sooner, once the thread returns its result or the run finishes with it. If the thread is still running or waiting on your client at that point, the server stops it first. An archived thread stays in the thread list, with status `terminated`. You don't need to archive a run's threads yourself. While the run is open, a request to archive one that the server hasn't archived yet returns 400 with `error.details.error_code: "workflow_run_open"`.
* **Visibility:** You don't see the workflow's code, but you can ask the agent for the workflow, as the tip after this list describes. You also don't see the tool calls the agent makes to start and manage runs, or the result each thread returns to the workflow.
<Tip>
You can ask the agent for the workflow that it wrote for your request. Wait until the run has ended and the session is `idle`. Then send a `user.message` that asks the agent to print the workflow that it started the run with, word for word, and not to start another run.
```text wrap
Print the workflow that you started the run with, word for word, in one code block. Do not start another run.
```
</Tip>
## Know when the work is done
While a run is running, expect the session to stay `running`, even while none of its threads is working. It goes `idle` with `requires_action` when no thread is working and a thread waits on your client. An idle by itself doesn't mean that the work is done. The work is done when both are true:
1. Every run you've seen created has its `workflow_run.status_ended`.
2. After that, a `session.status_idle` arrives with `stop_reason` `end_turn`, and your own request, such as an interrupt, didn't cause it. After you interrupt, count only an idle that comes after your next `user.message` or `user.define_outcome`.
* **Paused runs:** A paused run doesn't keep the session `running`, so the session can go idle while the run is still open. At the budget, for example, the session goes idle with `budget_reached`. The work isn't done until the run ends.
* **Another run:** The agent can start a new run when it reads a result, so check again.
* **Outcomes:** If you [defined an outcome](https://platform.claude.com/docs/en/managed-agents/define-outcomes), no evaluation starts while a run is open, whether it's running or idle. The turn in which the agent reads the run's result can start one.
* **`retries_exhausted`:** The agent's turn failed on an error: retries ran out, or the error can't be retried, such as a billing failure. A run might still be running when this idle comes. If a run ended and the agent hasn't read its result yet, the server starts a new turn with no input from you. The session goes `running` again, so wait for the next idle. If the session stays idle, read the `session.error` that came before it and fix the cause. Then send a `user.message`, or read each run's `result` yourself.
## Follow a run
This sample follows a session from your message to the agent's answer. It opens the stream and sends the message. Then it does the following:
* **Tracks each run** from its `workflow_run.created` to its `workflow_run.status_ended`, and prints each phase as it starts.
* **Answers custom tool calls** when each `agent.custom_tool_use` arrives, because a run's thread can wait on your client while the session stays `running`. If your agent's tools [ask for confirmation](https://platform.claude.com/docs/en/managed-agents/events-and-streaming#tool-confirmation), add a branch that answers each `agent.tool_use` or `agent.mcp_tool_use` whose `evaluated_permission` is `ask`. The sample has none, because a branch that allows every call would turn `always_ask` into always allow.
* **Stops** when the [work is done](https://platform.claude.com/docs/en/managed-agents/workflow-runs#know-when-the-work-is-done): no run is open, and the session goes idle with `end_turn`. It also stops if the session terminates. On an idle with any other stop reason except `requires_action`, such as `budget_reached`, `retries_exhausted`, or `refusal`, it prints the reason and stops, so handle those in your own code. It stops on `retries_exhausted` even when the server is about to start a new turn by itself. It keeps waiting on `requires_action`, and on `end_turn` while a run is open.
<CodeGroup>
```bash cURL
# This workflow does not translate well to a one-off shell command.
# Use one of the SDK examples in this code group instead.
```
```bash CLI
# This workflow does not translate well to a one-off shell command.
# Use one of the SDK examples in this code group instead.
```
```python Python
open_runs: dict[str, str] = {} # workflow_run_id -> run name
phase_names: dict[tuple[str, str], str] = {} # (run ID, phase ID) -> phase name
# Open the stream first, then send the user message
with client.beta.sessions.events.stream(session_id) as stream:
client.beta.sessions.events.send(
session_id,
events=[
{
"type": "user.message",
"content": [
{
"type": "text",
"text": "Which contracts in /contracts have a change-of-control clause?",
},
],
},
],
)
for event in stream:
match event.type:
case "workflow_run.created":
open_runs[event.workflow_run_id] = event.name
for phase in event.phases:
phase_names[event.workflow_run_id, phase.id] = phase.name
print(f"Run started: {event.name}")
case "workflow_run.phase_started":
phase_id = event.workflow_run_phase_id
key = (event.workflow_run_id, phase_id)
print(f" Phase: {phase_names.get(key, phase_id)}")
case "workflow_run.status_ended":
name = open_runs.pop(event.workflow_run_id, event.workflow_run_id)
print(f"Run ended: {name} ({event.result.type})")
case "agent.custom_tool_use":
# Answer when the event arrives. A run's thread can wait on your
# client while the session stays running.
result = call_tool(event.name, event.input)
try:
client.beta.sessions.events.send(
session_id,
events=[
{
"type": "user.custom_tool_result",
"custom_tool_use_id": event.id,
"content": [{"type": "text", "text": result}],
},
],
)
except anthropic.BadRequestError as error:
# The server refuses a result that comes too late, after it
# archived the call's thread. Keep following the run.
print(f" Answer to {event.name} refused: {error.message}")
case "session.status_idle":
# Done when every run has ended and the agent has finished its turn
if not open_runs and event.stop_reason.type == "end_turn":
break
# An idle with requires_action waits on your client, so keep reading.
# On any other stop reason, print it and stop.
if event.stop_reason.type not in ("end_turn", "requires_action"):
print(f"Session idle: {event.stop_reason.type}")
break
case "session.status_terminated":
break
```
```typescript TypeScript
const openRuns = new Map<string, string>(); // workflow_run_id -> run name
const phaseNames = new Map<string, string>(); // "run ID:phase ID" -> phase name
// Open the stream first, then send the user message
const stream = await client.beta.sessions.events.stream(sessionId);
await client.beta.sessions.events.send(sessionId, {
events: [
{
type: "user.message",
content: [{ type: "text", text: "Which contracts in /contracts have a change-of-control clause?" }],
},
],
});
events: for await (const event of stream) {
switch (event.type) {
case "workflow_run.created":
openRuns.set(event.workflow_run_id, event.name);
for (const phase of event.phases) {
phaseNames.set(`${event.workflow_run_id}:${phase.id}`, phase.name);
}
console.log(`Run started: ${event.name}`);
break;
case "workflow_run.phase_started": {
const phaseId = event.workflow_run_phase_id;
const phaseName = phaseNames.get(`${event.workflow_run_id}:${phaseId}`);
console.log(` Phase: ${phaseName ?? phaseId}`);
break;
}
case "workflow_run.status_ended": {
const name = openRuns.get(event.workflow_run_id) ?? event.workflow_run_id;
openRuns.delete(event.workflow_run_id);
console.log(`Run ended: ${name} (${event.result.type})`);
break;
}
case "agent.custom_tool_use": {
// Answer when the event arrives. A run's thread can wait on your
// client while the session stays running.
const result = await callTool(event.name, event.input);
try {
await client.beta.sessions.events.send(sessionId, {
events: [
{
type: "user.custom_tool_result",
custom_tool_use_id: event.id,
content: [{ type: "text", text: result }],
},
],
});
} catch (error) {
// The server refuses a result that comes too late, after it
Cut at 300 lines. The page has the rest.
api/beta/organization Changed · +2 / -2 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.
from line 8672
86728672
86738673 Name of the Workspace.
86748674
8675 minLength: 1, maxLength: 40
8675 minLength: 1, maxLength: 255
86768676
86778677- `data_residency: optional BetaDataResidencyCreateConfig or null`
86788678
from line 9080
90809080
90819081 Name of the Workspace.
90829082
9083 minLength: 1, maxLength: 40
9083 minLength: 1, maxLength: 255
90849084
90859085- `tags: optional map[string] or null`
90869086
from line 10574
1057410574
1057510575 - `"token-efficient-tools-2025-02-19"`
1057610576
10577 - `"output-128k-2025-
10577 - `"output-128k-202
api/beta/organization/workspaces Changed · +2 / -2 lines
from line 322
322322
323323 Name of the Workspace.
324324
325 minLength: 1, maxLength: 40
325 minLength: 1, maxLength: 255
326326
327327- `data_residency: optional BetaDataResidencyCreateConfig or null`
328328
from line 730
730730
731731 Name of the Workspace.
732732
733 minLength: 1, maxLength: 40
733 minLength: 1, maxLength: 255
734734
735735- `tags: optional map[string] or null`
736736
api/beta/organization/workspaces/create Changed · +1 / -1 lines
from line 129
129129
130130 Name of the Workspace.
131131
132 minLength: 1, maxLength: 40
132 minLength: 1, maxLength: 255
133133
134134- `data_residency: optional BetaDataResidencyCreateConfig or null`
135135
api/beta/organization/workspaces/update Changed · +1 / -1 lines
from line 71
7171
7272 Name of the Workspace.
7373
74 minLength: 1, maxLength: 40
74 minLength: 1, maxLength: 255
7575
7676- `tags: optional map[string] or null`
7777
api/beta/sessions/events/send Changed · +2 / -2 lines
from line 335
335335
336336 - `custom_tool_use_id: string`
337337
338 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.
338 The id of the `agent.custom_tool_use` event this result corresponds to. It is also listed 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.
339339
340340 minLength: 1, maxLength: 128
341341
from line 739
739739
740740 - `custom_tool_use_id: string`
741741
742 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.
742 The id of the `agent.custom_tool_use` event this result corresponds to. It is also listed 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.
743743
744744 - `content: optional array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsSearchResultBlock`
745745
api/messages/batches/results Changed · +0 / -4 lines
from line 948
948948
949949 - `"claude-haiku-4-5"`
950950
951 Fastest model with near-frontier intelligence
952
953951 - `"claude-haiku-4-5-20251001"`
954
955 Fastest model with near-frontier intelligence
956952
957953 - `"claude-opus-4-5"`
958954
api/organization Changed · +2 / -2 lines
from line 6340
63406340
63416341 Name of the Workspace.
63426342
6343 minLength: 1, maxLength: 40
6343 minLength: 1, maxLength: 255
63446344
63456345- `data_residency: optional DataResidencyCreateConfig or null`
63466346
from line 6748
67486748
67496749 Name of the Workspace.
67506750
6751 minLength: 1, maxLength: 40
6751 minLength: 1, maxLength: 255
67526752
67536753- `tags: optional map[string] or null`
67546754