更新智能体

POST

agents

{agent_id}

更新智能体

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

import requests

url = "http://localhost:38080/v1/agents/{agent_id}"

payload = { "description": "已更新" }
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({description: '已更新'})
};

fetch('http://localhost:38080/v1/agents/{agent_id}', 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/{agent_id}"

	payload := strings.NewReader("{\n  \"description\": \"已更新\"\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": "通用入门智能体。",
  "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": "我的第一个智能体",
  "skills": [
    {
      "skill_id": "xlsx",
      "type": "anthropic",
      "version": "1"
    },
    {
      "skill_id": "skill_011CZkZFNu9hAbo3jZPRgTlx",
      "type": "custom",
      "version": "2"
    }
  ],
  "system": "你是一个通用智能体，可以研究问题、编写代码、运行命令并使用已连接的工具，端到端地完成用户任务。",
  "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"
}

每个请求都必须发送 ?beta=true。

授权

X-Api-Key

string

header

默认值:sk-ant-local-default

必填

OMA 工作区 API 密钥。

请求头

anthropic-version

string

要使用的 OMA API 兼容版本。

anthropic-beta

string

用于启用托管智能体 API 合同的 Beta 请求头。

路径参数

agent_id

string

必填

智能体标识符。

查询参数

beta

enum<boolean>

必填

为此接口启用 Beta API 合同，必须为 true。

可用选项:

true

请求体

application/json

用于更新 agent 的请求参数。省略字段以保留其当前值。

version

integer<int32>

智能体的当前版本，用于防止并发覆盖。请从创建或获取响应中取得此值。指定时必须至少为 1。提供时，若与服务端当前版本不匹配则请求失败；省略则无条件应用更新。

示例:

1

name

string

人类可读的名称。必须非空。省略则保留。无法清除。

Maximum string length: 256

description

string | null

描述。省略则保持不变；发送空字符串或 null 则清除。

Maximum string length: 2048

model

模型标识符。可传入模型字符串（例如 claude-opus-4-6），或用于更多配置控制的 model_config 对象。省略则保留。无法清除。

system

string | null

系统提示词。省略则保持不变；发送空字符串或 null 则清除。

Maximum string length: 100000

示例:

"你是一个通用智能体，可以研究问题、编写代码、运行命令并使用已连接的工具，端到端地完成用户任务。"

tools

object[] | null

可供智能体使用的工具配置。整体替换。省略则保留；传入空数组或 null 则清空。所有工具集合计最多允许 128 个工具。

内置智能体工具的配置。用于启用或禁用智能体可用的工具组。

Option 1
Option 2
Option 3

Show child attributes

mcp_servers

object[] | null

MCP 服务器。全量替换。省略则保留；发送空数组或 null 则清空。名称必须唯一。最多 20 个。每个服务器都必须被智能体最终 tools 中的 mcp_toolset 引用；未被引用的服务器会被拒绝。详见 MCP 连接器指南。

Show child attributes

skills

object[] | null

技能。全量替换。省略则保留；发送空数组或 null 则清除。

要加载到会话容器中的技能。

Option 1
Option 2

Show child attributes

示例:

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

metadata

object | null

元数据补丁。将某个键设为字符串以插入或更新该键，设为 null 以删除该键。省略该字段则保持不变。存储的元数据集合最多 16 个键（每个键最多 64 个字符），值最多 512 个字符。

Show child attributes

multiagent

object | null

多智能体编排配置。全量替换。省略以保留；发送 null 以清除。

Show child attributes

示例:

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

响应

请求成功。

托管智能体的 agent。

string

必填

示例:

"agent_011CZkYpogX7uDKUyvBTophP"

archived_at

string<date-time> | null

必填

智能体的归档时间。未归档时为 null。

示例:

null

created_at

string<date-time>

必填

RFC 3339 格式的时间戳

示例:

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

description

string | null

必填

示例:

"一个通用入门智能体。"

mcp_servers

object[]

必填

Show child attributes

示例:

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

metadata

object

必填

Show child attributes

示例:

{ "foo": "bar" }

model

object

必填

模型标识符和配置。

Show child attributes

示例:

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

multiagent

object | null

必填

多智能体编排配置。当智能体为单线程时为 null。

Show child attributes

示例:

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

name

string

必填

示例:

"我的第一个智能体"

skills

object[]

必填

API 响应中返回的已解析技能。

Option 1
Option 2

Show child attributes

示例:

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

示例:

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

system

string | null

必填

示例:

"你是一个通用智能体，可以研究问题、编写代码、运行命令并使用已连接的工具，端到端地完成用户任务。"

tools

object[]

必填

API 响应中返回的工具配置的联合类型。

Option 1
Option 2
Option 3

Show child attributes

示例:

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

必填

可用选项:

agent

示例:

"agent"

updated_at

string<date-time>

必填

RFC 3339 格式的时间戳

示例:

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

version

integer<int32>

必填

智能体的当前版本。从 1 开始，每次修改智能体时递增。

示例:

1

更新智能体

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

import requests

url = "http://localhost:38080/v1/agents/{agent_id}"

payload = { "description": "已更新" }
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({description: '已更新'})
};

fetch('http://localhost:38080/v1/agents/{agent_id}', 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/{agent_id}"

	payload := strings.NewReader("{\n  \"description\": \"已更新\"\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": "通用入门智能体。",
  "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": "我的第一个智能体",
  "skills": [
    {
      "skill_id": "xlsx",
      "type": "anthropic",
      "version": "1"
    },
    {
      "skill_id": "skill_011CZkZFNu9hAbo3jZPRgTlx",
      "type": "custom",
      "version": "2"
    }
  ],
  "system": "你是一个通用智能体，可以研究问题、编写代码、运行命令并使用已连接的工具，端到端地完成用户任务。",
  "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"
}

开始使用

核心 API

托管智能体

Webhook

授权

请求头

路径参数

查询参数

请求体

响应