Update Agent

Update Agent through the OMA API.

POST /v1/agents/{agent_id}

Update Agent

cURL

curl --request POST \
  --url http://localhost:38080/v1/agents/{agent_id} \
  --header 'Content-Type: application/json' \
  --header 'X-Api-Key: <api-key>' \
  --data '
{
  "description": "updated"
}
'

200

{
  "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
}

Every request requires ?beta=true.

Authorizations

omaApiKeyomaBearer

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.

Path Parameters

agent_id · string · required

Path parameter agent_id

Query Parameters

beta · enum<boolean> · required

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

Available options: true

Body

application/json

Request parameters for updating an agent. Omit a field to preserve its current value.

version · integer<int32>

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.

Example:

1

name · string

Human-readable name. Must be non-empty. Omit to preserve. Cannot be cleared.

Maximum string length: 256

description · string | null

Description. Omit to preserve; send empty string or null to clear.

Maximum string length: 2048

model · BetaManagedAgentsModel · string BetaManagedAgentsModel · any BetaManagedAgentsModel · any BetaManagedAgentsModel · any BetaManagedAgentsModel · any BetaManagedAgentsModel · any BetaManagedAgentsModel · any BetaManagedAgentsModel · any BetaManagedAgentsModel · any BetaManagedAgentsModel · any BetaManagedAgentsModel · any BetaManagedAgentsModel · any BetaManagedAgentsModel · any BetaManagedAgentsModel · any Option 15 · object

Model identifier. Accepts the model string, e.g. claude-opus-4-6, or a model_config object for additional configuration control. Omit to preserve. Cannot be cleared.

system · string | null

System prompt. Omit to preserve; send empty string or null to clear.

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[] | null

Tool configurations available to the agent. Full replacement. Omit to preserve; send empty array or null to clear. 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

mcp_servers · object[] | null

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.

Show child attributes

skills · object[] | null

Skills. Full replacement. Omit to preserve; send empty array or null to clear.

Skill to load in the session container.

Option 1

Option 2

Show child attributes

Example:

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

metadata · object | null

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.

Show child attributes

multiagent · object | null

Multiagent orchestration configuration. Full replacement. Omit to preserve; send null to clear.

Show child attributes

Example:

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

Response

200

application/json

Successful response (OK)

A Managed Agents agent.

id · 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