Create Agent

POST

agents

cURL

curl --request POST \
  --url 'http://localhost:38080/v1/agents?beta=true' \
  --header 'Content-Type: application/json' \
  --header 'anthropic-version: 2023-06-01' \
  --header 'anthropic-beta: managed-agents-2026-04-01' \
  --header 'X-Api-Key: sk-ant-local-default' \
  --data '{
    "model": "claude-sonnet-4-6",
    "name": "My First Agent",
    "description": "A general-purpose starter agent.",
    "metadata": {
      "foo": "bar"
    },
    "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"
      }
    ]
  }'

import requests

url = "http://localhost:38080/v1/agents"

payload = {
    "model": "claude-sonnet-4-6",
    "name": "My First Agent",
    "description": "A general-purpose starter agent."
}
headers = {
    "X-Api-Key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-Api-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    model: 'claude-sonnet-4-6',
    name: 'My First Agent',
    description: 'A general-purpose starter agent.'
  })
};

fetch('http://localhost:38080/v1/agents', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "http://localhost:38080/v1/agents"

	payload := strings.NewReader("{\n  \"model\": \"claude-sonnet-4-6\",\n  \"name\": \"My First Agent\",\n  \"description\": \"A general-purpose starter agent.\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-Api-Key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

{
  "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-sonnet-4-6",
    "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"
          }
        }
      ],
      "default_config": {
        "enabled": true,
        "permission_policy": {
          "type": "always_ask"
        }
      },
      "type": "agent_toolset_20260401"
    }
  ],
  "type": "agent",
  "updated_at": "2026-03-15T10:00:00Z",
  "version": 1
}

{
  "error": {
    "message": "Invalid request",
    "type": "invalid_request_error"
  },
  "request_id": "<string>",
  "type": "error"
}

{
  "error": {
    "message": "Invalid request",
    "type": "invalid_request_error"
  },
  "request_id": "<string>",
  "type": "error"
}

{
  "error": {
    "message": "Invalid request",
    "type": "invalid_request_error"
  },
  "request_id": "<string>",
  "type": "error"
}

{
  "error": {
    "message": "Invalid request",
    "type": "invalid_request_error"
  },
  "request_id": "<string>",
  "type": "error"
}

{
  "error": {
    "message": "Invalid request",
    "type": "invalid_request_error"
  },
  "request_id": "<string>",
  "type": "error"
}

{
  "error": {
    "message": "Invalid request",
    "type": "invalid_request_error"
  },
  "request_id": "<string>",
  "type": "error"
}

{
  "error": {
    "message": "Invalid request",
    "type": "invalid_request_error"
  },
  "request_id": "<string>",
  "type": "error"
}

{
  "error": {
    "message": "Invalid request",
    "type": "invalid_request_error"
  },
  "request_id": "<string>",
  "type": "error"
}

{
  "error": {
    "message": "Invalid request",
    "type": "invalid_request_error"
  },
  "request_id": "<string>",
  "type": "error"
}

{
  "error": {
    "message": "Invalid request",
    "type": "invalid_request_error"
  },
  "request_id": "<string>",
  "type": "error"
}

{
  "error": {
    "message": "Invalid request",
    "type": "invalid_request_error"
  },
  "request_id": "<string>",
  "type": "error"
}

{
  "error": {
    "message": "Invalid request",
    "type": "invalid_request_error"
  },
  "request_id": "<string>",
  "type": "error"
}

{
  "error": {
    "message": "Invalid request",
    "type": "invalid_request_error"
  },
  "request_id": "<string>",
  "type": "error"
}

{
  "error": {
    "message": "Invalid request",
    "type": "invalid_request_error"
  },
  "request_id": "<string>",
  "type": "error"
}

{
  "error": {
    "message": "Invalid request",
    "type": "invalid_request_error"
  },
  "request_id": "<string>",
  "type": "error"
}

Every request requires ?beta=true.

Authorizations

X-Api-Key

string

header

default:sk-ant-local-default

