Claude Platform Docs

Create Agent

beta.agents.create(**kwargs) -> BetaManagedAgentsAgent
POST/v1/agents

Create Agent

Parameters
model: BetaManagedAgentsModel | BetaManagedAgentsModelConfigParams { id, effort, inference_geo, speed }

Model identifier. Accepts the model string, e.g. claude-opus-5, or a model_config object for additional configuration control

One of the following:
BetaManagedAgentsModel = :"claude-sonnet-5" | :"claude-fable-5" | :"claude-opus-5" | 10 more | String

The model that will power your agent.

See models for additional details and options.

One of the following:
class BetaManagedAgentsModelConfigParams { id, effort, inference_geo, speed }

An object that defines additional configuration control over model use

name: String

Human-readable name for the agent.

minLength1
maxLength256
description: String

Description of what the agent does.

maxLength2048
mcp_servers: Array[BetaManagedAgentsURLMCPServerParams { name, type, url }]

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.

name: String

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

minLength1
maxLength255
type: :url
url: String

Endpoint URL for the MCP server.

maxLength2048
metadata: Hash[Symbol, String]

Arbitrary key-value metadata. Maximum 16 pairs, keys up to 64 chars, values up to 512 chars.

multiagent: BetaManagedAgentsMultiagentParams { agents, type }

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

skills: Array[BetaManagedAgentsSkillParams]

Skills available to the agent.

One of the following:
class BetaManagedAgentsAnthropicSkillParams { skill_id, type, version }

An Anthropic-managed skill.

skill_id: String

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

minLength1
maxLength64
type: :anthropic
version: String

Version to pin. Defaults to latest if omitted.

minLength1
maxLength64
class BetaManagedAgentsCustomSkillParams { skill_id, type, version }

A user-created custom skill.

skill_id: String

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

minLength1
maxLength64
type: :custom
version: String

Version to pin. Defaults to latest if omitted.

minLength1
maxLength64
system_: String

System prompt for the agent.

maxLength100000
tools: Array[BetaManagedAgentsAgentToolset20260401Params { type, configs, default_config } | BetaManagedAgentsMCPToolsetParams { mcp_server_name, type, configs, default_config } | BetaManagedAgentsCustomToolParams { description, input_schema, name, type }]

Tool configurations available to the agent. Maximum of 128 tools across all toolsets allowed.

One of the following:
class BetaManagedAgentsAgentToolset20260401Params { type, configs, default_config }

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

class BetaManagedAgentsMCPToolsetParams { mcp_server_name, type, configs, default_config }

Configuration for tools from an MCP server defined in mcp_servers.

class BetaManagedAgentsCustomToolParams { description, input_schema, name, type }

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

description: String

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

minLength1
input_schema: BetaManagedAgentsCustomToolInputSchema { type, properties, required }

JSON Schema for custom tool input parameters.

type: :object
properties: Hash[Symbol, untyped]
required: Array[String]
name: String

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

minLength1
maxLength128
type: :custom
betas: Array[AnthropicBeta]

Optional header to specify the beta version(s) you want to use.

One of the following:
String = String
AnthropicBeta = :"message-batches-2024-09-24" | :"prompt-caching-2024-07-31" | :"computer-use-2024-10-22" | 38 more
One of the following:
:"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"
:"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"
Returns
class BetaManagedAgentsAgent { id, archived_at, created_at, 12 more }

A Managed Agents agent.

Create Agent

require "anthropic"

anthropic = Anthropic::Client.new(api_key: "my-anthropic-api-key")

beta_managed_agents_agent = anthropic.beta.agents.create(
  model: Anthropic::Beta::BetaManagedAgentsModel::CLAUDE_OPUS_5,
  name: "My First Agent"
)

puts(beta_managed_agents_agent)
{
  "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": {
    "agents": [
      {
        "id": "agent_011CZkYqphY8vELVzwCUpqiQ",
        "type": "agent",
        "version": 1
      }
    ],
    "type": "coordinator"
  },
  "name": "My First Agent",
  "skills": [
    {
      "skill_id": "xlsx",
      "type": "anthropic",
      "version": "1"
    },
    {
      "skill_id": "skill_011CZkZFNu9hAbo3jZPRgTlx",
      "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
}
Returns Examples
{
  "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": {
    "agents": [
      {
        "id": "agent_011CZkYqphY8vELVzwCUpqiQ",
        "type": "agent",
        "version": 1
      }
    ],
    "type": "coordinator"
  },
  "name": "My First Agent",
  "skills": [
    {
      "skill_id": "xlsx",
      "type": "anthropic",
      "version": "1"
    },
    {
      "skill_id": "skill_011CZkZFNu9hAbo3jZPRgTlx",
      "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
}