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-opus-5",
  "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-opus-5",
    "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
}

Changes

Changed in 13 of the 67 revisions of this API.321157

Aug 19, 20260042750ea1ee433See the full diff
- ▲
  added BetaManagedAgentsBashToolConfig BetaManagedAgentsEditToolConfig BetaManagedAgentsReadToolConfig BetaManagedAgentsWriteToolConfig BetaManagedAgentsGlobToolConfig BetaManagedAgentsGrepToolConfig BetaManagedAgentsWebFetchToolConfig BetaManagedAgentsWebSearchToolConfig to the tools/items/oneOf[BetaManagedAgentsAgentToolset20260401]/configs/items/ response property oneOf list for the response status 200
  response-property-one-of-added
- ▲
  removed the required property tools/items/oneOf[BetaManagedAgentsAgentToolset20260401]/configs/items/enabled from the response with the 200 status
  response-required-property-removed
- ▲
  removed the required property tools/items/oneOf[BetaManagedAgentsAgentToolset20260401]/configs/items/name from the response with the 200 status
  response-required-property-removed
- ▲
  removed the required property tools/items/oneOf[BetaManagedAgentsAgentToolset20260401]/configs/items/permission_policy from the response with the 200 status
  response-required-property-removed
- ●
  removed the request property tools/items/oneOf[BetaManagedAgentsAgentToolset20260401Params]/configs/items/enabled
  request-property-removed
- ●
  removed the request property tools/items/oneOf[BetaManagedAgentsAgentToolset20260401Params]/configs/items/name
  request-property-removed
- ●
  removed the request property tools/items/oneOf[BetaManagedAgentsAgentToolset20260401Params]/configs/items/permission_policy
  request-property-removed
- ○
  added discriminator to tools/items/oneOf[BetaManagedAgentsAgentToolset20260401Params]/configs/items/ request property
  request-property-discriminator-added
- ○
  added BetaManagedAgentsBashToolConfigParams BetaManagedAgentsEditToolConfigParams BetaManagedAgentsReadToolConfigParams BetaManagedAgentsWriteToolConfigParams BetaManagedAgentsGlobToolConfigParams BetaManagedAgentsGrepToolConfigParams BetaManagedAgentsWebFetchToolConfigParams BetaManagedAgentsWebSearchToolConfigParams to the tools/items/oneOf[BetaManagedAgentsAgentToolset20260401Params]/configs/items/ request property oneOf list
  request-property-one-of-added
- ○
  added discriminator to tools/items/oneOf[BetaManagedAgentsAgentToolset20260401]/configs/items/ response property for the response status 200
  response-property-discriminator-added
Aug 17, 2026d2b230555b7f16720See the full diff
- ▲
  the request property description became not nullable
  request-property-became-not-nullable
- ▲
  the request property model/allOf[BetaManagedAgentsModelParams]/oneOf[BetaManagedAgentsModelConfigParams]/effort became not nullable
  request-property-became-not-nullable
- ▲
  the request property model/allOf[BetaManagedAgentsModelParams]/oneOf[BetaManagedAgentsModelConfigParams]/inference_geo became not nullable
  request-property-became-not-nullable
- ▲
  the request property model/allOf[BetaManagedAgentsModelParams]/oneOf[BetaManagedAgentsModelConfigParams]/speed became not nullable
  request-property-became-not-nullable
- ▲
  the request property multiagent became not nullable
  request-property-became-not-nullable
- ▲
  the request property skills/items/oneOf[BetaManagedAgentsAnthropicSkillParams]/version became not nullable
  request-property-became-not-nullable
- ▲
  the request property skills/items/oneOf[BetaManagedAgentsCustomSkillParams]/version became not nullable
  request-property-became-not-nullable
- ▲
  the request property system became not nullable
  request-property-became-not-nullable
- ▲
  the request property tools/items/oneOf[BetaManagedAgentsAgentToolset20260401Params]/configs/items/enabled became not nullable
  request-property-became-not-nullable
- ▲
  the request property tools/items/oneOf[BetaManagedAgentsAgentToolset20260401Params]/configs/items/permission_policy became not nullable
  request-property-became-not-nullable
- ▲
  the request property tools/items/oneOf[BetaManagedAgentsAgentToolset20260401Params]/default_config became not nullable
  request-property-became-not-nullable
- ▲
  the request property tools/items/oneOf[BetaManagedAgentsMCPToolsetParams]/configs/items/enabled became not nullable
  request-property-became-not-nullable
- ▲
  the request property tools/items/oneOf[BetaManagedAgentsMCPToolsetParams]/configs/items/permission_policy became not nullable
  request-property-became-not-nullable
- ▲
  the request property tools/items/oneOf[BetaManagedAgentsMCPToolsetParams]/default_config became not nullable
  request-property-became-not-nullable
