--- title: List Agents url: https://platform.claude.com/docs/en/api/python/beta/agents/list --- # List Agents `beta.agents.list(**kwargs) -> SyncPageCursor[BetaManagedAgentsAgent]` **GET** `/v1/agents` List Agents ## Parameters - `created_at_gte: Optional[Union[str, datetime]]` (query parameter) Return agents created at or after this time (inclusive). format: date-time - `created_at_lte: Optional[Union[str, datetime]]` (query parameter) Return agents created at or before this time (inclusive). format: date-time - `include_archived: Optional[bool]` (query parameter) Include archived agents in results. Defaults to false. - `limit: Optional[int]` (query parameter) Maximum results per page. Default 20, maximum 100. format: int32 - `page: Optional[str]` (query parameter) Opaque pagination cursor from a previous response. - `betas: Optional[List[AnthropicBetaParam]]` (header parameter) Optional header to specify the beta version(s) you want to use. - `str` - `"message-batches-2024-09-24"` - `"prompt-caching-2024-07-31"` - `"computer-use-2024-10-22"` - `"computer-use-2025-01-24"` - `"pdfs-2024-09-25"` - `"token-counting-2024-11-01"` - `"token-efficient-tools-2025-02-19"` - `"output-128k-2025-02-19"` - `"files-api-2025-04-14"` - `"mcp-client-2025-04-04"` - `"mcp-client-2025-11-20"` - `"dev-full-thinking-2025-05-14"` - `"interleaved-thinking-2025-05-14"` - `"code-execution-2025-05-22"` - `"extended-cache-ttl-2025-04-11"` - `"context-1m-2025-08-07"` - `"context-management-2025-06-27"` - `"model-context-window-exceeded-2025-08-26"` - `"skills-2025-10-02"` - `"fast-mode-2026-02-01"` - `"output-300k-2026-03-24"` - `"user-profiles-2026-03-24"` - `"user-profiles-2026-08-18"` - `"user-profiles-2026-09-04"` - `"advisor-tool-2026-03-01"` - `"managed-agents-2026-04-01"` - `"cache-diagnosis-2026-04-07"` - `"dreaming-2026-04-21"` - `"thinking-token-count-2026-05-13"` - `"server-side-fallback-2026-06-01"` - `"server-side-fallback-2026-07-01"` - `"fallback-credit-2026-06-01"` - `"fallback-credit-2026-07-01"` - `"agent-memory-2026-07-22"` - `"mid-conversation-tool-changes-2026-07-01"` - `"compact-2026-01-12"` - `"computer-use-2025-11-24"` - `"mcp-tunnels-2026-06-22"` - `"structured-outputs-2025-11-13"` - `"task-budgets-2026-03-13"` - `"thinking-display-updates-2026-08-18"` - `"ce-user-management-2026-07-13"` - `"mid-conversation-output-config-2026-07-01"` - `"thinking-binding-controls-2026-08-01"` - `"mid-conversation-system-clear-at-2026-08-21"` - `"compact-2026-09-04"` - `"inline-tools-2026-09-15"` - `"mcp-client-2026-09-15"` - `"ce-plugins-2026-09-01"` - `"spend-limit-reads-2026-09-26"` - `workspace_id: Optional[str]` (header parameter) Optional header to select the Workspace for this request. The value is a Workspace ID (for example, `wrkspc_011CZkZaBF1tNoB5wlCeusgy`). Only needed for credentials that can act on more than one Workspace. A credential that belongs to a specific Workspace may omit it; if sent, it must match that Workspace. ## Returns - `class BetaManagedAgentsAgent` A Managed Agents `agent`. - `type: Literal["agent"]` - `id: str` - `archived_at: Optional[datetime]` When the agent was archived. Null if not archived. format: date-time - `created_at: datetime` A timestamp in RFC 3339 format format: date-time - `description: Optional[str]` - `mcp_servers: List[BetaManagedAgentsMCPServerURLDefinition]` - `type: Literal["url"]` - `name: str` - `url: str` - `metadata: Dict[str, str]` - `model: BetaManagedAgentsModelConfig` Model identifier and configuration. - `id: BetaManagedAgentsModel` The model that will power your agent. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - `"claude-haiku-5-5"` Fastest model for high-volume, real-time tasks - `"claude-sonnet-5-5"` Efficient model for coding and agents - `"claude-opus-5-5"` Powerful intelligence for coding, knowledge work, and long-running agents - `"claude-fable-5-1"` Frontier intelligence for ambitious tasks across coding, scientific discovery, and enterprise workflows - `"claude-sonnet-5"` Efficient 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"` - `"claude-haiku-4-5-20251001"` - `"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"` **Deprecated**: Will reach end-of-life on November 30, 2026. Please migrate to claude-sonnet-5-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information. High-performance model for agents and coding - `"claude-sonnet-4-5-20250929"` **Deprecated**: Will reach end-of-life on November 30, 2026. Please migrate to claude-sonnet-5-5. Visit https://docs.anthropic.com/en/docs/resources/model-deprecations for more information. High-performance model for agents and coding - `str` - `effort: Optional[Effort]` How hard Claude works on each inference call. One of `low`, `medium`, `high`, `xhigh`, `max`. Always present; resolved to the per-model default at save time when not supplied. - `class BetaManagedAgentsEffortLow` Low effort. Favors latency over reasoning depth. - `type: Literal["low"]` - `class BetaManagedAgentsEffortMedium` Medium effort. Balances latency and reasoning depth. - `type: Literal["medium"]` - `class BetaManagedAgentsEffortHigh` High effort. Favors reasoning depth. - `type: Literal["high"]` - `class BetaManagedAgentsEffortXhigh` Extra-high effort. Not all models accept this level. - `type: Literal["xhigh"]` - `class BetaManagedAgentsEffortMax` Maximum effort. Favors reasoning depth over latency. - `type: Literal["max"]` - `inference_geo: Optional[str]` Geographic region for model inference. When unset, requests fall through to the workspace's default_inference_geo. - `speed: Optional[Literal["standard", "fast"]]` Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Defaults to `standard`. Not all models support `fast`; invalid combinations are rejected at create time. - `"standard"` - `"fast"` - `multiagent: Optional[BetaManagedAgentsMultiagent]` Multiagent orchestration configuration. Null when the agent is single-threaded. - `class BetaManagedAgentsMultiagentCoordinator` Resolved coordinator topology with a concrete agent roster. - `type: Literal["coordinator"]` - `agents: List[Agent]` Agents the coordinator may spawn as session threads, each resolved to a specific version. - `class BetaManagedAgentsAgentReference` A resolved agent reference with a concrete version. - `type: Literal["agent"]` - `id: str` - `version: int` format: int32 - `class BetaManagedAgentsAdvisor` Platform advisor roster entry: a model the session's primary thread may consult mid-turn. - `type: Literal["advisor"]` - `model: str` The advisor model id. - `class BetaManagedAgentsMultiagent20261001` Resolved multiagent configuration with three members, each enabled or disabled on its own. - `type: Literal["multiagent_20261001"]` - `advisor: BetaManagedAgentsMultiagentAdvisor` Whether the session's primary thread can consult an advisor model. - `class BetaManagedAgentsMultiagentAdvisorEnabled` The session's primary thread can consult `model` mid-turn. - `type: Literal["enabled"]` - `model: str` The advisor model id. - `class BetaManagedAgentsMultiagentAdvisorDisabled` The agent has no advisor. - `type: Literal["disabled"]` - `subagents: BetaManagedAgentsMultiagentSubagents` Whether the agent can spawn session threads. - `class BetaManagedAgentsMultiagentSubagentsEnabled` The agent can spawn session threads. - `type: Literal["enabled"]` - `inline_agents: BetaManagedAgentsMultiagentInlineAgents` Whether the agent can define inline agents, which are not saved, when it spawns session threads. - `class BetaManagedAgentsMultiagentInlineAgentsEnabled` The agent can define inline agents. - `type: Literal["enabled"]` - `class BetaManagedAgentsMultiagentInlineAgentsDisabled` The agent cannot define inline agents. - `type: Literal["disabled"]` - `predefined_agents: List[BetaManagedAgentsAgentReference]` Predefined agents, which are saved agents that this agent can spawn as session threads, each resolved to a specific version. - `type: Literal["agent"]` - `id: str` - `version: int` format: int32 - `class BetaManagedAgentsMultiagentSubagentsDisabled` The agent cannot spawn session threads. - `type: Literal["disabled"]` - `workflows: BetaManagedAgentsMultiagentWorkflows` Whether the agent can start workflow runs. - `class BetaManagedAgentsMultiagentWorkflowsEnabled` The agent can start workflow runs. - `type: Literal["enabled"]` - `inline_agents: BetaManagedAgentsMultiagentInlineAgents` Whether a run's plan can define inline agents, which are not saved. - `predefined_agents: List[BetaManagedAgentsAgentReference]` Predefined agents, which are saved agents that a run's plan can use, each resolved to a specific version. - `type: Literal["agent"]` - `id: str` - `version: int` format: int32 - `class BetaManagedAgentsMultiagentWorkflowsDisabled` The agent cannot start workflow runs. - `type: Literal["disabled"]` - `name: str` - `skills: List[Skill]` - `class BetaManagedAgentsAnthropicSkill` A resolved Anthropic-managed skill. - `type: Literal["anthropic"]` - `skill_id: str` - `version: str` - `class BetaManagedAgentsCustomSkill` A resolved user-created custom skill. - `type: Literal["custom"]` - `skill_id: str` - `version: str` - `system: Optional[str]` - `tools: List[Tool]` - `class BetaManagedAgentsAgentToolset20260401` - `type: Literal["agent_toolset_20260401"]` - `configs: List[BetaManagedAgentsAgentToolConfig]` - `class BetaManagedAgentsBashToolConfig` Configuration for the bash tool. - `type: Literal["bash"]` - `enabled: bool` - `name: Literal["bash"]` - `permission_policy: PermissionPolicy` Permission policy for tool execution. - `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 BetaManagedAgentsAutoPolicy` 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. - `type: Literal["auto"]` - `class BetaManagedAgentsEditToolConfig` Configuration for the edit tool. - `type: Literal["edit"]` - `enabled: bool` - `name: Literal["edit"]` - `permission_policy: PermissionPolicy` Permission policy for tool execution. - `class BetaManagedAgentsAlwaysAllowPolicy` Tool calls are automatically approved without user confirmation. - `class BetaManagedAgentsAlwaysAskPolicy` Tool calls require user confirmation before execution. - `class BetaManagedAgentsAutoPolicy` 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. - `class BetaManagedAgentsReadToolConfig` Configuration for the read tool. - `type: Literal["read"]` - `enabled: bool` - `name: Literal["read"]` - `permission_policy: PermissionPolicy` Permission policy for tool execution. - `class BetaManagedAgentsAlwaysAllowPolicy` Tool calls are automatically approved without user confirmation. - `class BetaManagedAgentsAlwaysAskPolicy` Tool calls require user confirmation before execution. - `class BetaManagedAgentsAutoPolicy` 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. - `class BetaManagedAgentsWriteToolConfig` Configuration for the write tool. - `type: Literal["write"]` - `enabled: bool` - `name: Literal["write"]` - `permission_policy: PermissionPolicy` Permission policy for tool execution. - `class BetaManagedAgentsAlwaysAllowPolicy` Tool calls are automatically approved without user confirmation. - `class BetaManagedAgentsAlwaysAskPolicy` Tool calls require user confirmation before execution. - `class BetaManagedAgentsAutoPolicy` 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. - `class BetaManagedAgentsGlobToolConfig` Configuration for the glob tool. - `type: Literal["glob"]` - `enabled: bool` - `name: Literal["glob"]` - `permission_policy: PermissionPolicy` Permission policy for tool execution. - `class BetaManagedAgentsAlwaysAllowPolicy` Tool calls are automatically approved without user confirmation. - `class BetaManagedAgentsAlwaysAskPolicy` Tool calls require user confirmation before execution. - `class BetaManagedAgentsAutoPolicy` 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. - `class BetaManagedAgentsGrepToolConfig` Configuration for the grep tool. - `type: Literal["grep"]` - `enabled: bool` - `name: Literal["grep"]` - `permission_policy: PermissionPolicy` Permission policy for tool execution. - `class BetaManagedAgentsAlwaysAllowPolicy` Tool calls are automatically approved without user confirmation. - `class BetaManagedAgentsAlwaysAskPolicy` Tool calls require user confirmation before execution. - `class BetaManagedAgentsAutoPolicy` 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. - `class BetaManagedAgentsWebFetchToolConfig` Configuration for the web_fetch tool. - `type: Literal["web_fetch"]` - `enabled: bool` - `name: Literal["web_fetch"]` - `permission_policy: PermissionPolicy` Permission policy for tool execution. - `class BetaManagedAgentsAlwaysAllowPolicy` Tool calls are automatically approved without user confirmation. - `class BetaManagedAgentsAlwaysAskPolicy` Tool calls require user confirmation before execution. - `class BetaManagedAgentsAutoPolicy` 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. - `url_sources: Optional[BetaManagedAgentsWebFetchURLSources]` Which sources contribute URLs the tool may fetch, always in the object form. Null when not set, which allows every source. - `client_tool_results: Optional[BetaManagedAgentsWebFetchURLSourceToolFilter]` Which custom tools' results contribute URLs that may be fetched. Null when not set, which allows every custom tool's results. - `class BetaManagedAgentsWebFetchURLSourceAll` Every URL from this source may be fetched. This is the default. - `type: Literal["all"]` - `class BetaManagedAgentsWebFetchURLSourceNone` This source contributes no URLs that may be fetched. - `type: Literal["none"]` - `class BetaManagedAgentsWebFetchURLSourceOnly` Only the named tools' results contribute URLs that may be fetched. - `type: Literal["only"]` - `tools: List[BetaManagedAgentsWebFetchURLSourceToolReference]` 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. - `type: Literal["tool_reference"]` Must be "tool_reference". - `name: str` Name of the tool. Compared exactly, so upper and lower case letters are different. minLength: 1, maxLength: 128 - `class BetaManagedAgentsWebFetchURLSourceExcept` Every tool's results contribute URLs that may be fetched, except the named tools' results. - `type: Literal["except"]` - `tools: List[BetaManagedAgentsWebFetchURLSourceToolReference]` 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. - `type: Literal["tool_reference"]` Must be "tool_reference". - `name: str` Name of the tool. Compared exactly, so upper and lower case letters are different. minLength: 1, maxLength: 128 - `server_tool_results: Optional[BetaManagedAgentsWebFetchURLSourceToolFilter]` Which of the web_search and web_fetch tools' results contribute URLs that may be fetched. Null when not set, which allows both. - `user_input: Optional[BetaManagedAgentsWebFetchURLSourceUserInput]` Whether URLs in the text of user messages may be fetched. Null when not set, which allows them. - `class BetaManagedAgentsWebFetchURLSourceAll` Every URL from this source may be fetched. This is the default. - `class BetaManagedAgentsWebFetchURLSourceNone` This source contributes no URLs that may be fetched. - `allowed_domains: Optional[List[str]]` - `blocked_domains: Optional[List[str]]` - `max_content_tokens: Optional[int]` format: int32 - `class BetaManagedAgentsWebSearchToolConfig` Configuration for the web_search tool. - `type: Literal["web_search"]` - `enabled: bool` - `name: Literal["web_search"]` - `permission_policy: PermissionPolicy` Permission policy for tool execution. - `class BetaManagedAgentsAlwaysAllowPolicy` Tool calls are automatically approved without user confirmation. - `class BetaManagedAgentsAlwaysAskPolicy` Tool calls require user confirmation before execution. - `class BetaManagedAgentsAutoPolicy` 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. - `allowed_domains: Optional[List[str]]` - `blocked_domains: Optional[List[str]]` - `user_location: Optional[BetaManagedAgentsUserLocation]` Approximate user location for search result localization. - `type: Literal["approximate"]` Location precision. Only "approximate" is supported. - `city: Optional[str]` City name. minLength: 1, maxLength: 255 - `country: Optional[str]` Two-letter ISO 3166-1 country code, uppercase. - `region: Optional[str]` Region or state name. minLength: 1, maxLength: 255 - `timezone: Optional[str]` IANA timezone identifier, e.g. "America/Los_Angeles". minLength: 1, maxLength: 255 - `default_config: BetaManagedAgentsAgentToolsetDefaultConfig` Resolved default configuration for agent tools. - `enabled: bool` - `permission_policy: PermissionPolicy` Permission policy for tool execution. - `class BetaManagedAgentsAlwaysAllowPolicy` Tool calls are automatically approved without user confirmation. - `class BetaManagedAgentsAlwaysAskPolicy` Tool calls require user confirmation before execution. - `class BetaManagedAgentsAutoPolicy` 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. - `class BetaManagedAgentsMCPToolset` - `type: Literal["mcp_toolset"]` - `configs: List[BetaManagedAgentsMCPToolConfig]` - `enabled: bool` - `name: str` - `permission_policy: PermissionPolicy` Permission policy for tool execution. - `class BetaManagedAgentsAlwaysAllowPolicy` Tool calls are automatically approved without user confirmation. - `class BetaManagedAgentsAlwaysAskPolicy` Tool calls require user confirmation before execution. - `class BetaManagedAgentsAutoPolicy` 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. - `default_config: BetaManagedAgentsMCPToolsetDefaultConfig` Resolved default configuration for all tools from an MCP server. - `enabled: bool` - `permission_policy: PermissionPolicy` Permission policy for tool execution. - `class BetaManagedAgentsAlwaysAllowPolicy` Tool calls are automatically approved without user confirmation. - `class BetaManagedAgentsAlwaysAskPolicy` Tool calls require user confirmation before execution. - `class BetaManagedAgentsAutoPolicy` 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. - `mcp_server_name: str` - `class BetaManagedAgentsCustomTool` A custom tool as returned in API responses. - `type: Literal["custom"]` - `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` - `updated_at: datetime` A timestamp in RFC 3339 format format: date-time - `version: int` The agent's current version. Starts at 1 and increments when the agent is modified. format: int32 ## Example ```python import os from anthropic import Anthropic client = Anthropic( api_key=os.environ.get( "ANTHROPIC_API_KEY" ), # This is the default and can be omitted ) page = client.beta.agents.list() page = page.data[0] print(page.id) ``` ### Response (200) ```json { "data": [ { "id": "agent_011CZkYpogX7uDKUyvBTophP", "archived_at": null, "created_at": "2026-03-15T10:00:00Z", "description": "A general-purpose starter agent.", "mcp_servers": [ { "name": "example-mcp", "type": "url", "url": "https://example-server.modelcontextprotocol.io/sse" } ], "metadata": { "foo": "bar" }, "model": { "id": "claude-opus-5", "effort": { "type": "low" }, "inference_geo": "inference_geo", "speed": "standard" }, "multiagent": { "advisor": { "type": "disabled" }, "subagents": { "inline_agents": { "type": "enabled" }, "predefined_agents": [ { "id": "agent_011CZkYqphY8vELVzwCUpqiQ", "type": "agent", "version": 1 } ], "type": "enabled" }, "type": "multiagent_20261001", "workflows": { "inline_agents": { "type": "enabled" }, "predefined_agents": [ { "id": "agent_011CZkYqphY8vELVzwCUpqiQ", "type": "agent", "version": 1 } ], "type": "enabled" } }, "name": "My First Agent", "skills": [ { "skill_id": "xlsx", "type": "anthropic", "version": "1" }, { "skill_id": "skill_011CZkZFNu9hAbo3jZPRgTmx", "type": "custom", "version": "2" } ], "system": "You are a general-purpose agent that can research, write code, run commands, and use connected tools to complete the user's task end to end.", "tools": [ { "configs": [ { "enabled": true, "name": "bash", "permission_policy": { "type": "always_allow" }, "type": "bash" } ], "default_config": { "enabled": true, "permission_policy": { "type": "always_ask" } }, "type": "agent_toolset_20260401" } ], "type": "agent", "updated_at": "2026-03-15T10:00:00Z", "version": 1 } ], "next_page": "next_page" } ```