Sign in

v49

latestOpenAPI 3.1.0raw.githubusercontent.com2026-07-261319281.7 MB

Create Agent

post/v1/agents?beta=true

Headers

anthropic-versionstring
anthropic-betastring

Request body

namestring required

Human-readable name for the agent.

descriptionstring nullable

Description of what the agent does.

systemstring nullable

System prompt for the agent.

metadataobject

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

Example request

{
  "name": "My First Agent",
  "model": "claude-sonnet-4-6",
  "description": "A general-purpose starter agent.",
  "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"
    }
  ],
  "metadata": {
    "foo": "bar"
  }
}

Response

Successful response (OK)

type'agent' required
idstring required
versioninteger required

The agent's current version. Starts at 1 and increments when the agent is modified.

namestring required
descriptionstring nullable required
systemstring nullable required
metadataobject required
created_atstring date-time required

A timestamp in RFC 3339 format

updated_atstring date-time required

A timestamp in RFC 3339 format

archived_atstring date-time required

A timestamp in RFC 3339 format

Example response

{
  "type": "agent",
  "id": "agent_011CZkYpogX7uDKUyvBTophP",
  "version": 1,
  "name": "My First Agent",
  "description": "A general-purpose starter agent.",
  "model": {
    "id": "claude-sonnet-4-6",
    "speed": "standard"
  },
  "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",
      "default_config": {
        "enabled": true,
        "permission_policy": {
          "type": "always_ask"
        }
      },
      "configs": []
    }
  ],
  "mcp_servers": [
    {
      "type": "url",
      "name": "example-mcp",
      "url": "https://example-server.modelcontextprotocol.io/sse"
    }
  ],
  "skills": [
    {
      "type": "anthropic",
      "skill_id": "xlsx",
      "version": "1"
    },
    {
      "type": "custom",
      "skill_id": "skill_011CZkZFNu9hAbo3jZPRgTlx",
      "version": "2"
    }
  ],
  "multiagent": null,
  "metadata": {
    "foo": "bar"
  },
  "created_at": "2026-03-15T10:00:00Z",
  "updated_at": "2026-03-15T10:00:00Z",
  "archived_at": null
}