更新智能体

修改请求体中提供的字段，并创建一个新的不可变智能体版本。

数组和 metadata 会替换已存储的值。传入空值可清空对应集合。null 值视为未提供。
传入当前的 version 进行乐观并发检查。版本过期时更新失败，返回 409 conflict_error。
空补丁返回 400 invalid_request_error。已归档的智能体拒绝更新，返回 400 failed_precondition_error。

PATCH

agents

{id}

更新智能体

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

请求头

kimi-api-version

enum<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

路径参数

string

必填

智能体 ID。

请求体

application/json

更新智能体的部分更新请求体。只有出现的字段会变更，且更新会创建一个新的不可变版本。出现的数组与 metadata 映射会整体替换已存储的值（发送空值即可清空）。

version

string

智能体当前的 version。如果智能体在此之后发生变更，请求返回 409 conflict_error。

name

string

人类可读的智能体名称。

Maximum string length: 256

model

所选模型。

description

string

可选的人类可读描述。

Maximum string length: 2048

system

string

系统提示词。

Maximum string length: 100000

tools

(Agent 工具集 · object | MCP 工具集 · object)[]

替换工具列表。

Maximum array length: 128

内置智能体工具集声明。

Agent 工具集
MCP 工具集

Show child attributes

mcp_servers

object[]

替换 MCP 服务器连接列表。名称必须唯一。

Maximum array length: 20

Show child attributes

skills

object[]

替换技能列表。

Show child attributes

plugins

object[]

替换插件列表。

Show child attributes

metadata

object

替换元数据（最多 16 个条目）。

Show child attributes

multiagent

object

替换当前协调者配置。发送空的 agents 数组即可清空。

Show child attributes

响应

更新后的智能体，处于新的不可变版本。

持久化的、带版本管理的智能体配置。

string

必填

智能体 ID。

name

string

必填

人类可读的智能体名称。

model

必填

所选模型。

version

string

必填

智能体当前的不可变版本。

created_at

string<date-time>

必填

创建时间戳。

updated_at

string<date-time>

必填

最后更新时间戳。

scope

enum<string>

必填

可见性范围。

可用选项:

official,

org,

project,

user

description

string

可选的人类可读描述。

system

string

系统提示词。

tools

(Agent 工具集 · object | MCP 工具集 · object)[]

智能体可用的工具。

内置智能体工具集声明。

Agent 工具集
MCP 工具集

Show child attributes

mcp_servers

object[]

智能体可用的 MCP 服务器连接。

Show child attributes

skills

object[]

智能体可用的技能版本，在写入时冻结。

Show child attributes

plugins

object[]

智能体可用的插件，在写入时冻结。

Show child attributes

metadata

object

用户自定义元数据（最多 16 条）。

Show child attributes

archived_at

string<date-time>

归档时间戳。处于活跃状态时不存在。

multiagent

object

解析后的子智能体配置。单智能体时不存在。

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

使用 API

API Reference

工具接口

文件接口

批处理接口

托管智能体 Beta

更新智能体

请求头

路径参数

请求体

响应