Claude Platform Docs

Agents

Create Agent
beta.agents.create(AgentCreateParams**kwargs) -> BetaManagedAgentsAgent
POST/v1/agents
List Agents
beta.agents.list(AgentListParams**kwargs) -> SyncPageCursor[BetaManagedAgentsAgent]
GET/v1/agents
Get Agent
beta.agents.retrieve(stragent_id, AgentRetrieveParams**kwargs) -> BetaManagedAgentsAgent
GET/v1/agents/{agent_id}
Update Agent
beta.agents.update(stragent_id, AgentUpdateParams**kwargs) -> BetaManagedAgentsAgent
POST/v1/agents/{agent_id}
Archive Agent
beta.agents.archive(stragent_id, AgentArchiveParams**kwargs) -> BetaManagedAgentsAgent
POST/v1/agents/{agent_id}/archive
Models
class BetaManagedAgentsAdvisor: …

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

model: str

The advisor model id.

type: Literal["advisor"]
class BetaManagedAgentsAgent: …

A Managed Agents agent.

class BetaManagedAgentsAgentReference: …

A resolved agent reference with a concrete version.

id: str
type: Literal["agent"]
version: int
formatint32
BetaManagedAgentsAgentToolConfig

Configuration for a specific agent tool.

One of the following:
BetaManagedAgentsAgentToolConfigParams

Configuration override for a specific tool within a toolset.

One of the following:
class BetaManagedAgentsAgentToolsetDefaultConfig: …

Resolved default configuration for agent tools.

enabled: bool
permission_policy: PermissionPolicy

Permission policy for tool execution.

One of the following:
class BetaManagedAgentsAlwaysAllowPolicy: …

Tool calls are automatically approved without user confirmation.

type: Literal["always_allow"]
class BetaManagedAgentsAlwaysAskPolicy: …

Tool calls require user confirmation before execution.

type: Literal["always_ask"]
class BetaManagedAgentsAgentToolsetDefaultConfigParams: …

Default configuration for all tools in a toolset.

enabled: Optional[bool]

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

permission_policy: Optional[PermissionPolicy]

Permission policy for tool execution.

One of the following:
class BetaManagedAgentsAlwaysAllowPolicy: …

Tool calls are automatically approved without user confirmation.

type: Literal["always_allow"]
class BetaManagedAgentsAlwaysAskPolicy: …

Tool calls require user confirmation before execution.

type: Literal["always_ask"]
class BetaManagedAgentsAgentToolset20260401: …
class BetaManagedAgentsAgentToolset20260401BashInput: …

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: Optional[str]

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