- ▲
  response property description list-of-types was widened by adding types null to media type application/json of response 200
  response-property-list-of-types-widened
- ▲
  response property system list-of-types was widened by adding types null to media type application/json of response 200
  response-property-list-of-types-widened
- ●
  removed BetaManagedAgentsAgentToolsetDefaultConfigParams from the tools/items/oneOf[BetaManagedAgentsAgentToolset20260401Params]/default_config request property allOf list
  request-property-all-of-removed
- ●
  removed BetaManagedAgentsEffortParams from the model/allOf[BetaManagedAgentsModelParams]/oneOf[BetaManagedAgentsModelConfigParams]/effort request property allOf list
  request-property-all-of-removed
- ●
  removed BetaManagedAgentsMCPToolsetDefaultConfigParams from the tools/items/oneOf[BetaManagedAgentsMCPToolsetParams]/default_config request property allOf list
  request-property-all-of-removed
- ●
  removed BetaManagedAgentsMultiagentParams from the multiagent request property allOf list
  request-property-all-of-removed
- ●
  removed BetaManagedAgentsPermissionPolicy from the tools/items/oneOf[BetaManagedAgentsAgentToolset20260401Params]/configs/items/permission_policy request property allOf list
  request-property-all-of-removed
- ●
  removed BetaManagedAgentsPermissionPolicy from the tools/items/oneOf[BetaManagedAgentsMCPToolsetParams]/configs/items/permission_policy request property allOf list
  request-property-all-of-removed
- ●
  removed BetaManagedAgentsSpeed from the model/allOf[BetaManagedAgentsModelParams]/oneOf[BetaManagedAgentsModelConfigParams]/speed request property allOf list
  request-property-all-of-removed
- ○
  added BetaManagedAgentsAgentToolsetDefaultConfigParams subschema #2 to the tools/items/oneOf[BetaManagedAgentsAgentToolset20260401Params]/default_config request property anyOf list
  request-property-any-of-added
- ○
  added BetaManagedAgentsEffortParams subschema #2 to the model/allOf[BetaManagedAgentsModelParams]/oneOf[BetaManagedAgentsModelConfigParams]/effort request property anyOf list
  request-property-any-of-added
- ○
  added BetaManagedAgentsMCPToolsetDefaultConfigParams subschema #2 to the tools/items/oneOf[BetaManagedAgentsMCPToolsetParams]/default_config request property anyOf list
  request-property-any-of-added
- ○
  added BetaManagedAgentsMultiagentParams subschema #2 to the multiagent request property anyOf list
  request-property-any-of-added
- ○
  added BetaManagedAgentsPermissionPolicy subschema #2 to the tools/items/oneOf[BetaManagedAgentsAgentToolset20260401Params]/configs/items/permission_policy request property anyOf list
  request-property-any-of-added
- ○
  added BetaManagedAgentsPermissionPolicy subschema #2 to the tools/items/oneOf[BetaManagedAgentsMCPToolsetParams]/configs/items/permission_policy request property anyOf list
  request-property-any-of-added
- ○
  added BetaManagedAgentsSpeed subschema #2 to the model/allOf[BetaManagedAgentsModelParams]/oneOf[BetaManagedAgentsModelConfigParams]/speed request property anyOf list
  request-property-any-of-added
- ○
  request property description list-of-types was widened by adding types null to media type application/json
  request-property-list-of-types-widened
- ○
  request property model/allOf[BetaManagedAgentsModelParams]/oneOf[BetaManagedAgentsModelConfigParams]/inference_geo list-of-types was widened by adding types null to media type application/json
  request-property-list-of-types-widened
- ○
  request property skills/items/oneOf[BetaManagedAgentsAnthropicSkillParams]/version list-of-types was widened by adding types null to media type application/json
  request-property-list-of-types-widened
- ○
  request property skills/items/oneOf[BetaManagedAgentsCustomSkillParams]/version list-of-types was widened by adding types null to media type application/json
  request-property-list-of-types-widened
- ○
  request property system list-of-types was widened by adding types null to media type application/json
  request-property-list-of-types-widened
- ○
  request property tools/items/oneOf[BetaManagedAgentsAgentToolset20260401Params]/configs/items/enabled list-of-types was widened by adding types null to media type application/json
  request-property-list-of-types-widened
- ○
  request property tools/items/oneOf[BetaManagedAgentsMCPToolsetParams]/configs/items/enabled list-of-types was widened by adding types null to media type application/json
  request-property-list-of-types-widened
- ○
  the skills/items/oneOf[BetaManagedAgentsAnthropicSkillParams]/version request property's minLength was decreased from 1 to 0
  request-property-min-length-decreased
- ○
  the skills/items/oneOf[BetaManagedAgentsCustomSkillParams]/version request property's minLength was decreased from 1 to 0
  request-property-min-length-decreased