required

OMA workspace API key.

Headers

anthropic-version

string

The OMA API compatibility version to use.

anthropic-beta

string

Beta header that enables the Managed Agents API contract.

Query Parameters

beta

enum<boolean>

default:true

required

Selects the beta API contract for this endpoint. Must be true.

Available options:

true

Body

application/json

Request parameters for creating an agent.

model

required

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

Example:

"claude-sonnet-4-6"

name

string

required

Human-readable name for the agent.

Required string length: 1 - 256

Example:

"My First Agent"

description

string | null

Description of what the agent does.

Maximum string length: 2048

Example:

"A general-purpose starter agent."

mcp_servers

object[]

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.

Show child attributes

metadata

object

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

Show child attributes

Example:

{ "foo": "bar" }

multiagent

object | null

Multiagent orchestration configuration. Currently supports the coordinator topology with a roster of 1-20 agents.

Show child attributes

Example:

{
  "type": "coordinator",
  "agents": [
    "agent_011CZkYqphY8vELVzwCUpqiQ",
    { "type": "self" }
  ]
}

skills

object[]

Skills available to the agent.

Skill to load in the session container.

Option 1
Option 2

Show child attributes

Example:

{
  "type": "anthropic",
  "skill_id": "xlsx",
  "version": "1"
}

system

string | null

System prompt for the agent.

Maximum string length: 100000

Example:

"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

object[]

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

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

Option 1
Option 2
Option 3

Show child attributes

Example:

[{ "type": "agent_toolset_20260401" }]

Response

Successful response (OK)

A Managed Agents agent.

string

required

Example:

"agent_011CZkYpogX7uDKUyvBTophP"

archived_at

string<date-time> | null

required

When the agent was archived. Null if not archived.

Example:

null

created_at

string<date-time>

required

A timestamp in RFC 3339 format

Example:

"2026-03-15T10:00:00Z"

description

string | null

required

Example:

"A general-purpose starter agent."

mcp_servers

object[]

required

Show child attributes

Example:

[
  {
    "type": "url",
    "name": "example-mcp",
    "url": "https://example-server.modelcontextprotocol.io/sse"
  }
]

metadata

object

required

Show child attributes

Example:

{ "foo": "bar" }

model

object

required

Model identifier and configuration.

Show child attributes

Example:

{
  "id": "claude-sonnet-4-6",
  "effort": { "type": "low" },
  "inference_geo": "inference_geo",
  "speed": "standard"
}

multiagent

object | null

required

Multiagent orchestration configuration. Null when the agent is single-threaded.

Show child attributes

Example:

{
  "agents": [
    {
      "id": "agent_011CZkYqphY8vELVzwCUpqiQ",
      "type": "agent",
      "version": 1
    }
  ],
  "type": "coordinator"
}

name

string

required

Example:

"My First Agent"

skills

object[]

required

Resolved skill as returned in API responses.

Option 1
Option 2

Show child attributes

Example:

{
  "type": "anthropic",
  "skill_id": "xlsx",
  "version": "1"
}

Example:

[
  {
    "type": "anthropic",
    "skill_id": "xlsx",
    "version": "1"
  },
  {
    "type": "custom",
    "skill_id": "skill_011CZkZFNu9hAbo3jZPRgTlx",
    "version": "2"
  }
]

system

string | null

required

Example:

"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

object[]

required

Union type for tool configurations returned in API responses.

Option 1
Option 2
Option 3

Show child attributes

Example:

[
  {
    "configs": [
      {
        "enabled": true,
        "name": "bash",
        "permission_policy": { "type": "always_allow" }
      }
    ],
    "default_config": {
      "enabled": true,
      "permission_policy": { "type": "always_ask" }
    },
    "type": "agent_toolset_20260401"
  }
]

type

enum<string>

required

Available options:

agent

Example:

"agent"

updated_at

string<date-time>

required

A timestamp in RFC 3339 format

Example:

"2026-03-15T10:00:00Z"

version

integer<int32>