restart: Optional[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: Optional[int]

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

minimum0
class BetaManagedAgentsAgentToolset20260401EditInput: …

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

file_path: str

Path of the file to edit.

new_string: str

Replacement text.

old_string: str

Substring to find and replace.

replace_all: Optional[bool]

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

class BetaManagedAgentsAgentToolset20260401GlobInput: …

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

pattern: str

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

path: Optional[str]

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

class BetaManagedAgentsAgentToolset20260401GrepInput: …

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

pattern: str

Regular expression to search for.

path: Optional[str]

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

class BetaManagedAgentsAgentToolset20260401Params: …

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

class BetaManagedAgentsAgentToolset20260401ReadInput: …

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

file_path: str

Path of the file to read.

view_range: Optional[List[int]]

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: …

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

content: str

Full file contents to write.

file_path: str

Path of the file to write.

class BetaManagedAgentsAlwaysAllowPolicy: …

Tool calls are automatically approved without user confirmation.

type: Literal["always_allow"]
class BetaManagedAgentsAlwaysAskPolicy: …

Tool calls require user confirmation before execution.

type: Literal["always_ask"]
class BetaManagedAgentsAnthropicSkill: …

A resolved Anthropic-managed skill.

skill_id: str
type: Literal["anthropic"]
version: str
class BetaManagedAgentsAnthropicSkillParams: …

An Anthropic-managed skill.

skill_id: str

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

minLength1
maxLength64
type: Literal["anthropic"]
version: Optional[str]

Version to pin. Defaults to latest if omitted.

minLength1
maxLength64
class BetaManagedAgentsBashToolConfig: …

Configuration for the bash tool.

enabled: bool
name: Literal["bash"]
permission_policy: PermissionPolicy

Permission policy for tool execution.

One of the following:
class BetaManagedAgentsAlwaysAllowPolicy: …

Tool calls are automatically approved without user confirmation.

type: Literal["always_allow"]
class BetaManagedAgentsAlwaysAskPolicy: …

Tool calls require user confirmation before execution.

type: Literal["always_ask"]
type: Literal["bash"]
class BetaManagedAgentsBashToolConfigParams: …

Configuration override for the bash tool.

name: Literal["bash"]

Must be "bash".

enabled: Optional[bool]

Whether this tool is enabled and available to Claude. Overrides the default_config setting.

permission_policy: Optional[PermissionPolicy]

Permission policy for tool execution.

One of the following:
class BetaManagedAgentsAlwaysAllowPolicy: …

Tool calls are automatically approved without user confirmation.

type: Literal["always_allow"]
class BetaManagedAgentsAlwaysAskPolicy: …

Tool calls require user confirmation before execution.

type: Literal["always_ask"]
type: Optional[Literal["bash"]]
class BetaManagedAgentsCustomSkill: …

A resolved user-created custom skill.

skill_id: str
type: Literal["custom"]
version: str
class BetaManagedAgentsCustomSkillParams: …

A user-created custom skill.

skill_id: str

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

minLength1
maxLength64
type: Literal["custom"]
version: Optional[str]

Version to pin. Defaults to latest if omitted.

minLength1
maxLength64
class BetaManagedAgentsCustomTool: …

A custom tool as returned in API responses.

description: str
input_schema: BetaManagedAgentsCustomToolInputSchema

JSON Schema for custom tool input parameters.

type: Literal["object"]
properties: Optional[Dict[str, object]]
required: Optional[List[str]]
name: str
type: Literal["custom"]
class BetaManagedAgentsCustomToolInputSchema: …

JSON Schema for custom tool input parameters.

type: Literal["object"]
properties: Optional[Dict[str, object]]
required: Optional[List[str]]
class BetaManagedAgentsCustomToolParams: …

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: str

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

minLength1
input_schema: BetaManagedAgentsCustomToolInputSchema

JSON Schema for custom tool input parameters.

type: Literal["object"]
properties: Optional[Dict[str, object]]
required: Optional[List[str]]
name: str

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

minLength1
maxLength128
type: Literal["custom"]
class BetaManagedAgentsEditToolConfig: …

Configuration for the edit tool.

enabled: bool
name: Literal["edit"]
permission_policy: PermissionPolicy

Permission policy for tool execution.

One of the following:
class BetaManagedAgentsAlwaysAllowPolicy: …

Tool calls are automatically approved without user confirmation.

type: Literal["always_allow"]
class BetaManagedAgentsAlwaysAskPolicy: …

Tool calls require user confirmation before execution.

type: Literal["always_ask"]
type: Literal["edit"]
class BetaManagedAgentsEditToolConfigParams: …

Configuration override for the edit tool.

name: Literal["edit"]

Must be "edit".

enabled: Optional[bool]

Whether this tool is enabled and available to Claude. Overrides the default_config setting.

permission_policy: Optional[PermissionPolicy]

Permission policy for tool execution.

One of the following:
class BetaManagedAgentsAlwaysAllowPolicy: …

Tool calls are automatically approved without user confirmation.

type: Literal["always_allow"]
class BetaManagedAgentsAlwaysAskPolicy: …

Tool calls require user confirmation before execution.

type: Literal["always_ask"]
type: Optional[Literal["edit"]]
class BetaManagedAgentsEffortHigh: …

High effort. Favors reasoning depth.

type: Literal["high"]
class BetaManagedAgentsEffortLow: …

Low effort. Favors latency over reasoning depth.

type: Literal["low"]
class BetaManagedAgentsEffortMax: …

Maximum effort. Favors reasoning depth over latency.

type: Literal["max"]
class BetaManagedAgentsEffortMedium: …

Medium effort. Balances latency and reasoning depth.

type: Literal["medium"]
class BetaManagedAgentsEffortXhigh: …

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

type: Literal["xhigh"]
class BetaManagedAgentsGlobToolConfig: …

Configuration for the glob tool.

enabled: bool
name: Literal["glob"]
permission_policy: PermissionPolicy

Permission policy for tool execution.

One of the following:
class BetaManagedAgentsAlwaysAllowPolicy: …

Tool calls are automatically approved without user confirmation.

type: Literal["always_allow"]
class BetaManagedAgentsAlwaysAskPolicy: …

Tool calls require user confirmation before execution.

type: Literal["always_ask"]
type: Literal["glob"]
class BetaManagedAgentsGlobToolConfigParams: …

Configuration override for the glob tool.

name: Literal["glob"]

Must be "glob".

enabled: Optional[bool]

Whether this tool is enabled and available to Claude. Overrides the default_config setting.

permission_policy: Optional[PermissionPolicy]

Permission policy for tool execution.

One of the following:
class BetaManagedAgentsAlwaysAllowPolicy: …

Tool calls are automatically approved without user confirmation.

type: Literal["always_allow"]
class BetaManagedAgentsAlwaysAskPolicy: …

Tool calls require user confirmation before execution.

type: Literal["always_ask"]
type: Optional[Literal["glob"]]
class BetaManagedAgentsGrepToolConfig: …

Configuration for the grep tool.

enabled: bool
name: Literal["grep"]
permission_policy: PermissionPolicy

Permission policy for tool execution.

One of the following:
class BetaManagedAgentsAlwaysAllowPolicy: …

Tool calls are automatically approved without user confirmation.

type: Literal["always_allow"]
class BetaManagedAgentsAlwaysAskPolicy: …

Tool calls require user confirmation before execution.

type: Literal["always_ask"]
type: Literal["grep"]
class BetaManagedAgentsGrepToolConfigParams: …

Configuration override for the grep tool.

name: Literal["grep"]

Must be "grep".

enabled: Optional[bool]

Whether this tool is enabled and available to Claude. Overrides the default_config setting.

permission_policy: Optional[PermissionPolicy]

Permission policy for tool execution.

One of the following:
class BetaManagedAgentsAlwaysAllowPolicy: …

Tool calls are automatically approved without user confirmation.

type: Literal["always_allow"]
class BetaManagedAgentsAlwaysAskPolicy: …

Tool calls require user confirmation before execution.

type: Literal["always_ask"]
type: Optional[Literal["grep"]]
class BetaManagedAgentsMCPServerURLDefinition: …

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

name: str
type: Literal["url"]
url: str
class BetaManagedAgentsMCPToolConfig: …

Resolved configuration for a specific MCP tool.

enabled: bool
name: str
permission_policy: PermissionPolicy

Permission policy for tool execution.

One of the following:
class BetaManagedAgentsAlwaysAllowPolicy: …

Tool calls are automatically approved without user confirmation.

type: Literal["always_allow"]
class BetaManagedAgentsAlwaysAskPolicy: …

Tool calls require user confirmation before execution.

type: Literal["always_ask"]
class BetaManagedAgentsMCPToolConfigParams: …

Configuration override for a specific MCP tool.

name: str

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

minLength1
maxLength128
enabled: Optional[bool]

Whether this tool is enabled. Overrides the default_config setting.

permission_policy: Optional[PermissionPolicy]

Permission policy for tool execution.

One of the following:
class BetaManagedAgentsAlwaysAllowPolicy: …

Tool calls are automatically approved without user confirmation.

type: Literal["always_allow"]
class BetaManagedAgentsAlwaysAskPolicy: …

Tool calls require user confirmation before execution.

type: Literal["always_ask"]
class BetaManagedAgentsMCPToolset: …
class BetaManagedAgentsMCPToolsetDefaultConfig: …

Resolved default configuration for all tools from an MCP server.

enabled: bool
permission_policy: PermissionPolicy

Permission policy for tool execution.

One of the following:
class BetaManagedAgentsAlwaysAllowPolicy: …

Tool calls are automatically approved without user confirmation.

type: Literal["always_allow"]
class BetaManagedAgentsAlwaysAskPolicy: …

Tool calls require user confirmation before execution.

type: Literal["always_ask"]
class BetaManagedAgentsMCPToolsetDefaultConfigParams: …

Default configuration for all tools from an MCP server.

enabled: Optional[bool]

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

permission_policy: Optional[PermissionPolicy]

Permission policy for tool execution.

One of the following:
class BetaManagedAgentsAlwaysAllowPolicy: …

Tool calls are automatically approved without user confirmation.

type: Literal["always_allow"]
class BetaManagedAgentsAlwaysAskPolicy: …

Tool calls require user confirmation before execution.

type: Literal["always_ask"]
class BetaManagedAgentsMCPToolsetParams: …

Configuration for tools from an MCP server defined in mcp_servers.

Union[Literal["claude-sonnet-5", "claude-fable-5", "claude-opus-5", 10 more], str]

The model that will power your agent.

See models for additional details and options.

One of the following:
class BetaManagedAgentsModelConfig: …

Model identifier and configuration.

class BetaManagedAgentsModelConfigParams: …

An object that defines additional configuration control over model use

class BetaManagedAgentsMultiagentCoordinator: …

Resolved coordinator topology with a concrete agent roster.

agents: List[Agent]

Agents the coordinator may spawn as session threads, each resolved to a specific version.

One of the following:
class BetaManagedAgentsAgentReference: …

A resolved agent reference with a concrete version.

id: str
type: Literal["agent"]
version: int
formatint32
class BetaManagedAgentsAdvisor: …

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

model: str

The advisor model id.

type: Literal["advisor"]
type: Literal["coordinator"]
class BetaManagedAgentsMultiagentCoordinatorParams: …

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: …

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

type: Literal["self"]
class BetaManagedAgentsReadToolConfig: …

Configuration for the read tool.

enabled: bool
name: Literal["read"]
permission_policy: PermissionPolicy

Permission policy for tool execution.

One of the following:
class BetaManagedAgentsAlwaysAllowPolicy: …

Tool calls are automatically approved without user confirmation.

type: Literal["always_allow"]
class BetaManagedAgentsAlwaysAskPolicy: …

Tool calls require user confirmation before execution.

type: Literal["always_ask"]
type: Literal["read"]
class BetaManagedAgentsReadToolConfigParams: …

Configuration override for the read tool.

name: Literal["read"]

Must be "read".

enabled: Optional[bool]

Whether this tool is enabled and available to Claude. Overrides the default_config setting.

permission_policy: Optional[PermissionPolicy]

Permission policy for tool execution.

One of the following:
class BetaManagedAgentsAlwaysAllowPolicy: …

Tool calls are automatically approved without user confirmation.

type: Literal["always_allow"]
class BetaManagedAgentsAlwaysAskPolicy: …

Tool calls require user confirmation before execution.

type: Literal["always_ask"]
type: Optional[Literal["read"]]
class BetaManagedAgentsSessionThreadAgent: …

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

Skill to load in the session container.

One of the following:
class BetaManagedAgentsAnthropicSkillParams: …

An Anthropic-managed skill.

skill_id: str

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

minLength1
maxLength64
type: Literal["anthropic"]
version: Optional[str]

Version to pin. Defaults to latest if omitted.

minLength1
maxLength64
class BetaManagedAgentsCustomSkillParams: …

A user-created custom skill.

skill_id: str

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

minLength1
maxLength64
type: Literal["custom"]
version: Optional[str]

Version to pin. Defaults to latest if omitted.

minLength1
maxLength64
class BetaManagedAgentsURLMCPServerParams: …

URL-based MCP server connection.

name: str

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

minLength1
maxLength255
type: Literal["url"]
url: str

Endpoint URL for the MCP server.

maxLength2048
class BetaManagedAgentsUserLocation: …

Approximate user location for search result localization.

type: Literal["approximate"]

Location precision. Only "approximate" is supported.

city: Optional[str]

City name.

minLength1
maxLength255
country: Optional[str]

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

region: Optional[str]

Region or state name.

minLength1
maxLength255
timezone: Optional[str]

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

minLength1
maxLength255
class BetaManagedAgentsWebFetchToolConfig: …

Configuration for the web_fetch tool.

class BetaManagedAgentsWebFetchToolConfigParams: …

Configuration override for the web_fetch tool.

class BetaManagedAgentsWebSearchToolConfig: …

Configuration for the web_search tool.

class BetaManagedAgentsWebSearchToolConfigParams: …

Configuration override for the web_search tool.

class BetaManagedAgentsWriteToolConfig: …

Configuration for the write tool.

enabled: bool
name: Literal["write"]
permission_policy: PermissionPolicy

Permission policy for tool execution.

One of the following:
class BetaManagedAgentsAlwaysAllowPolicy: …

Tool calls are automatically approved without user confirmation.

type: Literal["always_allow"]
class BetaManagedAgentsAlwaysAskPolicy: …

Tool calls require user confirmation before execution.

type: Literal["always_ask"]
type: Literal["write"]
class BetaManagedAgentsWriteToolConfigParams: …

Configuration override for the write tool.

name: Literal["write"]

Must be "write".

enabled: Optional[bool]

Whether this tool is enabled and available to Claude. Overrides the default_config setting.

permission_policy: Optional[PermissionPolicy]

Permission policy for tool execution.

One of the following:
class BetaManagedAgentsAlwaysAllowPolicy: …

Tool calls are automatically approved without user confirmation.

type: Literal["always_allow"]
class BetaManagedAgentsAlwaysAskPolicy: …

Tool calls require user confirmation before execution.

type: Literal["always_ask"]
type: Optional[Literal["write"]]

AgentsVersions

List Agent Versions
beta.agents.versions.list(stragent_id, VersionListParams**kwargs) -> SyncPageCursor[BetaManagedAgentsAgent]
GET/v1/agents/{agent_id}/versions