Agents

Create Agent

beta.agents.create(**kwargs) -> BetaManagedAgentsAgent

POST/v1/agents

List Agents

beta.agents.list(**kwargs) -> PageCursor<BetaManagedAgentsAgent>

GET/v1/agents

Get Agent

beta.agents.retrieve(agent_id, **kwargs) -> BetaManagedAgentsAgent

GET/v1/agents/{agent_id}

Update Agent

beta.agents.update(agent_id, **kwargs) -> BetaManagedAgentsAgent

POST/v1/agents/{agent_id}

Archive Agent

beta.agents.archive(agent_id, **kwargs) -> BetaManagedAgentsAgent

POST/v1/agents/{agent_id}/archive

Models

class BetaManagedAgentsAdvisor { model, type }

Platform advisor roster entry: a model the session's primary thread may consult mid-turn.

model: String

The advisor model id.

type: :advisor

class BetaManagedAgentsAgent { id, archived_at, created_at, 12 more }

A Managed Agents agent.

class BetaManagedAgentsAgentReference { id, type, version }

A resolved agent reference with a concrete version.

id: String

type: :agent

version: Integer

formatint32

BetaManagedAgentsAgentToolConfig = BetaManagedAgentsBashToolConfig { enabled, name, permission_policy, type } | BetaManagedAgentsEditToolConfig { enabled, name, permission_policy, type } | BetaManagedAgentsReadToolConfig { enabled, name, permission_policy, type } | 5 more

Configuration for a specific agent tool.

One of the following:

BetaManagedAgentsAgentToolConfigParams = BetaManagedAgentsBashToolConfigParams { name, enabled, permission_policy, type } | BetaManagedAgentsEditToolConfigParams { name, enabled, permission_policy, type } | BetaManagedAgentsReadToolConfigParams { name, enabled, permission_policy, type } | 5 more

Configuration override for a specific tool within a toolset.

One of the following:

class BetaManagedAgentsAgentToolsetDefaultConfig { enabled, permission_policy }

Resolved default configuration for agent tools.

enabled: bool

permission_policy: BetaManagedAgentsAlwaysAllowPolicy { type } | BetaManagedAgentsAlwaysAskPolicy { type }

Permission policy for tool execution.

One of the following:

class BetaManagedAgentsAlwaysAllowPolicy { type }

Tool calls are automatically approved without user confirmation.

type: :always_allow

class BetaManagedAgentsAlwaysAskPolicy { type }

Tool calls require user confirmation before execution.

type: :always_ask

class BetaManagedAgentsAgentToolsetDefaultConfigParams { enabled, permission_policy }

Default configuration for all tools in a toolset.

enabled: bool

Whether tools are enabled and available to Claude by default. Defaults to true if not specified.

permission_policy: BetaManagedAgentsAlwaysAllowPolicy { type } | BetaManagedAgentsAlwaysAskPolicy { type }

Permission policy for tool execution.

One of the following:

class BetaManagedAgentsAlwaysAllowPolicy { type }

Tool calls are automatically approved without user confirmation.

type: :always_allow

class BetaManagedAgentsAlwaysAskPolicy { type }

Tool calls require user confirmation before execution.

type: :always_ask

class BetaManagedAgentsAgentToolset20260401 { configs, default_config, type }

class BetaManagedAgentsAgentToolset20260401BashInput { command, restart, timeout_ms }

Input payload for the bash tool of the agent_toolset_20260401 toolset. All fields are optional; a normal invocation supplies command, while restart=true (with no command) reboots the runner-side bash session.

command: String

Shell command to execute. Omit only when restart is true.

restart: bool

When true, restart the persistent bash session instead of running a command. Subsequent calls without restart will run against the fresh session.

timeout_ms: Integer

Per-call timeout in milliseconds. Defaults to the runner-wide tool timeout when omitted or zero.

minimum0

class BetaManagedAgentsAgentToolset20260401EditInput { file_path, new_string, old_string, replace_all }