required

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

Example:

1

cURL

curl --request POST \
  --url 'http://localhost:38080/v1/agents?beta=true' \
  --header 'Content-Type: application/json' \
  --header 'anthropic-version: 2023-06-01' \
  --header 'anthropic-beta: managed-agents-2026-04-01' \
  --header 'X-Api-Key: sk-ant-local-default' \
  --data '{
    "model": "claude-sonnet-4-6",
    "name": "My First Agent",
    "description": "A general-purpose starter agent.",
    "metadata": {
      "foo": "bar"
    },
    "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"
      }
    ]
  }'

import requests

url = "http://localhost:38080/v1/agents"

payload = {
    "model": "claude-sonnet-4-6",
    "name": "My First Agent",
    "description": "A general-purpose starter agent."
}
headers = {
    "X-Api-Key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-Api-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    model: 'claude-sonnet-4-6',
    name: 'My First Agent',
    description: 'A general-purpose starter agent.'
  })
};

fetch('http://localhost:38080/v1/agents', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "http://localhost:38080/v1/agents"

	payload := strings.NewReader("{\n  \"model\": \"claude-sonnet-4-6\",\n  \"name\": \"My First Agent\",\n  \"description\": \"A general-purpose starter agent.\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-Api-Key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

{
  "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-sonnet-4-6",
    "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"
          }
        }
      ],
      "default_config": {
        "enabled": true,
        "permission_policy": {
          "type": "always_ask"
        }
      },
      "type": "agent_toolset_20260401"
    }
  ],
  "type": "agent",
  "updated_at": "2026-03-15T10:00:00Z",
  "version": 1
}

{
  "error": {
    "message": "Invalid request",
    "type": "invalid_request_error"
  },
  "request_id": "<string>",
  "type": "error"
}

{
  "error": {
    "message": "Invalid request",
    "type": "invalid_request_error"
  },
  "request_id": "<string>",
  "type": "error"
}

{
  "error": {
    "message": "Invalid request",
    "type": "invalid_request_error"
  },
  "request_id": "<string>",
  "type": "error"
}

{
  "error": {
    "message": "Invalid request",
    "type": "invalid_request_error"
  },
  "request_id": "<string>",
  "type": "error"
}

{
  "error": {
    "message": "Invalid request",
    "type": "invalid_request_error"
  },
  "request_id": "<string>",
  "type": "error"
}

{
  "error": {
    "message": "Invalid request",
    "type": "invalid_request_error"
  },
  "request_id": "<string>",
  "type": "error"
}

{
  "error": {
    "message": "Invalid request",
    "type": "invalid_request_error"
  },
  "request_id": "<string>",
  "type": "error"
}

{
  "error": {
    "message": "Invalid request",
    "type": "invalid_request_error"
  },
  "request_id": "<string>",
  "type": "error"
}

{
  "error": {
    "message": "Invalid request",
    "type": "invalid_request_error"
  },
  "request_id": "<string>",
  "type": "error"
}

{
  "error": {
    "message": "Invalid request",
    "type": "invalid_request_error"
  },
  "request_id": "<string>",
  "type": "error"
}

{
  "error": {
    "message": "Invalid request",
    "type": "invalid_request_error"
  },
  "request_id": "<string>",
  "type": "error"
}

{
  "error": {
    "message": "Invalid request",
    "type": "invalid_request_error"
  },
  "request_id": "<string>",
  "type": "error"
}

{
  "error": {
    "message": "Invalid request",
    "type": "invalid_request_error"
  },
  "request_id": "<string>",
  "type": "error"
}

{
  "error": {
    "message": "Invalid request",
    "type": "invalid_request_error"
  },
  "request_id": "<string>",
  "type": "error"
}

{
  "error": {
    "message": "Invalid request",
    "type": "invalid_request_error"
  },
  "request_id": "<string>",
  "type": "error"
}

Get started

Core API

Managed Agents

Webhooks

Authorizations

Headers

Query Parameters

Body

Response