- ○
  removed BetaManagedAgentsMultiagent from the multiagent response property allOf list for the response status 200
  response-property-all-of-removed
- ○
  removed BetaTimestamp from the archived_at response property allOf list for the response status 200
  response-property-all-of-removed
- ○
  added BetaManagedAgentsMultiagent subschema #2 to the multiagent response property anyOf list for the response status 200
  response-property-any-of-added
- ○
  added BetaTimestamp subschema #2 to the archived_at response property anyOf list for the response status 200
  response-property-any-of-added
Aug 6, 202693d8fd7d649355See the full diff
- ▲
  added BetaManagedAgentsAgentReference BetaManagedAgentsAdvisor to the multiagent/allOf[BetaManagedAgentsMultiagent]/oneOf[BetaManagedAgentsMultiagentCoordinator]/agents/items/ response property oneOf list for the response status 200
  response-property-one-of-added
- ▲
  the multiagent/allOf[BetaManagedAgentsMultiagent]/oneOf[BetaManagedAgentsMultiagentCoordinator]/agents/items/ response's property type/format changed from object/ to / for status 200
  response-property-type-changed
- ▲
  removed the required property multiagent/allOf[BetaManagedAgentsMultiagent]/oneOf[BetaManagedAgentsMultiagentCoordinator]/agents/items/id from the response with the 200 status
  response-required-property-removed
- ▲
  removed the required property multiagent/allOf[BetaManagedAgentsMultiagent]/oneOf[BetaManagedAgentsMultiagentCoordinator]/agents/items/type from the response with the 200 status
  response-required-property-removed
- ▲
  removed the required property multiagent/allOf[BetaManagedAgentsMultiagent]/oneOf[BetaManagedAgentsMultiagentCoordinator]/agents/items/version from the response with the 200 status
  response-required-property-removed
- ○
  added the new optional request property model/allOf[BetaManagedAgentsModelParams]/oneOf[BetaManagedAgentsModelConfigParams]/inference_geo
  new-optional-request-property
