跳转到主要内容

Documentation Index

Fetch the complete documentation index at: https://docs.qoder.com/llms.txt

Use this file to discover all available pages before exploring further.

PUT /v1/agents/{agent_id} 更新指定 Agent 的配置。使用乐观并发控制（OCC），需要在请求体中提供当前 version 值。

​
请求头

头部必选说明
Authorization是Bearer <PAT>
Content-Type是application/json

​
路径参数

参数类型必选说明
agent_idstring是Agent 唯一标识

​
请求体

字段类型必选说明
versioninteger是当前版本号（OCC 校验），必须与服务端当前版本一致
namestring否Agent 名称，长度 1-256 字符
modelstring/object否模型标识
systemstring否系统提示词
descriptionstring否Agent 描述
toolsarray否工具配置列表
mcp_serversarray否MCP 服务器配置列表
metadataobject否自定义元数据键值对
default_environmentstring否默认运行环境

​
示例请求

curl -X PUT "https://openapi.qoder.sh/api/v1/cloud/agents/agent_019eXXXX..." \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "doc-test-agent-updated",
    "model": "ultimate",
    "system": "你是更新后的文档测试助手",
    "description": "用于 API 文档测试",
    "version": 1
  }'

​
示例响应

HTTP 200 OK 
{
  "type": "agent",
  "id": "agent_019eXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "name": "doc-test-agent-updated",
  "description": "用于 API 文档测试",
  "model": "ultimate",
  "system": "你是更新后的文档测试助手",
  "instructions": "你是更新后的文档测试助手",
  "tools": [],
  "mcp_servers": [],
  "default_environment": "",
  "version": 2,
  "created_at": "2026-05-18T15:26:39.61669Z",
  "updated_at": "2026-05-18T15:27:07.967138Z"
}

​
乐观并发控制（OCC）

更新操作使用版本号进行乐观锁校验：
  1. 客户端先通过 GET 获取 Agent 当前的 version 值
  2. 更新时将该 version 放入请求体
  3. 服务端校验 version 是否与当前值一致
  4. 一致则更新成功，version 自动 +1
  5. 不一致则返回 409 Conflict
这确保了多个客户端并发修改同一 Agent 时不会互相覆盖。

​
错误码

HTTPtype触发条件
400invalid_request_error请求体格式错误或字段值不合法
401authentication_errorPAT 无效或过期
403permission_error无权限更新此 Agent
404not_found_error指定 ID 的 Agent 不存在
409conflict_errorversion 不匹配，存在并发冲突
版本冲突（409）错误响应示例： 
{
  "type": "error",
  "error": {
    "type": "conflict_error",
    "message": "Version conflict. Expected version 99, got 1."
  }
}

​
注意事项

  • version 字段是必须的，不传会导致更新失败
  • 每次成功更新后 version 自动递增
  • 更新是全量替换语义：未传的可选字段会被设为空值，建议每次更新时传入所有当前字段值
  • 可通过 列出 Agent 版本 查看历史版本