更新智能体
修改请求体中提供的字段,并创建一个新的不可变智能体版本。
- 数组和
metadata会替换已存储的值。传入空值可清空对应集合。null值会被拒绝(400invalid_parameter_error)。 mcp_servers的 headers 例外:按服务器身份合并。headers缺省或为空时,继承未发生变化的服务器(name、type、url 均一致)的已存储值,非空时整体替换,值为空字符串表示删除该键。- 传入当前的
version进行乐观并发检查。版本过期时更新失败,返回 409conflict_error。 - 空补丁返回 400
invalid_request_error。已归档的智能体拒绝更新,返回 400failed_precondition_error。
curl --request PATCH \
--url https://api.moonshot.cn/v1/agents/{id} \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"name": "Updated Agent"
}
'import requests
url = "https://api.moonshot.cn/v1/agents/{id}"
payload = { "name": "Updated Agent" }
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.patch(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'PATCH',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({name: 'Updated Agent'})
};
fetch('https://api.moonshot.cn/v1/agents/{id}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.moonshot.cn/v1/agents/{id}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "PATCH",
CURLOPT_POSTFIELDS => json_encode([
'name' => 'Updated Agent'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.moonshot.cn/v1/agents/{id}"
payload := strings.NewReader("{\n \"name\": \"Updated Agent\"\n}")
req, _ := http.NewRequest("PATCH", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
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))
}HttpResponse<String> response = Unirest.patch("https://api.moonshot.cn/v1/agents/{id}")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"name\": \"Updated Agent\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.moonshot.cn/v1/agents/{id}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Patch.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"name\": \"Updated Agent\"\n}"
response = http.request(request)
puts response.read_body{
"id": "agent_01h455vb4pex5vsknk084sn02q",
"name": "Updated Agent",
"model": {
"id": "kimi-example"
},
"version": "2",
"created_at": "2026-01-01T00:00:00Z",
"updated_at": "2026-01-02T00:00:00Z",
"scope": "project"
}{
"error": {
"type": "invalid_parameter_error",
"message": "<string>",
"param": "<string>",
"request_id": "<string>"
}
}{
"error": {
"type": "invalid_parameter_error",
"message": "<string>",
"param": "<string>",
"request_id": "<string>"
}
}{
"error": {
"type": "invalid_parameter_error",
"message": "<string>",
"param": "<string>",
"request_id": "<string>"
}
}{
"error": {
"type": "invalid_parameter_error",
"message": "<string>",
"param": "<string>",
"request_id": "<string>"
}
}{
"error": {
"type": "invalid_parameter_error",
"message": "<string>",
"param": "<string>",
"request_id": "<string>"
}
}{
"error": {
"type": "invalid_parameter_error",
"message": "<string>",
"param": "<string>",
"request_id": "<string>"
}
}请求头
本次请求使用的 API 版本,格式为 YYYY-MM-DD。发送 2026-09-01-beta 即使用本文档所述版本。/v1/files* 之外必传:未携带请求头将被拒绝并返回 400 invalid_request_error;在 /v1/files* 上缺省时选择兼容行为。所有端点对未知取值均返回 400 invalid_request_error。
平台当前支持的 API 版本。新的日期版本发布时加入;版本在公告的 Sunset 日期后移除。
2026-09-01-beta 路径参数
智能体 ID。
请求体
更新智能体的部分更新请求体。只有出现的字段会变更,且更新会创建一个新的不可变版本。出现的数组与 metadata 映射会整体替换已存储的值(发送空值即可清空)。
智能体当前的 version。如果智能体在此之后发生变更,请求返回 409 conflict_error。
人类可读的智能体名称。
256所选模型。
可选的人类可读描述。
2048系统提示词。
100000替换工具列表。
128内置智能体工具集声明。同一 name 出现多次时,只使用首份声明及其 default_config、configs,不合并后续声明。
- Agent 工具集
- 自定义工具
- MCP 工具集
Show child attributes
Show child attributes
替换 MCP 服务器连接列表。名称必须唯一。
20Show child attributes
Show child attributes
替换技能列表。
Show child attributes
Show child attributes
替换插件列表。
Show child attributes
Show child attributes
替换元数据(最多 16 个条目)。
Show child attributes
Show child attributes
替换当前协调者配置。发送空的 agents 数组即可清空。
Show child attributes
Show child attributes
响应
更新后的智能体,处于新的不可变版本。
持久化的、带版本管理的智能体配置。
智能体 ID。
人类可读的智能体名称。
所选模型。
智能体当前的不可变版本。
创建时间戳。
最后更新时间戳。
可见性范围。
official, org, project, user 可选的人类可读描述。
系统提示词。
智能体可用的工具。
内置智能体工具集声明。同一 name 出现多次时,只使用首份声明及其 default_config、configs,不合并后续声明。
- Agent 工具集
- 自定义工具
- MCP 工具集
Show child attributes
Show child attributes
智能体可用的 MCP 服务器连接。
Show child attributes
Show child attributes
智能体可用的技能版本。空版本在写入时冻结;"latest" 原样保留,每次唤醒现解最新版。
Show child attributes
Show child attributes
智能体可用的插件,在写入时冻结。
Show child attributes
Show child attributes
用户自定义元数据(最多 16 条)。
Show child attributes
Show child attributes
归档时间戳。处于活跃状态时不存在。
解析后的子智能体配置。单智能体时不存在。
Show child attributes
Show child attributes
此页面对您有帮助吗?
curl --request PATCH \
--url https://api.moonshot.cn/v1/agents/{id} \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"name": "Updated Agent"
}
'import requests
url = "https://api.moonshot.cn/v1/agents/{id}"
payload = { "name": "Updated Agent" }
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.patch(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'PATCH',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({name: 'Updated Agent'})
};
fetch('https://api.moonshot.cn/v1/agents/{id}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.moonshot.cn/v1/agents/{id}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "PATCH",
CURLOPT_POSTFIELDS => json_encode([
'name' => 'Updated Agent'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.moonshot.cn/v1/agents/{id}"
payload := strings.NewReader("{\n \"name\": \"Updated Agent\"\n}")
req, _ := http.NewRequest("PATCH", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
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))
}HttpResponse<String> response = Unirest.patch("https://api.moonshot.cn/v1/agents/{id}")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"name\": \"Updated Agent\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.moonshot.cn/v1/agents/{id}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Patch.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"name\": \"Updated Agent\"\n}"
response = http.request(request)
puts response.read_body{
"id": "agent_01h455vb4pex5vsknk084sn02q",
"name": "Updated Agent",
"model": {
"id": "kimi-example"
},
"version": "2",
"created_at": "2026-01-01T00:00:00Z",
"updated_at": "2026-01-02T00:00:00Z",
"scope": "project"
}{
"error": {
"type": "invalid_parameter_error",
"message": "<string>",
"param": "<string>",
"request_id": "<string>"
}
}{
"error": {
"type": "invalid_parameter_error",
"message": "<string>",
"param": "<string>",
"request_id": "<string>"
}
}{
"error": {
"type": "invalid_parameter_error",
"message": "<string>",
"param": "<string>",
"request_id": "<string>"
}
}{
"error": {
"type": "invalid_parameter_error",
"message": "<string>",
"param": "<string>",
"request_id": "<string>"
}
}{
"error": {
"type": "invalid_parameter_error",
"message": "<string>",
"param": "<string>",
"request_id": "<string>"
}
}{
"error": {
"type": "invalid_parameter_error",
"message": "<string>",
"param": "<string>",
"request_id": "<string>"
}
}