- ○
  added advisor discriminator mapping keys to the multiagent/allOf[BetaManagedAgentsMultiagentParams]/oneOf[BetaManagedAgentsMultiagentCoordinatorParams]/agents/items/oneOf[subschema #2]/ request property
  request-property-discriminator-mapping-added
- ○
  added BetaManagedAgentsAdvisorParams to the multiagent/allOf[BetaManagedAgentsMultiagentParams]/oneOf[BetaManagedAgentsMultiagentCoordinatorParams]/agents/items/oneOf[subschema #2]/ request property oneOf list
  request-property-one-of-added
- ○
  added the optional property model/inference_geo to the response with the 200 status
  response-optional-property-added
- ○
  added discriminator to multiagent/allOf[BetaManagedAgentsMultiagent]/oneOf[BetaManagedAgentsMultiagentCoordinator]/agents/items/ response property for the response status 200
  response-property-discriminator-added
This revision also has 1 change that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog
Jul 24, 2026a97790bd7f1824See the full diff
- ▲
  removed subschema #4 subschema #5 subschema #6 subschema #10 subschema #11 from the model/allOf[BetaManagedAgentsModelParams]/oneOf[BetaManagedAgentsModelConfigParams]/id request property anyOf list
  request-property-any-of-removed
- ▲
  removed subschema #4 subschema #5 subschema #6 subschema #10 subschema #11 from the model/allOf[BetaManagedAgentsModelParams]/oneOf[subschema #1: BetaManagedAgentsModel]/allOf[subschema #1: BetaManagedAgentsModel]/ request property anyOf list
  request-property-any-of-removed
- ○
  added subschema #4 subschema #5 subschema #6 subschema #7 subschema #11 subschema #12 to the model/allOf[BetaManagedAgentsModelParams]/oneOf[BetaManagedAgentsModelConfigParams]/id request property anyOf list
  request-property-any-of-added
- ○
  added subschema #4 subschema #5 subschema #6 subschema #7 subschema #11 subschema #12 to the model/allOf[BetaManagedAgentsModelParams]/oneOf[subschema #1: BetaManagedAgentsModel]/allOf[subschema #1: BetaManagedAgentsModel]/ request property anyOf list
  request-property-any-of-added
- ○
  added subschema #4 subschema #5 subschema #6 subschema #7 subschema #11 subschema #12 to the model/id response property anyOf list for the response status 200
  response-property-any-of-added
- ○
  removed subschema #4 subschema #5 subschema #6 subschema #10 subschema #11 from the model/id response property anyOf list for the response status 200
  response-property-any-of-removed
Jul 22, 20265e4a8830793b2See the full diff
- ○
  added the new optional request property model/allOf[BetaManagedAgentsModelParams]/oneOf[BetaManagedAgentsModelConfigParams]/effort
  new-optional-request-property
- ○
  added the optional property model/effort to the response with the 200 status
  response-optional-property-added
This revision also has 7 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog
Jul 2, 2026ec00b28b50c21See the full diff
- ○
  the tools/items/oneOf[BetaManagedAgentsCustomToolParams]/description request property's maxLength was increased from 1024 to 4096
  request-property-max-length-increased
Jun 30, 20267caa9a75ddbc3See the full diff
- ○
  added subschema #2 to the model/allOf[BetaManagedAgentsModelParams]/oneOf[BetaManagedAgentsModelConfigParams]/id request property anyOf list
  request-property-any-of-added
- ○
  added subschema #2 to the model/allOf[BetaManagedAgentsModelParams]/oneOf[subschema #1: BetaManagedAgentsModel]/allOf[subschema #1: BetaManagedAgentsModel]/ request property anyOf list
  request-property-any-of-added
- ○
  added subschema #2 to the model/id response property anyOf list for the response status 200
  response-property-any-of-added
Jun 9, 202600259327305f3See the full diff
- ○
  added subschema #2 to the model/allOf[BetaManagedAgentsModelParams]/oneOf[BetaManagedAgentsModelConfigParams]/id request property anyOf list
  request-property-any-of-added
- ○
  added subschema #2 to the model/allOf[BetaManagedAgentsModelParams]/oneOf[subschema #1: BetaManagedAgentsModel]/allOf[subschema #1: BetaManagedAgentsModel]/ request property anyOf list
  request-property-any-of-added
- ○
  added subschema #2 to the model/id response property anyOf list for the response status 200
  response-property-any-of-added
Jun 6, 2026546c704d347b517See the full diff
- ▲
  the request property tools/items/oneOf[BetaManagedAgentsCustomToolParams]/input_schema/allOf[BetaManagedAgentsCustomToolInputSchema]/properties became not nullable
  request-property-became-not-nullable
- ▲
  the request property tools/items/oneOf[BetaManagedAgentsCustomToolParams]/input_schema/allOf[BetaManagedAgentsCustomToolInputSchema]/type became required
  request-property-became-required
- ▲
  the type request property const value object was added
  request-property-const-added
- ▲
  removed the enum value object of the request property tools/items/oneOf[BetaManagedAgentsCustomToolParams]/input_schema/allOf[BetaManagedAgentsCustomToolInputSchema]/type
  request-property-enum-value-removed
- ▲
  response property tools/items/oneOf[BetaManagedAgentsCustomTool]/input_schema/required list-of-types was widened by adding types null to media type application/json of response 200
  response-property-list-of-types-widened
- ●
  removed BetaManagedAgentsStruct from the tools/items/oneOf[BetaManagedAgentsCustomToolParams]/input_schema/allOf[BetaManagedAgentsCustomToolInputSchema]/properties request property allOf list
  request-property-all-of-removed
- ○
  added subschema #1 subschema #2 to the tools/items/oneOf[BetaManagedAgentsCustomToolParams]/input_schema/allOf[BetaManagedAgentsCustomToolInputSchema]/properties request property anyOf list
  request-property-any-of-added
- ○
  request property tools/items/oneOf[BetaManagedAgentsCustomToolParams]/input_schema/allOf[BetaManagedAgentsCustomToolInputSchema]/required list-of-types was widened by adding types null to media type application/json
  request-property-list-of-types-widened
- ○
  removed BetaManagedAgentsStruct from the tools/items/oneOf[BetaManagedAgentsCustomTool]/input_schema/properties response property allOf list for the response status 200
  response-property-all-of-removed
- ○
  added subschema #1 subschema #2 to the tools/items/oneOf[BetaManagedAgentsCustomTool]/input_schema/properties response property anyOf list for the response status 200
  response-property-any-of-added
- ○
  the response property tools/items/oneOf[BetaManagedAgentsCustomTool]/input_schema/type became required for the status 200
  response-property-became-required
- ○
  the type response property const value object was added for the status 200
  response-property-const-added
- ○
  removed the object enum value from the tools/items/oneOf[BetaManagedAgentsCustomTool]/input_schema/type response property for the response status 200
  response-property-enum-value-removed
May 28, 2026f9d488f9290d3See the full diff
- ○
  added subschema #2 to the model/allOf[BetaManagedAgentsModelParams]/oneOf[BetaManagedAgentsModelConfigParams]/id request property anyOf list
  request-property-any-of-added
- ○
  added subschema #2 to the model/allOf[BetaManagedAgentsModelParams]/oneOf[subschema #1: BetaManagedAgentsModel]/allOf[subschema #1: BetaManagedAgentsModel]/ request property anyOf list
  request-property-any-of-added
- ○
  added subschema #2 to the model/id response property anyOf list for the response status 200
  response-property-any-of-added

Full history (13 revisions)