--- title: Agents url: https://platform.claude.com/docs/en/api/php/beta/agents --- # Agents ## Create Agent `$client->beta->agents->create(Model model, string name, ?string description, ?BetaManagedAgentsExecutionIdentityParams executionIdentity, ?list mcpServers, ?array metadata, ?BetaManagedAgentsMultiagentParams multiagent, ?list skills, ?string system, ?list tools, ?list betas, ?string workspaceID): BetaManagedAgentsAgent` **POST** `/v1/agents` Create Agent ### Parameters - `model: Model` Model identifier. Accepts the [model string](https://platform.claude.com/docs/en/about-claude/models/overview?sdk_languages=php#latest-models-comparison), e.g. `claude-opus-5-5`, or a `model_config` object for additional configuration control - `name: string` Human-readable name for the agent. - `description?: optional string` Description of what the agent does. - `executionIdentity?: optional BetaManagedAgentsExecutionIdentityParams` Execution principal for runs of this agent. Omitting it, sending null, or sending `{"type": "service_account"}` stores the default. - `mcpServers?: optional list` MCP servers this agent connects to. Maximum 20. Names must be unique within the array. Every server must be referenced by an `mcp_toolset` in `tools`; unreferenced servers are rejected. See the [MCP connector guide](https://platform.claude.com/docs/en/managed-agents/mcp-connector?sdk_languages=php). - `metadata?: optional array` Arbitrary key-value metadata. Maximum 16 pairs, keys up to 64 chars, values up to 512 chars. - `multiagent?: optional BetaManagedAgentsMultiagentParams` Multiagent orchestration configuration. - `skills?: optional list` Skills available to the agent. - `system?: optional string` System prompt for the agent. - `tools?: optional list` Tool configurations available to the agent. Maximum of 256 tools across all toolsets allowed. - `betas?: optional list` (header parameter) This endpoint is in beta: requests must send `managed-agents-2026-04-01` in this header. - `workspaceID?: optional string` (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` - `"agent" type` - `string id` - `?\Datetime archivedAt` When the agent was archived. Null if not archived. - `\Datetime createdAt` A timestamp in RFC 3339 format - `?string description` - `BetaManagedAgentsExecutionIdentity executionIdentity` Execution principal for runs of this agent. Always present; `{"type": "service_account"}` when runs carry no customer-named principal. - `list mcpServers` - `array metadata` - `BetaManagedAgentsModelConfig model` Model identifier and configuration. - `?BetaManagedAgentsMultiagent multiagent` Multiagent orchestration configuration. Null when the agent is single-threaded. - `string name` - `list skills` - `?string system` - `list tools` - `\Datetime updatedAt` A timestamp in RFC 3339 format - `int version` The agent's current version. Starts at 1 and increments when the agent is modified. ### Example ```php beta->agents->create( model: BetaManagedAgentsModel::CLAUDE_OPUS_5_5, name: 'My First Agent', description: 'A general-purpose starter agent.', executionIdentity: [ 'roleARN' => 'arn:aws:iam::228601553692:role/T', 'type' => 'aws_role' ], mcpServers: [ [ 'name' => 'example-mcp', 'type' => 'url', 'url' => 'https://example-server.modelcontextprotocol.io/sse', ], ], metadata: ['foo' => 'bar'], multiagent: [ 'agents' => ['agent_011CZkYqphY8vELVzwCUpqiQ', ['type' => 'self']], 'type' => 'coordinator', ], skills: [['skillID' => 'xlsx', 'type' => 'anthropic', 'version' => '1']], 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: [ [ 'type' => 'agent_toolset_20260401', 'configs' => [ [ 'name' => 'bash', 'enabled' => true, 'permissionPolicy' => ['type' => 'always_allow'], 'type' => 'bash', ], ], 'defaultConfig' => [ 'enabled' => true, 'permissionPolicy' => ['type' => 'always_allow'] ], ], ], betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], workspaceID: 'wrkspc_011CZkZaBF1tNoB5wlCeusgy', ); var_dump($betaManagedAgentsAgent); ``` #### Response (200) ```json { "id": "agent_011CZkYpogX7uDKUyvBTophP", "archived_at": null, "created_at": "2026-03-15T10:00:00Z", "description": "A general-purpose starter agent.", "execution_identity": { "type": "service_account" }, "mcp_servers": [ { "name": "example-mcp", "type": "url", "url": "https://example-server.modelcontextprotocol.io/sse" } ], "metadata": { "foo": "bar" }, "model": { "id": "claude-opus-5-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 } ``` ## List Agents `$client->beta->agents->list(?\Datetime createdAtGte, ?\Datetime createdAtLte, ?bool includeArchived, ?int limit, ?string page, ?list betas, ?string workspaceID): PageCursor` **GET** `/v1/agents` List Agents ### Parameters - `createdAtGte?: optional \Datetime` (query parameter) Return agents created at or after this time (inclusive). - `createdAtLte?: optional \Datetime` (query parameter) Return agents created at or before this time (inclusive). - `includeArchived?: 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. - `page?: optional string` (query parameter) Opaque pagination cursor from a previous response. - `betas?: optional list` (header parameter) This endpoint is in beta: requests must send `managed-agents-2026-04-01` in this header. - `workspaceID?: optional string` (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` - `"agent" type` - `string id` - `?\Datetime archivedAt` When the agent was archived. Null if not archived. - `\Datetime createdAt` A timestamp in RFC 3339 format - `?string description` - `BetaManagedAgentsExecutionIdentity executionIdentity` Execution principal for runs of this agent. Always present; `{"type": "service_account"}` when runs carry no customer-named principal. - `list mcpServers` - `array metadata` - `BetaManagedAgentsModelConfig model` Model identifier and configuration. - `?BetaManagedAgentsMultiagent multiagent` Multiagent orchestration configuration. Null when the agent is single-threaded. - `string name` - `list skills` - `?string system` - `list tools` - `\Datetime updatedAt` A timestamp in RFC 3339 format - `int version` The agent's current version. Starts at 1 and increments when the agent is modified. ### Example ```php beta->agents->list( createdAtGte: new \DateTimeImmutable('2019-12-27T18:11:19.117Z'), createdAtLte: new \DateTimeImmutable('2019-12-27T18:11:19.117Z'), includeArchived: true, limit: 0, page: 'page', betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], workspaceID: 'wrkspc_011CZkZaBF1tNoB5wlCeusgy', ); var_dump($page); ``` #### Response (200) ```json { "data": [ { "id": "agent_011CZkYpogX7uDKUyvBTophP", "archived_at": null, "created_at": "2026-03-15T10:00:00Z", "description": "A general-purpose starter agent.", "execution_identity": { "type": "service_account" }, "mcp_servers": [ { "name": "example-mcp", "type": "url", "url": "https://example-server.modelcontextprotocol.io/sse" } ], "metadata": { "foo": "bar" }, "model": { "id": "claude-opus-5-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" } ``` ## Get Agent `$client->beta->agents->retrieve(string agentID, ?int version, ?list betas, ?string workspaceID): BetaManagedAgentsAgent` **GET** `/v1/agents/{agent_id}` Get Agent ### Parameters - `agentID: string` (path parameter) Unique identifier of the agent to retrieve. - `version?: optional int` (query parameter) Agent version. Omit for the most recent version. Must be at least 1 if specified. - `betas?: optional list` (header parameter) This endpoint is in beta: requests must send `managed-agents-2026-04-01` in this header. - `workspaceID?: optional string` (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` - `"agent" type` - `string id` - `?\Datetime archivedAt` When the agent was archived. Null if not archived. - `\Datetime createdAt` A timestamp in RFC 3339 format - `?string description` - `BetaManagedAgentsExecutionIdentity executionIdentity` Execution principal for runs of this agent. Always present; `{"type": "service_account"}` when runs carry no customer-named principal. - `list mcpServers` - `array metadata` - `BetaManagedAgentsModelConfig model` Model identifier and configuration. - `?BetaManagedAgentsMultiagent multiagent` Multiagent orchestration configuration. Null when the agent is single-threaded. - `string name` - `list skills` - `?string system` - `list tools` - `\Datetime updatedAt` A timestamp in RFC 3339 format - `int version` The agent's current version. Starts at 1 and increments when the agent is modified. ### Example ```php beta->agents->retrieve( 'agent_011CZkYpogX7uDKUyvBTophP', version: 0, betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], workspaceID: 'wrkspc_011CZkZaBF1tNoB5wlCeusgy', ); var_dump($betaManagedAgentsAgent); ``` #### Response (200) ```json { "id": "agent_011CZkYpogX7uDKUyvBTophP", "archived_at": null, "created_at": "2026-03-15T10:00:00Z", "description": "A general-purpose starter agent.", "execution_identity": { "type": "service_account" }, "mcp_servers": [ { "name": "example-mcp", "type": "url", "url": "https://example-server.modelcontextprotocol.io/sse" } ], "metadata": { "foo": "bar" }, "model": { "id": "claude-opus-5-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 } ``` ## Update Agent `$client->beta->agents->update(string agentID, ?string description, ?BetaManagedAgentsExecutionIdentityParams executionIdentity, ?list mcpServers, ?array metadata, ?Model model, ?BetaManagedAgentsMultiagentParams multiagent, ?string name, ?list skills, ?string system, ?list tools, ?int version, ?list betas, ?string workspaceID): BetaManagedAgentsAgent` **POST** `/v1/agents/{agent_id}` Update Agent ### Parameters - `agentID: string` (path parameter) Unique identifier of the agent to update. - `description?: optional string` Description. Omit to preserve; send empty string or null to clear. - `executionIdentity?: optional BetaManagedAgentsExecutionIdentityParams` Execution principal for runs of this agent. Full replacement. Omit to preserve; send null or `{"type": "service_account"}` to restore the default. - `mcpServers?: optional list` MCP servers. Full replacement. Omit to preserve; send empty array or `null` to clear. Names must be unique. Maximum 20. Every server must be referenced by an `mcp_toolset` in the agent's resulting `tools`; unreferenced servers are rejected. See the [MCP connector guide](https://platform.claude.com/docs/en/managed-agents/mcp-connector?sdk_languages=php). - `metadata?: optional array` Metadata patch. Set a key to a string to upsert it, or to null to delete it. Omit the field to preserve. The stored bag is limited to 16 keys (up to 64 chars each) with values up to 512 chars. - `model?: optional Model` Model identifier. Accepts the [model string](https://platform.claude.com/docs/en/about-claude/models/overview?sdk_languages=php#latest-models-comparison), e.g. `claude-opus-5-5`, or a `model_config` object for additional configuration control. Omit to preserve. Cannot be cleared. - `multiagent?: optional BetaManagedAgentsMultiagentParams` Multiagent orchestration configuration. Full replacement. Omit to preserve; send null to clear. - `name?: optional string` Human-readable name. Must be non-empty. Omit to preserve. Cannot be cleared. - `skills?: optional list` Skills. Full replacement. Omit to preserve; send empty array or null to clear. - `system?: optional string` System prompt. Omit to preserve; send empty string or null to clear. - `tools?: optional list` Tool configurations available to the agent. Full replacement. Omit to preserve; send empty array or null to clear. Maximum of 256 tools across all toolsets allowed. - `version?: optional int` The agent's current version, used to prevent concurrent overwrites. Obtain this value from a create or retrieve response. Must be at least 1 if specified. When supplied, the request fails if it does not match the server's current version; omit to apply the update unconditionally. - `betas?: optional list` (header parameter) This endpoint is in beta: requests must send `managed-agents-2026-04-01` in this header. - `workspaceID?: optional string` (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` - `"agent" type` - `string id` - `?\Datetime archivedAt` When the agent was archived. Null if not archived. - `\Datetime createdAt` A timestamp in RFC 3339 format - `?string description` - `BetaManagedAgentsExecutionIdentity executionIdentity` Execution principal for runs of this agent. Always present; `{"type": "service_account"}` when runs carry no customer-named principal. - `list mcpServers` - `array metadata` - `BetaManagedAgentsModelConfig model` Model identifier and configuration. - `?BetaManagedAgentsMultiagent multiagent` Multiagent orchestration configuration. Null when the agent is single-threaded. - `string name` - `list skills` - `?string system` - `list tools` - `\Datetime updatedAt` A timestamp in RFC 3339 format - `int version` The agent's current version. Starts at 1 and increments when the agent is modified. ### Example ```php beta->agents->update( 'agent_011CZkYpogX7uDKUyvBTophP', description: 'updated', executionIdentity: [ 'roleARN' => 'arn:aws:iam::228601553692:role/T', 'type' => 'aws_role' ], mcpServers: [ [ 'name' => 'example-mcp', 'type' => 'url', 'url' => 'https://example-server.modelcontextprotocol.io/sse', ], ], metadata: ['foo' => 'string'], model: [ 'id' => BetaManagedAgentsModel::CLAUDE_OPUS_5_5, 'effort' => 'low', 'inferenceGeo' => 'inference_geo', 'speed' => 'standard', ], multiagent: [ 'agents' => ['agent_011CZkYqphY8vELVzwCUpqiQ', ['type' => 'self']], 'type' => 'coordinator', ], name: 'name', skills: [['skillID' => 'xlsx', 'type' => 'anthropic', 'version' => '1']], 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: [ [ 'type' => 'agent_toolset_20260401', 'configs' => [ [ 'name' => 'bash', 'enabled' => true, 'permissionPolicy' => ['type' => 'always_allow'], 'type' => 'bash', ], ], 'defaultConfig' => [ 'enabled' => true, 'permissionPolicy' => ['type' => 'always_allow'] ], ], ], version: 1, betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], workspaceID: 'wrkspc_011CZkZaBF1tNoB5wlCeusgy', ); var_dump($betaManagedAgentsAgent); ``` #### Response (200) ```json { "id": "agent_011CZkYpogX7uDKUyvBTophP", "archived_at": null, "created_at": "2026-03-15T10:00:00Z", "description": "A general-purpose starter agent.", "execution_identity": { "type": "service_account" }, "mcp_servers": [ { "name": "example-mcp", "type": "url", "url": "https://example-server.modelcontextprotocol.io/sse" } ], "metadata": { "foo": "bar" }, "model": { "id": "claude-opus-5-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 } ``` ## Archive Agent `$client->beta->agents->archive(string agentID, ?list betas, ?string workspaceID): BetaManagedAgentsAgent` **POST** `/v1/agents/{agent_id}/archive` Archive Agent ### Parameters - `agentID: string` (path parameter) Unique identifier of the agent to archive. - `betas?: optional list` (header parameter) This endpoint is in beta: requests must send `managed-agents-2026-04-01` in this header. - `workspaceID?: optional string` (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` - `"agent" type` - `string id` - `?\Datetime archivedAt` When the agent was archived. Null if not archived. - `\Datetime createdAt` A timestamp in RFC 3339 format - `?string description` - `BetaManagedAgentsExecutionIdentity executionIdentity` Execution principal for runs of this agent. Always present; `{"type": "service_account"}` when runs carry no customer-named principal. - `list mcpServers` - `array metadata` - `BetaManagedAgentsModelConfig model` Model identifier and configuration. - `?BetaManagedAgentsMultiagent multiagent` Multiagent orchestration configuration. Null when the agent is single-threaded. - `string name` - `list skills` - `?string system` - `list tools` - `\Datetime updatedAt` A timestamp in RFC 3339 format - `int version` The agent's current version. Starts at 1 and increments when the agent is modified. ### Example ```php beta->agents->archive( 'agent_011CZkYpogX7uDKUyvBTophP', betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], workspaceID: 'wrkspc_011CZkZaBF1tNoB5wlCeusgy', ); var_dump($betaManagedAgentsAgent); ``` #### Response (200) ```json { "id": "agent_011CZkYpogX7uDKUyvBTophP", "archived_at": null, "created_at": "2026-03-15T10:00:00Z", "description": "A general-purpose starter agent.", "execution_identity": { "type": "service_account" }, "mcp_servers": [ { "name": "example-mcp", "type": "url", "url": "https://example-server.modelcontextprotocol.io/sse" } ], "metadata": { "foo": "bar" }, "model": { "id": "claude-opus-5-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 } ``` ## Domain types ### Beta Managed Agents Advisor - `class BetaManagedAgentsAdvisor` - `"advisor" type` - `string model` The advisor model id. ### Beta Managed Agents Agent - `class BetaManagedAgentsAgent` - `"agent" type` - `string id` - `?\Datetime archivedAt` When the agent was archived. Null if not archived. - `\Datetime createdAt` A timestamp in RFC 3339 format - `?string description` - `BetaManagedAgentsExecutionIdentity executionIdentity` Execution principal for runs of this agent. Always present; `{"type": "service_account"}` when runs carry no customer-named principal. - `list mcpServers` - `array metadata` - `BetaManagedAgentsModelConfig model` Model identifier and configuration. - `?BetaManagedAgentsMultiagent multiagent` Multiagent orchestration configuration. Null when the agent is single-threaded. - `string name` - `list skills` - `?string system` - `list tools` - `\Datetime updatedAt` A timestamp in RFC 3339 format - `int version` The agent's current version. Starts at 1 and increments when the agent is modified. ### Beta Managed Agents Agent Reference - `class BetaManagedAgentsAgentReference` - `"agent" type` - `string id` - `int version` ### Beta Managed Agents Agent Tool Config - `class BetaManagedAgentsAgentToolConfig` - `class BetaManagedAgentsBashToolConfig` - `"bash" type` - `bool enabled` - `"bash" name` - `PermissionPolicy permissionPolicy` Permission policy for tool execution. - `class BetaManagedAgentsEditToolConfig` - `"edit" type` - `bool enabled` - `"edit" name` - `PermissionPolicy permissionPolicy` Permission policy for tool execution. - `class BetaManagedAgentsReadToolConfig` - `"read" type` - `bool enabled` - `"read" name` - `PermissionPolicy permissionPolicy` Permission policy for tool execution. - `class BetaManagedAgentsWriteToolConfig` - `"write" type` - `bool enabled` - `"write" name` - `PermissionPolicy permissionPolicy` Permission policy for tool execution. - `class BetaManagedAgentsGlobToolConfig` - `"glob" type` - `bool enabled` - `"glob" name` - `PermissionPolicy permissionPolicy` Permission policy for tool execution. - `class BetaManagedAgentsGrepToolConfig` - `"grep" type` - `bool enabled` - `"grep" name` - `PermissionPolicy permissionPolicy` Permission policy for tool execution. - `class BetaManagedAgentsWebFetchToolConfig` - `"web_fetch" type` - `bool enabled` - `"web_fetch" name` - `PermissionPolicy permissionPolicy` Permission policy for tool execution. - `?BetaManagedAgentsWebFetchURLSources urlSources` Which sources contribute URLs the tool may fetch, always in the object form. Null when not set, which allows every source. - `?list allowedDomains` - `?list blockedDomains` - `?int maxContentTokens` - `class BetaManagedAgentsWebSearchToolConfig` - `"web_search" type` - `bool enabled` - `"web_search" name` - `PermissionPolicy permissionPolicy` Permission policy for tool execution. - `?list allowedDomains` - `?list blockedDomains` - `?BetaManagedAgentsUserLocation userLocation` Approximate user location for search result localization. ### Beta Managed Agents Agent Tool Config Params - `class BetaManagedAgentsAgentToolConfigParams` - `class BetaManagedAgentsBashToolConfigParams` - `?Type type` - `"bash" name` Must be "bash". - `?bool enabled` Whether this tool is enabled and available to Claude. Overrides the default_config setting. - `?PermissionPolicy permissionPolicy` Permission policy for this tool. Controls whether tool calls are auto-approved or require confirmation. - `class BetaManagedAgentsEditToolConfigParams` - `?Type type` - `"edit" name` Must be "edit". - `?bool enabled` Whether this tool is enabled and available to Claude. Overrides the default_config setting. - `?PermissionPolicy permissionPolicy` Permission policy for this tool. Controls whether tool calls are auto-approved or require confirmation. - `class BetaManagedAgentsReadToolConfigParams` - `?Type type` - `"read" name` Must be "read". - `?bool enabled` Whether this tool is enabled and available to Claude. Overrides the default_config setting. - `?PermissionPolicy permissionPolicy` Permission policy for this tool. Controls whether tool calls are auto-approved or require confirmation. - `class BetaManagedAgentsWriteToolConfigParams` - `?Type type` - `"write" name` Must be "write". - `?bool enabled` Whether this tool is enabled and available to Claude. Overrides the default_config setting. - `?PermissionPolicy permissionPolicy` Permission policy for this tool. Controls whether tool calls are auto-approved or require confirmation. - `class BetaManagedAgentsGlobToolConfigParams` - `?Type type` - `"glob" name` Must be "glob". - `?bool enabled` Whether this tool is enabled and available to Claude. Overrides the default_config setting. - `?PermissionPolicy permissionPolicy` Permission policy for this tool. Controls whether tool calls are auto-approved or require confirmation. - `class BetaManagedAgentsGrepToolConfigParams` - `?Type type` - `"grep" name` Must be "grep". - `?bool enabled` Whether this tool is enabled and available to Claude. Overrides the default_config setting. - `?PermissionPolicy permissionPolicy` Permission policy for this tool. Controls whether tool calls are auto-approved or require confirmation. - `class BetaManagedAgentsWebFetchToolConfigParams` - `?Type type` - `"web_fetch" name` Must be "web_fetch". - `?list allowedDomains` Only 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. - `?list blockedDomains` Never 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. - `?bool enabled` Whether this tool is enabled and available to Claude. Overrides the default_config setting. - `?int maxContentTokens` Maximum number of tokens of fetched text content to include in context per call. Does not apply to binary content such as PDFs. - `?PermissionPolicy permissionPolicy` Permission policy for this tool. Controls whether tool calls are auto-approved or require confirmation. - `?BetaManagedAgentsWebFetchURLSourcesParams urlSources` Which sources contribute URLs the tool may fetch. Omit to allow every source. - `class BetaManagedAgentsWebSearchToolConfigParams` - `?Type type` - `"web_search" name` Must be "web_search". - `?list allowedDomains` Only 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. - `?list blockedDomains` Never 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. - `?bool enabled` Whether this tool is enabled and available to Claude. Overrides the default_config setting. - `?PermissionPolicy permissionPolicy` Permission policy for this tool. Controls whether tool calls are auto-approved or require confirmation. - `?BetaManagedAgentsUserLocation userLocation` Approximate user location for search result localization. ### Beta Managed Agents Agent Toolset Default Config - `class BetaManagedAgentsAgentToolsetDefaultConfig` - `bool enabled` - `PermissionPolicy permissionPolicy` Permission policy for tool execution. ### Beta Managed Agents Agent Toolset Default Config Params - `class BetaManagedAgentsAgentToolsetDefaultConfigParams` - `?bool enabled` Whether tools are enabled and available to Claude by default. Defaults to true if not specified. - `?PermissionPolicy permissionPolicy` Default permission policy for tools. Controls whether tool calls are auto-approved or require confirmation. ### Beta Managed Agents Agent Toolset20260401 - `class BetaManagedAgentsAgentToolset20260401` - `"agent_toolset_20260401" type` - `list configs` - `BetaManagedAgentsAgentToolsetDefaultConfig defaultConfig` Resolved default configuration for agent tools. ### Beta Managed Agents Agent Toolset20260401 Bash Input - `class BetaManagedAgentsAgentToolset20260401BashInput` - `?string command` Shell command to execute. Omit only when `restart` is true. - `?bool restart` When true, restart the persistent bash session instead of running a command. Subsequent calls without `restart` will run against the fresh session. - `?int timeoutMs` Per-call timeout in milliseconds. Defaults to the runner-wide tool timeout when omitted or zero. ### Beta Managed Agents Agent Toolset20260401 Edit Input - `class BetaManagedAgentsAgentToolset20260401EditInput` - `string filePath` Path of the file to edit. - `string newString` Replacement text. - `string oldString` Substring to find and replace. - `?bool replaceAll` When true, replace every occurrence of `old_string` instead of requiring a unique match. ### Beta Managed Agents Agent Toolset20260401 Glob Input - `class BetaManagedAgentsAgentToolset20260401GlobInput` - `string pattern` Doublestar glob pattern (e.g. `**/*.go`). Absolute patterns are only permitted when the runner is configured to allow them. - `?string path` Optional directory root to search under. Defaults to the runner's working directory. ### Beta Managed Agents Agent Toolset20260401 Grep Input - `class BetaManagedAgentsAgentToolset20260401GrepInput` - `string pattern` Regular expression to search for. - `?string path` Optional directory root to search under. Defaults to the runner's working directory. ### Beta Managed Agents Agent Toolset20260401 Params - `class BetaManagedAgentsAgentToolset20260401Params` - `"agent_toolset_20260401" type` - `?list configs` Per-tool configuration overrides. - `?BetaManagedAgentsAgentToolsetDefaultConfigParams defaultConfig` Default configuration applied to all tools in this set. ### Beta Managed Agents Agent Toolset20260401 Read Input - `class BetaManagedAgentsAgentToolset20260401ReadInput` - `string filePath` Path of the file to read. - `?list viewRange` 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". ### Beta Managed Agents Agent Toolset20260401 Write Input - `class BetaManagedAgentsAgentToolset20260401WriteInput` - `string content` Full file contents to write. - `string filePath` Path of the file to write. ### Beta Managed Agents Always Allow Policy - `class BetaManagedAgentsAlwaysAllowPolicy` - `"always_allow" type` ### Beta Managed Agents Always Ask Policy - `class BetaManagedAgentsAlwaysAskPolicy` - `"always_ask" type` ### Beta Managed Agents Anthropic Skill - `class BetaManagedAgentsAnthropicSkill` - `"anthropic" type` - `string skillID` - `string version` ### Beta Managed Agents Anthropic Skill Params - `class BetaManagedAgentsAnthropicSkillParams` - `"anthropic" type` - `string skillID` Identifier of the Anthropic skill (e.g., "xlsx"). - `?string version` Version to pin. Defaults to latest if omitted. ### Beta Managed Agents Auto Policy - `class BetaManagedAgentsAutoPolicy` - `"auto" type` ### Beta Managed Agents AWS Role Execution Identity - `class BetaManagedAgentsAWSRoleExecutionIdentity` - `"aws_role" type` - `string roleARN` The IAM role's ARN. ### Beta Managed Agents AWS Role Execution Identity Params - `class BetaManagedAgentsAWSRoleExecutionIdentityParams` - `"aws_role" type` - `string roleARN` The IAM role's ARN, e.g. "arn:aws:iam::123456789012:role/my-agent-runner". Maximum 2048 characters. ### Beta Managed Agents Bash Tool Config - `class BetaManagedAgentsBashToolConfig` - `"bash" type` - `bool enabled` - `"bash" name` - `PermissionPolicy permissionPolicy` Permission policy for tool execution. ### Beta Managed Agents Bash Tool Config Params - `class BetaManagedAgentsBashToolConfigParams` - `?Type type` - `"bash" name` Must be "bash". - `?bool enabled` Whether this tool is enabled and available to Claude. Overrides the default_config setting. - `?PermissionPolicy permissionPolicy` Permission policy for this tool. Controls whether tool calls are auto-approved or require confirmation. ### Beta Managed Agents Custom Skill - `class BetaManagedAgentsCustomSkill` - `"custom" type` - `string skillID` - `string version` ### Beta Managed Agents Custom Skill Params - `class BetaManagedAgentsCustomSkillParams` - `"custom" type` - `string skillID` Tagged ID of the custom skill (e.g., "skill_01XJ5..."). - `?string version` Version to pin. Defaults to latest if omitted. ### Beta Managed Agents Custom Tool - `class BetaManagedAgentsCustomTool` - `"custom" type` - `string description` - `BetaManagedAgentsCustomToolInputSchema inputSchema` JSON Schema for custom tool input parameters. - `string name` ### Beta Managed Agents Custom Tool Input Schema - `class BetaManagedAgentsCustomToolInputSchema` - `"object" type` - `?array properties` - `?list required` ### Beta Managed Agents Custom Tool Params - `class BetaManagedAgentsCustomToolParams` - `"custom" type` - `string description` Description of what the tool does, shown to the agent to help it decide when to use the tool. - `BetaManagedAgentsCustomToolInputSchema inputSchema` JSON Schema defining the expected input parameters for the tool. - `string name` Unique name for the tool. 1-128 characters; letters, digits, underscores, and hyphens. ### Beta Managed Agents Edit Tool Config - `class BetaManagedAgentsEditToolConfig` - `"edit" type` - `bool enabled` - `"edit" name` - `PermissionPolicy permissionPolicy` Permission policy for tool execution. ### Beta Managed Agents Edit Tool Config Params - `class BetaManagedAgentsEditToolConfigParams` - `?Type type` - `"edit" name` Must be "edit". - `?bool enabled` Whether this tool is enabled and available to Claude. Overrides the default_config setting. - `?PermissionPolicy permissionPolicy` Permission policy for this tool. Controls whether tool calls are auto-approved or require confirmation. ### Beta Managed Agents Effort High - `class BetaManagedAgentsEffortHigh` - `"high" type` ### Beta Managed Agents Effort Low - `class BetaManagedAgentsEffortLow` - `"low" type` ### Beta Managed Agents Effort Max - `class BetaManagedAgentsEffortMax` - `"max" type` ### Beta Managed Agents Effort Medium - `class BetaManagedAgentsEffortMedium` - `"medium" type` ### Beta Managed Agents Effort Xhigh - `class BetaManagedAgentsEffortXhigh` - `"xhigh" type` ### Beta Managed Agents Execution Identity - `class BetaManagedAgentsExecutionIdentity` - `class BetaManagedAgentsAWSRoleExecutionIdentity` - `"aws_role" type` - `string roleARN` The IAM role's ARN. - `class BetaManagedAgentsServiceAccountExecutionIdentity` - `"service_account" type` ### Beta Managed Agents Execution Identity Params - `class BetaManagedAgentsExecutionIdentityParams` - `class BetaManagedAgentsAWSRoleExecutionIdentityParams` - `"aws_role" type` - `string roleARN` The IAM role's ARN, e.g. "arn:aws:iam::123456789012:role/my-agent-runner". Maximum 2048 characters. - `class BetaManagedAgentsServiceAccountExecutionIdentityParams` - `"service_account" type` ### Beta Managed Agents Glob Tool Config - `class BetaManagedAgentsGlobToolConfig` - `"glob" type` - `bool enabled` - `"glob" name` - `PermissionPolicy permissionPolicy` Permission policy for tool execution. ### Beta Managed Agents Glob Tool Config Params - `class BetaManagedAgentsGlobToolConfigParams` - `?Type type` - `"glob" name` Must be "glob". - `?bool enabled` Whether this tool is enabled and available to Claude. Overrides the default_config setting. - `?PermissionPolicy permissionPolicy` Permission policy for this tool. Controls whether tool calls are auto-approved or require confirmation. ### Beta Managed Agents Grep Tool Config - `class BetaManagedAgentsGrepToolConfig` - `"grep" type` - `bool enabled` - `"grep" name` - `PermissionPolicy permissionPolicy` Permission policy for tool execution. ### Beta Managed Agents Grep Tool Config Params - `class BetaManagedAgentsGrepToolConfigParams` - `?Type type` - `"grep" name` Must be "grep". - `?bool enabled` Whether this tool is enabled and available to Claude. Overrides the default_config setting. - `?PermissionPolicy permissionPolicy` Permission policy for this tool. Controls whether tool calls are auto-approved or require confirmation. ### Beta Managed Agents MCP Server URL Definition - `class BetaManagedAgentsMCPServerURLDefinition` - `"url" type` - `string name` - `string url` ### Beta Managed Agents MCP Tool Config - `class BetaManagedAgentsMCPToolConfig` - `bool enabled` - `string name` - `PermissionPolicy permissionPolicy` Permission policy for tool execution. ### Beta Managed Agents MCP Tool Config Params - `class BetaManagedAgentsMCPToolConfigParams` - `string name` Name of the MCP tool to configure. 1-128 characters. - `?bool enabled` Whether this tool is enabled. Overrides the `default_config` setting. - `?PermissionPolicy permissionPolicy` Permission policy for this tool. Overrides the `default_config` setting. ### Beta Managed Agents MCP Toolset - `class BetaManagedAgentsMCPToolset` - `"mcp_toolset" type` - `list configs` - `BetaManagedAgentsMCPToolsetDefaultConfig defaultConfig` Resolved default configuration for all tools from an MCP server. - `string mcpServerName` ### Beta Managed Agents MCP Toolset Default Config - `class BetaManagedAgentsMCPToolsetDefaultConfig` - `bool enabled` - `PermissionPolicy permissionPolicy` Permission policy for tool execution. ### Beta Managed Agents MCP Toolset Default Config Params - `class BetaManagedAgentsMCPToolsetDefaultConfigParams` - `?bool enabled` Whether tools are enabled by default. Defaults to true if not specified. - `?PermissionPolicy permissionPolicy` Default permission policy for tools from this server. ### Beta Managed Agents MCP Toolset Params - `class BetaManagedAgentsMCPToolsetParams` - `"mcp_toolset" type` - `string mcpServerName` Name of the MCP server. Must match a server name from the mcp_servers array. 1-255 characters. - `?list configs` Per-tool configuration overrides. - `?BetaManagedAgentsMCPToolsetDefaultConfigParams defaultConfig` Default configuration for all tools from this server. ### Beta Managed Agents Model - `enum BetaManagedAgentsModel` - `"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 - `string` ### Beta Managed Agents Model Config - `class BetaManagedAgentsModelConfig` - `BetaManagedAgentsModel id` The model that will power your agent. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - `?Effort 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. - `?string inferenceGeo` Geographic region for model inference. When unset, requests fall through to the workspace's default_inference_geo. - `?Speed speed` 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. ### Beta Managed Agents Model Config Params - `class BetaManagedAgentsModelConfigParams` - `BetaManagedAgentsModel id` The model that will power your agent. See [models](https://docs.anthropic.com/en/docs/models-overview) for additional details and options. - `?Effort effort` How 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. - `?string inferenceGeo` Geographic region for model inference. When unset, requests fall through to the workspace's default_inference_geo. On update, `model` is whole-object replacement — omitting inference_geo clears it. - `?Speed speed` 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. ### Beta Managed Agents Multiagent Advisor - `class BetaManagedAgentsMultiagentAdvisor` - `class BetaManagedAgentsMultiagentAdvisorEnabled` - `"enabled" type` - `string model` The advisor model id. - `class BetaManagedAgentsMultiagentAdvisorDisabled` - `"disabled" type` ### Beta Managed Agents Multiagent Advisor Disabled - `class BetaManagedAgentsMultiagentAdvisorDisabled` - `"disabled" type` ### Beta Managed Agents Multiagent Advisor Disabled Params - `class BetaManagedAgentsMultiagentAdvisorDisabledParams` - `"disabled" type` ### Beta Managed Agents Multiagent Advisor Enabled - `class BetaManagedAgentsMultiagentAdvisorEnabled` - `"enabled" type` - `string model` The advisor model id. ### Beta Managed Agents Multiagent Advisor Enabled Params - `class BetaManagedAgentsMultiagentAdvisorEnabledParams` - `"enabled" type` - `string model` A Claude model id. The model must be permitted as an advisor for this agent's model. ### Beta Managed Agents Multiagent Advisor Params - `class BetaManagedAgentsMultiagentAdvisorParams` - `class BetaManagedAgentsMultiagentAdvisorEnabledParams` - `"enabled" type` - `string model` A Claude model id. The model must be permitted as an advisor for this agent's model. - `class BetaManagedAgentsMultiagentAdvisorDisabledParams` - `"disabled" type` ### Beta Managed Agents Multiagent Coordinator - `class BetaManagedAgentsMultiagentCoordinator` - `"coordinator" type` - `list agents` Agents the coordinator may spawn as session threads, each resolved to a specific version. ### Beta Managed Agents Multiagent Coordinator Params - `class BetaManagedAgentsMultiagentCoordinatorParams` - `"coordinator" type` - `list agents` Agents the coordinator may spawn as session threads. 1–20 entries. Each entry is an agent ID string, a versioned `{"type":"agent","id","version"}` reference, or `{"type":"self"}` to allow recursive self-invocation. Entries must reference distinct agents (after resolving `self` and string forms); at most one `self`. Referenced agents must exist, must not be archived, and must not themselves have `multiagent` set (depth limit 1). ### Beta Managed Agents Multiagent Inline Agents - `class BetaManagedAgentsMultiagentInlineAgents` - `class BetaManagedAgentsMultiagentInlineAgentsEnabled` - `"enabled" type` - `class BetaManagedAgentsMultiagentInlineAgentsDisabled` - `"disabled" type` ### Beta Managed Agents Multiagent Inline Agents Disabled - `class BetaManagedAgentsMultiagentInlineAgentsDisabled` - `"disabled" type` ### Beta Managed Agents Multiagent Inline Agents Disabled Params - `class BetaManagedAgentsMultiagentInlineAgentsDisabledParams` - `"disabled" type` ### Beta Managed Agents Multiagent Inline Agents Enabled - `class BetaManagedAgentsMultiagentInlineAgentsEnabled` - `"enabled" type` ### Beta Managed Agents Multiagent Inline Agents Enabled Params - `class BetaManagedAgentsMultiagentInlineAgentsEnabledParams` - `"enabled" type` ### Beta Managed Agents Multiagent Inline Agents Params - `class BetaManagedAgentsMultiagentInlineAgentsParams` - `class BetaManagedAgentsMultiagentInlineAgentsEnabledParams` - `"enabled" type` - `class BetaManagedAgentsMultiagentInlineAgentsDisabledParams` - `"disabled" type` ### Beta Managed Agents Multiagent Predefined Agent Params - `class BetaManagedAgentsMultiagentPredefinedAgentParams` - `string` - `class BetaManagedAgentsAgentParams` - `"agent" type` - `string id` The `agent` ID. - `?int version` The specific `agent` version to use. Omit to use the latest version. Must be at least 1 if specified. - `class BetaManagedAgentsMultiagentSelfParams` - `"self" type` ### Beta Managed Agents Multiagent Self Params - `class BetaManagedAgentsMultiagentSelfParams` - `"self" type` ### Beta Managed Agents Multiagent Subagents - `class BetaManagedAgentsMultiagentSubagents` - `class BetaManagedAgentsMultiagentSubagentsEnabled` - `"enabled" type` - `BetaManagedAgentsMultiagentInlineAgents inlineAgents` Whether the agent can define inline agents, which are not saved, when it spawns session threads. - `list predefinedAgents` Predefined agents, which are saved agents that this agent can spawn as session threads, each resolved to a specific version. - `class BetaManagedAgentsMultiagentSubagentsDisabled` - `"disabled" type` ### Beta Managed Agents Multiagent Subagents Disabled - `class BetaManagedAgentsMultiagentSubagentsDisabled` - `"disabled" type` ### Beta Managed Agents Multiagent Subagents Disabled Params - `class BetaManagedAgentsMultiagentSubagentsDisabledParams` - `"disabled" type` ### Beta Managed Agents Multiagent Subagents Enabled - `class BetaManagedAgentsMultiagentSubagentsEnabled` - `"enabled" type` - `BetaManagedAgentsMultiagentInlineAgents inlineAgents` Whether the agent can define inline agents, which are not saved, when it spawns session threads. - `list predefinedAgents` Predefined agents, which are saved agents that this agent can spawn as session threads, each resolved to a specific version. ### Beta Managed Agents Multiagent Subagents Enabled Params - `class BetaManagedAgentsMultiagentSubagentsEnabledParams` - `"enabled" type` - `?BetaManagedAgentsMultiagentInlineAgentsParams inlineAgents` Whether the agent can define inline agents when it spawns session threads. Defaults to enabled. - `?list predefinedAgents` Predefined agents that this agent can spawn as session threads. At most 20. Defaults to null. Null and an empty list both mean no predefined agents. This list is separate from `workflows.predefined_agents`, and an agent in one list is not added to the other. ### Beta Managed Agents Multiagent Subagents Params - `class BetaManagedAgentsMultiagentSubagentsParams` - `class BetaManagedAgentsMultiagentSubagentsEnabledParams` - `"enabled" type` - `?BetaManagedAgentsMultiagentInlineAgentsParams inlineAgents` Whether the agent can define inline agents when it spawns session threads. Defaults to enabled. - `?list predefinedAgents` Predefined agents that this agent can spawn as session threads. At most 20. Defaults to null. Null and an empty list both mean no predefined agents. This list is separate from `workflows.predefined_agents`, and an agent in one list is not added to the other. - `class BetaManagedAgentsMultiagentSubagentsDisabledParams` - `"disabled" type` ### Beta Managed Agents Multiagent Workflows - `class BetaManagedAgentsMultiagentWorkflows` - `class BetaManagedAgentsMultiagentWorkflowsEnabled` - `"enabled" type` - `BetaManagedAgentsMultiagentInlineAgents inlineAgents` Whether a run's plan can define inline agents, which are not saved. - `list predefinedAgents` Predefined agents, which are saved agents that a run's plan can use, each resolved to a specific version. - `class BetaManagedAgentsMultiagentWorkflowsDisabled` - `"disabled" type` ### Beta Managed Agents Multiagent Workflows Disabled - `class BetaManagedAgentsMultiagentWorkflowsDisabled` - `"disabled" type` ### Beta Managed Agents Multiagent Workflows Disabled Params - `class BetaManagedAgentsMultiagentWorkflowsDisabledParams` - `"disabled" type` ### Beta Managed Agents Multiagent Workflows Enabled - `class BetaManagedAgentsMultiagentWorkflowsEnabled` - `"enabled" type` - `BetaManagedAgentsMultiagentInlineAgents inlineAgents` Whether a run's plan can define inline agents, which are not saved. - `list predefinedAgents` Predefined agents, which are saved agents that a run's plan can use, each resolved to a specific version. ### Beta Managed Agents Multiagent Workflows Enabled Params - `class BetaManagedAgentsMultiagentWorkflowsEnabledParams` - `"enabled" type` - `?BetaManagedAgentsMultiagentInlineAgentsParams inlineAgents` Whether a run's plan can define inline agents. Defaults to enabled. - `?list predefinedAgents` Predefined agents that a run's plan can use. At most 20. Defaults to null. Null and an empty list both mean no predefined agents. This list is separate from `subagents.predefined_agents`, and an agent in one list is not added to the other. ### Beta Managed Agents Multiagent Workflows Params - `class BetaManagedAgentsMultiagentWorkflowsParams` - `class BetaManagedAgentsMultiagentWorkflowsEnabledParams` - `"enabled" type` - `?BetaManagedAgentsMultiagentInlineAgentsParams inlineAgents` Whether a run's plan can define inline agents. Defaults to enabled. - `?list predefinedAgents` Predefined agents that a run's plan can use. At most 20. Defaults to null. Null and an empty list both mean no predefined agents. This list is separate from `subagents.predefined_agents`, and an agent in one list is not added to the other. - `class BetaManagedAgentsMultiagentWorkflowsDisabledParams` - `"disabled" type` ### Beta Managed Agents Multiagent20261001 - `class BetaManagedAgentsMultiagent20261001` - `"multiagent_20261001" type` - `BetaManagedAgentsMultiagentAdvisor advisor` Whether the session's primary thread can consult an advisor model. - `BetaManagedAgentsMultiagentSubagents subagents` Whether the agent can spawn session threads. - `BetaManagedAgentsMultiagentWorkflows workflows` Whether the agent can start workflow runs. ### Beta Managed Agents Multiagent20261001 Params - `class BetaManagedAgentsMultiagent20261001Params` - `"multiagent_20261001" type` - `?BetaManagedAgentsMultiagentAdvisorParams advisor` Whether the session's primary thread can consult an advisor model. Defaults to disabled. - `?BetaManagedAgentsMultiagentSubagentsParams subagents` Whether the agent can spawn session threads. Defaults to enabled. - `?BetaManagedAgentsMultiagentWorkflowsParams workflows` Whether the agent can start workflow runs. Defaults to enabled. ### Beta Managed Agents Read Tool Config - `class BetaManagedAgentsReadToolConfig` - `"read" type` - `bool enabled` - `"read" name` - `PermissionPolicy permissionPolicy` Permission policy for tool execution. ### Beta Managed Agents Read Tool Config Params - `class BetaManagedAgentsReadToolConfigParams` - `?Type type` - `"read" name` Must be "read". - `?bool enabled` Whether this tool is enabled and available to Claude. Overrides the default_config setting. - `?PermissionPolicy permissionPolicy` Permission policy for this tool. Controls whether tool calls are auto-approved or require confirmation. ### Beta Managed Agents Service Account Execution Identity - `class BetaManagedAgentsServiceAccountExecutionIdentity` - `"service_account" type` ### Beta Managed Agents Service Account Execution Identity Params - `class BetaManagedAgentsServiceAccountExecutionIdentityParams` - `"service_account" type` ### Beta Managed Agents Session Thread Agent - `class BetaManagedAgentsSessionThreadAgent` - `"agent" type` - `string id` - `?string description` - `BetaManagedAgentsExecutionIdentity executionIdentity` Execution principal snapshotted from the agent at session creation. Always present; `{"type": "service_account"}` when runs carry no customer-named principal. - `list mcpServers` - `BetaManagedAgentsModelConfig model` Model identifier and configuration. - `string name` - `list skills` - `?string system` - `list tools` - `int version` ### Beta Managed Agents Skill Params - `class BetaManagedAgentsSkillParams` - `class BetaManagedAgentsAnthropicSkillParams` - `"anthropic" type` - `string skillID` Identifier of the Anthropic skill (e.g., "xlsx"). - `?string version` Version to pin. Defaults to latest if omitted. - `class BetaManagedAgentsCustomSkillParams` - `"custom" type` - `string skillID` Tagged ID of the custom skill (e.g., "skill_01XJ5..."). - `?string version` Version to pin. Defaults to latest if omitted. ### Beta Managed Agents URL MCP Server Params - `class BetaManagedAgentsURLMCPServerParams` - `"url" type` - `string name` Unique name for this server, referenced by mcp_toolset configurations. 1-255 characters. - `string url` Endpoint URL for the MCP server. ### Beta Managed Agents User Location - `class BetaManagedAgentsUserLocation` - `"approximate" type` Location precision. Only "approximate" is supported. - `?string city` City name. - `?string country` Two-letter ISO 3166-1 country code, uppercase. - `?string region` Region or state name. - `?string timezone` IANA timezone identifier, e.g. "America/Los_Angeles". ### Beta Managed Agents Web Fetch Tool Config - `class BetaManagedAgentsWebFetchToolConfig` - `"web_fetch" type` - `bool enabled` - `"web_fetch" name` - `PermissionPolicy permissionPolicy` Permission policy for tool execution. - `?BetaManagedAgentsWebFetchURLSources urlSources` Which sources contribute URLs the tool may fetch, always in the object form. Null when not set, which allows every source. - `?list allowedDomains` - `?list blockedDomains` - `?int maxContentTokens` ### Beta Managed Agents Web Fetch Tool Config Params - `class BetaManagedAgentsWebFetchToolConfigParams` - `?Type type` - `"web_fetch" name` Must be "web_fetch". - `?list allowedDomains` Only 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. - `?list blockedDomains` Never 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. - `?bool enabled` Whether this tool is enabled and available to Claude. Overrides the default_config setting. - `?int maxContentTokens` Maximum number of tokens of fetched text content to include in context per call. Does not apply to binary content such as PDFs. - `?PermissionPolicy permissionPolicy` Permission policy for this tool. Controls whether tool calls are auto-approved or require confirmation. - `?BetaManagedAgentsWebFetchURLSourcesParams urlSources` Which sources contribute URLs the tool may fetch. Omit to allow every source. ### Beta Managed Agents Web Fetch URL Source All - `class BetaManagedAgentsWebFetchURLSourceAll` - `"all" type` ### Beta Managed Agents Web Fetch URL Source Except - `class BetaManagedAgentsWebFetchURLSourceExcept` - `"except" type` - `list tools` 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. ### Beta Managed Agents Web Fetch URL Source None - `class BetaManagedAgentsWebFetchURLSourceNone` - `"none" type` ### Beta Managed Agents Web Fetch URL Source Only - `class BetaManagedAgentsWebFetchURLSourceOnly` - `"only" type` - `list tools` 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. ### Beta Managed Agents Web Fetch URL Source Shorthand - `enum BetaManagedAgentsWebFetchURLSourceShorthand` - `"all"` - `"none"` ### Beta Managed Agents Web Fetch URL Source Tool Filter - `class BetaManagedAgentsWebFetchURLSourceToolFilter` - `class BetaManagedAgentsWebFetchURLSourceAll` - `"all" type` - `class BetaManagedAgentsWebFetchURLSourceNone` - `"none" type` - `class BetaManagedAgentsWebFetchURLSourceOnly` - `"only" type` - `list tools` 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. - `class BetaManagedAgentsWebFetchURLSourceExcept` - `"except" type` - `list tools` 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. ### Beta Managed Agents Web Fetch URL Source Tool Filter Params - `class BetaManagedAgentsWebFetchURLSourceToolFilterParams` - `enum BetaManagedAgentsWebFetchURLSourceShorthand` - `"all"` - `"none"` - `class BetaManagedAgentsWebFetchURLSourceToolFilter` - `class BetaManagedAgentsWebFetchURLSourceAll` - `"all" type` - `class BetaManagedAgentsWebFetchURLSourceNone` - `"none" type` - `class BetaManagedAgentsWebFetchURLSourceOnly` - `"only" type` - `list tools` 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. - `class BetaManagedAgentsWebFetchURLSourceExcept` - `"except" type` - `list tools` 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. ### Beta Managed Agents Web Fetch URL Source Tool Reference - `class BetaManagedAgentsWebFetchURLSourceToolReference` - `"tool_reference" type` Must be "tool_reference". - `string name` Name of the tool. Compared exactly, so upper and lower case letters are different. ### Beta Managed Agents Web Fetch URL Source User Input - `class BetaManagedAgentsWebFetchURLSourceUserInput` - `class BetaManagedAgentsWebFetchURLSourceAll` - `"all" type` - `class BetaManagedAgentsWebFetchURLSourceNone` - `"none" type` ### Beta Managed Agents Web Fetch URL Source User Input Params - `class BetaManagedAgentsWebFetchURLSourceUserInputParams` - `enum BetaManagedAgentsWebFetchURLSourceShorthand` - `"all"` - `"none"` - `class BetaManagedAgentsWebFetchURLSourceUserInput` - `class BetaManagedAgentsWebFetchURLSourceAll` - `"all" type` - `class BetaManagedAgentsWebFetchURLSourceNone` - `"none" type` ### Beta Managed Agents Web Fetch URL Sources - `class BetaManagedAgentsWebFetchURLSources` - `?BetaManagedAgentsWebFetchURLSourceToolFilter clientToolResults` Which custom tools' results contribute URLs that may be fetched. Null when not set, which allows every custom tool's results. - `?BetaManagedAgentsWebFetchURLSourceToolFilter serverToolResults` Which of the web_search and web_fetch tools' results contribute URLs that may be fetched. Null when not set, which allows both. - `?BetaManagedAgentsWebFetchURLSourceUserInput userInput` Whether URLs in the text of user messages may be fetched. Null when not set, which allows them. ### Beta Managed Agents Web Fetch URL Sources Params - `class BetaManagedAgentsWebFetchURLSourcesParams` - `?BetaManagedAgentsWebFetchURLSourceToolFilterParams clientToolResults` Which custom tools' results contribute URLs that may be fetched: "all" (the default), "none", or an only or except list. Each name in a list must be a custom tool in the same tools array. - `?BetaManagedAgentsWebFetchURLSourceToolFilterParams serverToolResults` Which of the web_search and web_fetch tools' results contribute URLs that may be fetched: "all" (the default), "none", or an only or except list. Each name in a list must be "web_search" or "web_fetch". - `?BetaManagedAgentsWebFetchURLSourceUserInputParams userInput` Whether URLs in the text of user messages may be fetched: "all" (the default) or "none". ### Beta Managed Agents Web Search Tool Config - `class BetaManagedAgentsWebSearchToolConfig` - `"web_search" type` - `bool enabled` - `"web_search" name` - `PermissionPolicy permissionPolicy` Permission policy for tool execution. - `?list allowedDomains` - `?list blockedDomains` - `?BetaManagedAgentsUserLocation userLocation` Approximate user location for search result localization. ### Beta Managed Agents Web Search Tool Config Params - `class BetaManagedAgentsWebSearchToolConfigParams` - `?Type type` - `"web_search" name` Must be "web_search". - `?list allowedDomains` Only 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. - `?list blockedDomains` Never 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. - `?bool enabled` Whether this tool is enabled and available to Claude. Overrides the default_config setting. - `?PermissionPolicy permissionPolicy` Permission policy for this tool. Controls whether tool calls are auto-approved or require confirmation. - `?BetaManagedAgentsUserLocation userLocation` Approximate user location for search result localization. ### Beta Managed Agents Write Tool Config - `class BetaManagedAgentsWriteToolConfig` - `"write" type` - `bool enabled` - `"write" name` - `PermissionPolicy permissionPolicy` Permission policy for tool execution. ### Beta Managed Agents Write Tool Config Params - `class BetaManagedAgentsWriteToolConfigParams` - `?Type type` - `"write" name` Must be "write". - `?bool enabled` Whether this tool is enabled and available to Claude. Overrides the default_config setting. - `?PermissionPolicy permissionPolicy` Permission policy for this tool. Controls whether tool calls are auto-approved or require confirmation. ## Agents › Versions ### List Agent Versions `$client->beta->agents->versions->list(string agentID, ?int limit, ?string page, ?list betas, ?string workspaceID): PageCursor` **GET** `/v1/agents/{agent_id}/versions` List Agent Versions #### Parameters - `agentID: string` (path parameter) Agent ID to list versions for. - `limit?: optional int` (query parameter) Maximum results per page. Default 20, maximum 100. - `page?: optional string` (query parameter) Opaque pagination cursor. - `betas?: optional list` (header parameter) This endpoint is in beta: requests must send `managed-agents-2026-04-01` in this header. - `workspaceID?: optional string` (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` - `"agent" type` - `string id` - `?\Datetime archivedAt` When the agent was archived. Null if not archived. - `\Datetime createdAt` A timestamp in RFC 3339 format - `?string description` - `BetaManagedAgentsExecutionIdentity executionIdentity` Execution principal for runs of this agent. Always present; `{"type": "service_account"}` when runs carry no customer-named principal. - `list mcpServers` - `array metadata` - `BetaManagedAgentsModelConfig model` Model identifier and configuration. - `?BetaManagedAgentsMultiagent multiagent` Multiagent orchestration configuration. Null when the agent is single-threaded. - `string name` - `list skills` - `?string system` - `list tools` - `\Datetime updatedAt` A timestamp in RFC 3339 format - `int version` The agent's current version. Starts at 1 and increments when the agent is modified. #### Example ```php beta->agents->versions->list( 'agent_011CZkYpogX7uDKUyvBTophP', limit: 0, page: 'page', betas: [AnthropicBeta::MESSAGE_BATCHES_2024_09_24], workspaceID: 'wrkspc_011CZkZaBF1tNoB5wlCeusgy', ); var_dump($page); ``` ##### Response (200) ```json { "data": [ { "id": "agent_011CZkYpogX7uDKUyvBTophP", "archived_at": null, "created_at": "2026-03-15T10:00:00Z", "description": "A general-purpose starter agent.", "execution_identity": { "type": "service_account" }, "mcp_servers": [ { "name": "example-mcp", "type": "url", "url": "https://example-server.modelcontextprotocol.io/sse" } ], "metadata": { "foo": "bar" }, "model": { "id": "claude-opus-5-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" } ```