Body parameters
agent: string or BetaManagedAgentsAgentParams or BetaManagedAgentsAgentWithOverridesParamsAgent identifier. Accepts the
agentID string, which pins the latest version for the session, or anagentobject with both id and version specified.stringBetaManagedAgentsAgentParams objectSpecification for an Agent. Provide a specific
versionor use the short-formagent="agent_id"for the most recent versiontype: "agent"id: stringThe
agentID.minLength: 1, maxLength: 128
version: optional numberThe specific
agentversion to use. Omit to use the latest version. Must be at least 1 if specified.format: int32
BetaManagedAgentsAgentWithOverridesParams objectReference to an
agentplus optional configuration overrides. Each provided field replaces the agent's value for the caller's use; the agent resource is unchanged.type: "agent_with_overrides"id: stringThe
agentID.minLength: 1, maxLength: 128
mcp_servers: optional array of BetaManagedAgentsURLMCPServerParamsReplacement MCP server list. Full replacement: the provided array becomes the MCP servers. Send an empty array to clear; omit to preserve the agent's servers.
type: "url"name: stringUnique name for this server, referenced by mcp_toolset configurations. 1-255 characters.
minLength: 1, maxLength: 255
url: stringEndpoint URL for the MCP server.
maxLength: 2048
model: optional BetaManagedAgentsModel or BetaManagedAgentsModelConfigParamsReplacement model. Accepts the model string, e.g.
claude-opus-5, or amodel_configobject. Omit to use the agent's model.BetaManagedAgentsModel = "claude-fable-5-1" or "claude-sonnet-5" or "claude-fable-5" or 11 more or stringThe model that will power your agent.
See models for additional details and options.
"claude-fable-5-1" or "claude-sonnet-5" or "claude-fable-5" or 11 moreThe model that will power your agent.
See models for additional details and options.
"claude-fable-5-1"Frontier intelligence for ambitious tasks across coding, scientific discovery, and enterprise workflows
"claude-sonnet-5"High-performance model for coding and agents
"claude-fable-5"Next generation of intelligence for the hardest knowledge work and coding problems
"claude-opus-5"Powerful intelligence for long-running agents and coding
"claude-opus-4-8"Powerful intelligence for long-running agents and coding
"claude-opus-4-7"Powerful intelligence for long-running agents and coding
"claude-opus-4-6"Powerful intelligence for long-running agents and coding
"claude-sonnet-4-6"Best combination of speed and intelligence
"claude-haiku-4-5"Fastest model with near-frontier intelligence
"claude-haiku-4-5-20251001"Fastest model with near-frontier intelligence
"claude-opus-4-5"Powerful intelligence for long-running agents and coding
"claude-opus-4-5-20251101"Powerful intelligence for long-running agents and coding
"claude-sonnet-4-5"High-performance model for agents and coding
"claude-sonnet-4-5-20250929"High-performance model for agents and coding
string
BetaManagedAgentsModelConfigParams objectAn object that defines additional configuration control over model use
id: BetaManagedAgentsModelThe model that will power your agent.
See models for additional details and options.
effort: optional "low" or "medium" or "high" or 2 more or BetaManagedAgentsEffortLow or BetaManagedAgentsEffortMedium or 3 more or nullHow hard Claude works on each inference call. Accepts a bare level string (
"high") or\{"type": "high"\}. On create, omitting it resolves the per-model default; on update, omitting it leaves the stored value unchanged.BetaManagedAgentsEffortLevel = "low" or "medium" or "high" or 2 moreHow hard Claude works on each turn. Higher levels favor reasoning depth over latency. Not all models accept every level; invalid combinations are rejected at create time.
"low""medium""high""xhigh""max"
BetaManagedAgentsEffortLow objectLow effort. Favors latency over reasoning depth.
type: "low"
BetaManagedAgentsEffortMedium objectMedium effort. Balances latency and reasoning depth.
type: "medium"
BetaManagedAgentsEffortHigh objectHigh effort. Favors reasoning depth.
type: "high"
BetaManagedAgentsEffortXhigh objectExtra-high effort. Not all models accept this level.
type: "xhigh"
BetaManagedAgentsEffortMax objectMaximum effort. Favors reasoning depth over latency.
type: "max"
inference_geo: optional string or nullGeographic region for model inference. When unset, requests fall through to the workspace's default_inference_geo. On update,
modelis whole-object replacement — omitting inference_geo clears it.speed: optional "standard" or "fast" or nullInference speed mode.
fastprovides significantly faster output token generation at premium pricing. Not all models supportfast; invalid combinations are rejected at create time."standard""fast"
skills: optional array of BetaManagedAgentsSkillParamsReplacement skill list. Full replacement: the provided array becomes the skills. Send an empty array to clear; omit to preserve the agent's skills.
BetaManagedAgentsAnthropicSkillParams objectAn Anthropic-managed skill.
type: "anthropic"skill_id: stringIdentifier of the Anthropic skill (e.g., "xlsx").
minLength: 1, maxLength: 64
version: optional string or nullVersion to pin. Defaults to latest if omitted.
minLength: 1, maxLength: 64
BetaManagedAgentsCustomSkillParams objectA user-created custom skill.
type: "custom"skill_id: stringTagged ID of the custom skill (e.g., "skill_01XJ5...").
minLength: 1, maxLength: 64
version: optional string or nullVersion to pin. Defaults to latest if omitted.
minLength: 1, maxLength: 64
system: optional string or nullReplacement system prompt. Up to 100,000 characters. Set to null to clear the agent's system prompt; omit to preserve it.
maxLength: 100000
tools: optional array of BetaManagedAgentsAgentToolset20260401Params or BetaManagedAgentsMCPToolsetParams or BetaManagedAgentsCustomToolParamsReplacement tool list. Full replacement: the provided array becomes the tool configuration. Send an empty array to clear; omit to preserve the agent's tools.
BetaManagedAgentsAgentToolset20260401Params objectConfiguration for built-in agent tools. Use this to enable or disable groups of tools available to the agent.
type: "agent_toolset_20260401"configs: optional array of BetaManagedAgentsAgentToolConfigParamsPer-tool configuration overrides.
BetaManagedAgentsBashToolConfigParams objectConfiguration override for the bash tool.
type: optional "bash"name: "bash"Must be "bash".
enabled: optional boolean or nullWhether this tool is enabled and available to Claude. Overrides the default_config setting.
permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or nullPermission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy objectTool calls are automatically approved without user confirmation.
type: "always_allow"
BetaManagedAgentsAlwaysAskPolicy objectTool calls require user confirmation before execution.
type: "always_ask"
BetaManagedAgentsAutoPolicy objectThe server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
type: "auto"
BetaManagedAgentsEditToolConfigParams objectConfiguration override for the edit tool.
type: optional "edit"name: "edit"Must be "edit".
enabled: optional boolean or nullWhether this tool is enabled and available to Claude. Overrides the default_config setting.
permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or nullPermission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy objectTool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy objectTool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy objectThe server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
BetaManagedAgentsReadToolConfigParams objectConfiguration override for the read tool.
type: optional "read"name: "read"Must be "read".
enabled: optional boolean or nullWhether this tool is enabled and available to Claude. Overrides the default_config setting.
permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or nullPermission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy objectTool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy objectTool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy objectThe server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
BetaManagedAgentsWriteToolConfigParams objectConfiguration override for the write tool.
type: optional "write"name: "write"Must be "write".
enabled: optional boolean or nullWhether this tool is enabled and available to Claude. Overrides the default_config setting.
permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or nullPermission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy objectTool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy objectTool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy objectThe server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
BetaManagedAgentsGlobToolConfigParams objectConfiguration override for the glob tool.
type: optional "glob"name: "glob"Must be "glob".
enabled: optional boolean or nullWhether this tool is enabled and available to Claude. Overrides the default_config setting.
permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or nullPermission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy objectTool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy objectTool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy objectThe server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
BetaManagedAgentsGrepToolConfigParams objectConfiguration override for the grep tool.
type: optional "grep"name: "grep"Must be "grep".
enabled: optional boolean or nullWhether this tool is enabled and available to Claude. Overrides the default_config setting.
permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or nullPermission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy objectTool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy objectTool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy objectThe server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
BetaManagedAgentsWebFetchToolConfigParams objectConfiguration override for the web_fetch tool.
type: optional "web_fetch"name: "web_fetch"Must be "web_fetch".
allowed_domains: optional array of stringOnly fetch URLs whose host is one of these domains or a subdomain of one. Each entry is a plain hostname like "docs.example.com" (no scheme, port, or path). At most 64 entries; an empty list is rejected (omit the field instead). Cannot be combined with blocked_domains.
blocked_domains: optional array of stringNever fetch URLs whose host is one of these domains or a subdomain of one. Each entry is a plain hostname like "ads.example.com" (no scheme, port, or path). At most 64 entries; an empty list is rejected (omit the field instead). Cannot be combined with allowed_domains.
enabled: optional boolean or nullWhether this tool is enabled and available to Claude. Overrides the default_config setting.
max_content_tokens: optional number or nullMaximum number of tokens of fetched text content to include in context per call. Does not apply to binary content such as PDFs.
format: int32
permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or nullPermission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy objectTool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy objectTool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy objectThe server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
BetaManagedAgentsWebSearchToolConfigParams objectConfiguration override for the web_search tool.
type: optional "web_search"name: "web_search"Must be "web_search".
allowed_domains: optional array of stringOnly return search results whose host is one of these domains or a subdomain of one. Each entry is a plain hostname like "docs.example.com" (no scheme or port; an optional path suffix is accepted). At most 64 entries; an empty list is rejected (omit the field instead). Cannot be combined with blocked_domains.
blocked_domains: optional array of stringNever return search results whose host is one of these domains or a subdomain of one. Each entry is a plain hostname like "ads.example.com" (no scheme or port; an optional path suffix is accepted). At most 64 entries; an empty list is rejected (omit the field instead). Cannot be combined with allowed_domains.
enabled: optional boolean or nullWhether this tool is enabled and available to Claude. Overrides the default_config setting.
permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or nullPermission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy objectTool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy objectTool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy objectThe server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
user_location: optional BetaManagedAgentsUserLocation or nullApproximate user location for search result localization.
type: "approximate"Location precision. Only "approximate" is supported.
city: optional string or nullCity name.
minLength: 1, maxLength: 255
country: optional string or nullTwo-letter ISO 3166-1 country code, uppercase.
region: optional string or nullRegion or state name.
minLength: 1, maxLength: 255
timezone: optional string or nullIANA timezone identifier, e.g. "America/Los_Angeles".
minLength: 1, maxLength: 255
default_config: optional BetaManagedAgentsAgentToolsetDefaultConfigParams or nullDefault configuration for all tools in a toolset.
enabled: optional boolean or nullWhether tools are enabled and available to Claude by default. Defaults to true if not specified.
permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or nullPermission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy objectTool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy objectTool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy objectThe server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
BetaManagedAgentsMCPToolsetParams objectConfiguration for tools from an MCP server defined in
mcp_servers.type: "mcp_toolset"mcp_server_name: stringName of the MCP server. Must match a server name from the mcp_servers array. 1-255 characters.
minLength: 1, maxLength: 255
configs: optional array of BetaManagedAgentsMCPToolConfigParamsPer-tool configuration overrides.
name: stringName of the MCP tool to configure. 1-128 characters.
minLength: 1, maxLength: 128
enabled: optional boolean or nullWhether this tool is enabled. Overrides the
default_configsetting.permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or nullPermission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy objectTool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy objectTool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy objectThe server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
default_config: optional BetaManagedAgentsMCPToolsetDefaultConfigParams or nullDefault configuration for all tools from an MCP server.
enabled: optional boolean or nullWhether tools are enabled by default. Defaults to true if not specified.
permission_policy: optional BetaManagedAgentsAlwaysAllowPolicy or BetaManagedAgentsAlwaysAskPolicy or BetaManagedAgentsAutoPolicy or nullPermission policy for tool execution.
BetaManagedAgentsAlwaysAllowPolicy objectTool calls are automatically approved without user confirmation.
BetaManagedAgentsAlwaysAskPolicy objectTool calls require user confirmation before execution.
BetaManagedAgentsAutoPolicy objectThe server decides each tool call individually: it judges, from the tool, its input, and the session content so far, whether the call is safe to execute or high-risk, and evaluates it to allow when judged safe and to deny when judged high-risk. A call the server cannot reach a judgement on evaluates to ask.
BetaManagedAgentsCustomToolParams objectA custom tool that is executed by the API client rather than the agent. When the agent calls this tool, an
agent.custom_tool_useevent is emitted and the session goes idle, waiting for the client to provide the result via auser.custom_tool_resultevent.type: "custom"description: stringDescription of what the tool does, shown to the agent to help it decide when to use the tool.
minLength: 1
input_schema: BetaManagedAgentsCustomToolInputSchemaJSON Schema for custom tool input parameters.
type: "object"properties: optional map[unknown] or nullrequired: optional array of string or null
name: stringUnique name for the tool. 1-128 characters; letters, digits, underscores, and hyphens.
minLength: 1, maxLength: 128
version: optional numberThe specific
agentversion to use. Omit to use the latest version.format: int32
environment_id: stringID of the
environmentdefining the container configuration for this session.minLength: 1, maxLength: 128
budget: optional BetaManagedAgentsBudgetLimitA hard spend ceiling. The session stops issuing new model requests once the tracked list cost reaches
max_list_cost.type: "limit"max_list_cost: BetaMonetaryAmountA monetary amount in a specific currency.
amount: stringAmount in minor units of the currency, as an integer decimal string with no leading zeros: "2500" is $25.00 and "50" is fifty cents. A string rather than a number so no float rounding is ever applied.
currency: BetaCurrencyUppercase ISO-4217 currency code.
USDis the only currency currently supported; the accepted set is closed and grows only when a new currency is priced.
initial_events: optional array of BetaManagedAgentsUserMessageEventParams or BetaManagedAgentsUserDefineOutcomeEventParamsInitial events to send to the
sessionat creation, processed in order. Supportsuser.messageanduser.define_outcomeevents. Maximum 50 events.BetaManagedAgentsUserMessageEventParams objectParameters for sending a user message to the session.
type: "user.message"content: array of BetaManagedAgentsTextBlock or BetaManagedAgentsImageBlock or BetaManagedAgentsDocumentBlock or BetaManagedAgentsRedactedBlockArray of content blocks for the user message.
BetaManagedAgentsTextBlock objectRegular text content.
type: "text"text: stringThe text content.
minLength: 1
BetaManagedAgentsImageBlock objectImage content specified directly as base64 data or as a reference via a URL.
type: "image"source: BetaManagedAgentsBase64ImageSource or BetaManagedAgentsURLImageSource or BetaManagedAgentsFileImageSourceUnion type for image source variants.
BetaManagedAgentsBase64ImageSource objectBase64-encoded image data.
type: "base64"data: stringBase64-encoded image data.
minLength: 1
media_type: stringMIME type of the image (e.g., "image/png", "image/jpeg", "image/gif", "image/webp").
minLength: 1
BetaManagedAgentsURLImageSource objectImage referenced by URL.
type: "url"url: stringURL of the image to fetch.
minLength: 1
BetaManagedAgentsFileImageSource objectImage referenced by file ID.
type: "file"file_id: stringID of a previously uploaded file.
minLength: 1
BetaManagedAgentsDocumentBlock objectDocument content, either specified directly as base64 data, as text, or as a reference via a URL.
type: "document"source: BetaManagedAgentsBase64DocumentSource or BetaManagedAgentsPlainTextDocumentSource or BetaManagedAgentsURLDocumentSource or BetaManagedAgentsFileDocumentSourceUnion type for document source variants.
BetaManagedAgentsBase64DocumentSource objectBase64-encoded document data.
type: "base64"data: stringBase64-encoded document data.
minLength: 1
media_type: stringMIME type of the document (e.g., "application/pdf").
minLength: 1
BetaManagedAgentsPlainTextDocumentSource objectPlain text document content.
type: "text"data: stringThe plain text content.
minLength: 1
media_type: "text/plain"MIME type of the text content. Must be "text/plain".
BetaManagedAgentsURLDocumentSource objectDocument referenced by URL.
type: "url"url: stringURL of the document to fetch.
minLength: 1
BetaManagedAgentsFileDocumentSource objectDocument referenced by file ID.
type: "file"file_id: stringID of a previously uploaded file.
minLength: 1
context: optional string or nullAdditional context about the document for the model.
title: optional string or nullThe title of the document.
BetaManagedAgentsRedactedBlock objectPlaceholder for content withheld by Anthropic model policy.
type: "redacted"
BetaManagedAgentsUserDefineOutcomeEventParams objectParameters for defining an outcome the agent should work toward. The agent begins work on receipt.
type: "user.define_outcome"description: stringWhat the agent should produce. This is the task specification.
rubric: BetaManagedAgentsFileRubricParams or BetaManagedAgentsTextRubricParamsRubric for grading the quality of an outcome.
BetaManagedAgentsFileRubricParams objectRubric referenced by a file uploaded via the Files API.
type: "file"file_id: stringID of the rubric file.
BetaManagedAgentsTextRubricParams objectRubric content provided inline as text.
type: "text"content: stringRubric content. Plain text or markdown — the grader treats it as freeform text. Maximum 262144 characters.
maxLength: 262144
max_iterations: optional number or nullEval→revision cycles before giving up. Default 3, max 20.
format: int32
metadata: optional map[string]Arbitrary key-value metadata attached to the session. Maximum 16 pairs, keys up to 64 chars, values up to 512 chars.
resources: optional array of BetaManagedAgentsGitHubRepositoryResourceParams or BetaManagedAgentsFileResourceParams or BetaManagedAgentsMemoryStoreResourceParamResources (e.g. repositories, files) to mount into the session's container.
BetaManagedAgentsGitHubRepositoryResourceParams objectMount a GitHub repository into the session's container.
type: "github_repository"url: stringGithub URL of the repository
minLength: 1, maxLength: 2048
authorization_token: optional stringGitHub authorization token used to clone the repository. Required for private repositories; optional for public ones.
minLength: 1, maxLength: 4096
checkout: optional BetaManagedAgentsBranchCheckout or BetaManagedAgentsCommitCheckout or nullBranch or commit to check out. Defaults to the repository's default branch.
BetaManagedAgentsBranchCheckout objecttype: "branch"name: stringBranch name to check out.
minLength: 1, maxLength: 255
BetaManagedAgentsCommitCheckout objecttype: "commit"sha: stringFull commit SHA to check out.
minLength: 7, maxLength: 64
mount_path: optional string or null