Input payload for the edit tool. Performs a string replacement in the named file; by default old_string must occur exactly once.

file_path: String

Path of the file to edit.

new_string: String

Replacement text.

old_string: String

Substring to find and replace.

replace_all: bool

When true, replace every occurrence of old_string instead of requiring a unique match.

class BetaManagedAgentsAgentToolset20260401GlobInput { pattern, path }

Input payload for the glob tool. Returns paths matching a doublestar glob pattern, newest first.

pattern: String

Doublestar glob pattern (e.g. **/*.go). Absolute patterns are only permitted when the runner is configured to allow them.

path: String

Optional directory root to search under. Defaults to the runner's working directory.

class BetaManagedAgentsAgentToolset20260401GrepInput { pattern, path }

Input payload for the grep tool. Searches file contents for a regular expression, returning matching lines.

pattern: String

Regular expression to search for.

path: String

Optional directory root to search under. Defaults to the runner's working directory.

class BetaManagedAgentsAgentToolset20260401Params { type, configs, default_config }

Configuration for built-in agent tools. Use this to enable or disable groups of tools available to the agent.

class BetaManagedAgentsAgentToolset20260401ReadInput { file_path, view_range }

Input payload for the read tool. Reads file contents relative to the runner's working directory (or absolute when the runner permits).

file_path: String

Path of the file to read.

view_range: Array[Integer]

Optional [start_line, end_line] 1-indexed inclusive range. When omitted the entire file is returned. end_line of 0 or negative means "to end of file".

minItems2

maxItems2

class BetaManagedAgentsAgentToolset20260401WriteInput { content, file_path }

Input payload for the write tool. Writes (overwriting) the entire file contents.

content: String

Full file contents to write.

file_path: String

Path of the file to write.

class BetaManagedAgentsAlwaysAllowPolicy { type }

Tool calls are automatically approved without user confirmation.

type: :always_allow

class BetaManagedAgentsAlwaysAskPolicy { type }

Tool calls require user confirmation before execution.

type: :always_ask

class BetaManagedAgentsAnthropicSkill { skill_id, type, version }

A resolved Anthropic-managed skill.

skill_id: String

type: :anthropic

version: String

class BetaManagedAgentsAnthropicSkillParams { skill_id, type, version }

An Anthropic-managed skill.

skill_id: String

Identifier of the Anthropic skill (e.g., "xlsx").

minLength1

maxLength64

type: :anthropic

version: String

Version to pin. Defaults to latest if omitted.

minLength1

maxLength64

class BetaManagedAgentsBashToolConfig { enabled, name, permission_policy, type }

Configuration for the bash tool.

class BetaManagedAgentsBashToolConfigParams { name, enabled, permission_policy, type }

Configuration override for the bash tool.

class BetaManagedAgentsCustomSkill { skill_id, type, version }

A resolved user-created custom skill.

skill_id: String

type: :custom

version: String

class BetaManagedAgentsCustomSkillParams { skill_id, type, version }

A user-created custom skill.

skill_id: String

Tagged ID of the custom skill (e.g., "skill_01XJ5...").

minLength1

maxLength64

type: :custom

version: String

Version to pin. Defaults to latest if omitted.

minLength1

maxLength64

class BetaManagedAgentsCustomTool { description, input_schema, name, type }

A custom tool as returned in API responses.

description: String

input_schema: BetaManagedAgentsCustomToolInputSchema { type, properties, required }

JSON Schema for custom tool input parameters.

type: :object

properties: Hash[Symbol, untyped]

required: Array[String]

type: :custom

class BetaManagedAgentsCustomToolInputSchema { type, properties, required }

JSON Schema for custom tool input parameters.

type: :object

properties: Hash[Symbol, untyped]

required: Array[String]

class BetaManagedAgentsCustomToolParams { description, input_schema, name, type }

A custom tool that is executed by the API client rather than the agent. When the agent calls this tool, an agent.custom_tool_use event is emitted and the session goes idle, waiting for the client to provide the result via a user.custom_tool_result event.

description: String

Description of what the tool does, shown to the agent to help it decide when to use the tool.

minLength1

input_schema: BetaManagedAgentsCustomToolInputSchema { type, properties, required }

JSON Schema for custom tool input parameters.

type: :object

properties: Hash[Symbol, untyped]

required: Array[String]

Unique name for the tool. 1-128 characters; letters, digits, underscores, and hyphens.

minLength1

maxLength128

type: :custom

class BetaManagedAgentsEditToolConfig { enabled, name, permission_policy, type }

Configuration for the edit tool.

class BetaManagedAgentsEditToolConfigParams { name, enabled, permission_policy, type }

Configuration override for the edit tool.

class BetaManagedAgentsEffortHigh { type }

High effort. Favors reasoning depth.

type: :high

class BetaManagedAgentsEffortLow { type }

Low effort. Favors latency over reasoning depth.

type: :low

class BetaManagedAgentsEffortMax { type }

Maximum effort. Favors reasoning depth over latency.

type: :max

class BetaManagedAgentsEffortMedium { type }

Medium effort. Balances latency and reasoning depth.

type: :medium

class BetaManagedAgentsEffortXhigh { type }

Extra-high effort. Not all models accept this level.

type: :xhigh

class BetaManagedAgentsGlobToolConfig { enabled, name, permission_policy, type }

Configuration for the glob tool.

class BetaManagedAgentsGlobToolConfigParams { name, enabled, permission_policy, type }

Configuration override for the glob tool.

class BetaManagedAgentsGrepToolConfig { enabled, name, permission_policy, type }

Configuration for the grep tool.

class BetaManagedAgentsGrepToolConfigParams { name, enabled, permission_policy, type }

Configuration override for the grep tool.

class BetaManagedAgentsMCPServerURLDefinition { name, type, url }

URL-based MCP server connection as returned in API responses.

type: :url

url: String

class BetaManagedAgentsMCPToolConfig { enabled, name, permission_policy }

Resolved configuration for a specific MCP tool.

enabled: bool

permission_policy: BetaManagedAgentsAlwaysAllowPolicy { type } | BetaManagedAgentsAlwaysAskPolicy { type }

Permission policy for tool execution.

One of the following:

class BetaManagedAgentsAlwaysAllowPolicy { type }

Tool calls are automatically approved without user confirmation.

type: :always_allow

class BetaManagedAgentsAlwaysAskPolicy { type }

Tool calls require user confirmation before execution.

type: :always_ask

class BetaManagedAgentsMCPToolConfigParams { name, enabled, permission_policy }

Configuration override for a specific MCP tool.

Name of the MCP tool to configure. 1-128 characters.

minLength1

maxLength128

enabled: bool

Whether this tool is enabled. Overrides the default_config setting.

permission_policy: BetaManagedAgentsAlwaysAllowPolicy { type } | BetaManagedAgentsAlwaysAskPolicy { type }

Permission policy for tool execution.

One of the following:

class BetaManagedAgentsAlwaysAllowPolicy { type }

Tool calls are automatically approved without user confirmation.

type: :always_allow

class BetaManagedAgentsAlwaysAskPolicy { type }

Tool calls require user confirmation before execution.

type: :always_ask

class BetaManagedAgentsMCPToolset { configs, default_config, mcp_server_name, type }

class BetaManagedAgentsMCPToolsetDefaultConfig { enabled, permission_policy }

Resolved default configuration for all tools from an MCP server.

enabled: bool

permission_policy: BetaManagedAgentsAlwaysAllowPolicy { type } | BetaManagedAgentsAlwaysAskPolicy { type }

Permission policy for tool execution.

One of the following:

class BetaManagedAgentsAlwaysAllowPolicy { type }

Tool calls are automatically approved without user confirmation.

type: :always_allow

class BetaManagedAgentsAlwaysAskPolicy { type }

Tool calls require user confirmation before execution.

type: :always_ask

class BetaManagedAgentsMCPToolsetDefaultConfigParams { enabled, permission_policy }

Default configuration for all tools from an MCP server.

enabled: bool

Whether tools are enabled by default. Defaults to true if not specified.

permission_policy: BetaManagedAgentsAlwaysAllowPolicy { type } | BetaManagedAgentsAlwaysAskPolicy { type }

Permission policy for tool execution.

One of the following:

class BetaManagedAgentsAlwaysAllowPolicy { type }

Tool calls are automatically approved without user confirmation.

type: :always_allow

class BetaManagedAgentsAlwaysAskPolicy { type }

Tool calls require user confirmation before execution.

type: :always_ask

class BetaManagedAgentsMCPToolsetParams { mcp_server_name, type, configs, default_config }

Configuration for tools from an MCP server defined in mcp_servers.

BetaManagedAgentsModel = :"claude-sonnet-5" | :"claude-fable-5" | :"claude-opus-5" | 10 more | String

The model that will power your agent.

See models for additional details and options.

One of the following:

class BetaManagedAgentsModelConfig { id, effort, inference_geo, speed }

Model identifier and configuration.

class BetaManagedAgentsModelConfigParams { id, effort, inference_geo, speed }

An object that defines additional configuration control over model use

class BetaManagedAgentsMultiagentCoordinator { agents, type }

Resolved coordinator topology with a concrete agent roster.

class BetaManagedAgentsMultiagentCoordinatorParams { agents, type }

A coordinator topology: the session's primary thread orchestrates work by spawning session threads, each running an agent drawn from the agents roster.

class BetaManagedAgentsMultiagentSelfParams { type }

Sentinel roster entry meaning "the agent that owns this configuration". Resolved server-side to a concrete agent reference.

type: :self

class BetaManagedAgentsReadToolConfig { enabled, name, permission_policy, type }

Configuration for the read tool.

class BetaManagedAgentsReadToolConfigParams { name, enabled, permission_policy, type }

Configuration override for the read tool.

class BetaManagedAgentsSessionThreadAgent { id, description, mcp_servers, 7 more }

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.

BetaManagedAgentsSkillParams = BetaManagedAgentsAnthropicSkillParams { skill_id, type, version } | BetaManagedAgentsCustomSkillParams { skill_id, type, version }

Skill to load in the session container.

One of the following:

class BetaManagedAgentsURLMCPServerParams { name, type, url }

URL-based MCP server connection.

Unique name for this server, referenced by mcp_toolset configurations. 1-255 characters.

minLength1

maxLength255

type: :url

url: String

Endpoint URL for the MCP server.

maxLength2048

class BetaManagedAgentsUserLocation { type, city, country, 2 more }

Approximate user location for search result localization.

type: :approximate

Location precision. Only "approximate" is supported.

city: String

City name.

minLength1

maxLength255

country: String

Two-letter ISO 3166-1 country code, uppercase.

region: String

Region or state name.

minLength1

maxLength255

timezone: String

IANA timezone identifier, e.g. "America/Los_Angeles".

minLength1

maxLength255

class BetaManagedAgentsWebFetchToolConfig { enabled, name, permission_policy, 4 more }

Configuration for the web_fetch tool.

class BetaManagedAgentsWebFetchToolConfigParams { name, allowed_domains, blocked_domains, 4 more }

Configuration override for the web_fetch tool.

class BetaManagedAgentsWebSearchToolConfig { enabled, name, permission_policy, 4 more }

Configuration for the web_search tool.

class BetaManagedAgentsWebSearchToolConfigParams { name, allowed_domains, blocked_domains, 4 more }

Configuration override for the web_search tool.

class BetaManagedAgentsWriteToolConfig { enabled, name, permission_policy, type }

Configuration for the write tool.

class BetaManagedAgentsWriteToolConfigParams { name, enabled, permission_policy, type }

Configuration override for the write tool.

AgentsVersions

List Agent Versions

beta.agents.versions.list(agent_id, **kwargs) -> PageCursor<BetaManagedAgentsAgent>

GET/v1/agents/{agent_id}/versions