Agent 模块 API 文档（实时抓取版）

本文档由本地运行中的 KIAP 后端（http://localhost:8001）真实请求抓取生成，非手写推测。用于前端对接、回归核对。git 版本号为快照节点，后期 git 更新后可据此区分接口是否变化。

0. 快照信息（git 版本号，重要！）

项	值
git commit（短）	`4f46278`
git commit（完整）	`4f462789875d362ff4b9106a7b73222e8c58b632`
commit 日期	`2026-08-11`
commit message	`feat: 新增 Agent Catalog 模块 Agent 模板与专家目录接口`
后端端口	`8001`
接口前缀	`/external/private/api`

抓取时间	`2026-08-12`

⚠️ 后期若 git pull / rebase 导致接口变化，以本 commit 4f46278 为基线对比。重新抓取命令见文末「附录：复现脚本」。

1. 鉴权头（所有接口必带）

后端从 HTTP 请求头读取身份（不读请求体/Query，请求体带 userId/tenantId 会被拒绝）。本地联调固定值（对应前端 DEFAULT_USER_ID / DEFAULT_TENANT_ID）：

Header	值	说明
`DEFrame-UserId`	`1123598821738675201`	用户 ID
`DEFrame-TenantId`	`000000`	租户 ID
`DEFrame-ExtendedInfo`	`{}`	必须为非空合法 JSON，缺失会导致 principal 注入失败、所有租户接口返回 `TPT_ACCESS_DENIED`（403）

反例（真实踩坑）：

只用 curl + set H3=DEFrame-ExtendedInfo: {}：cmd 会把 {} 截断，导致该头为 null → listener 注入崩溃 → 全部 TPT_ACCESS_DENIED。
缺失 DEFrame-ExtendedInfo：同上。
✅ 推荐用 PowerShell Invoke-RestMethod 显式传这三个头（见附录），稳定可靠。

2. 接口总览

#	方法	路径	说明	类型
1	GET	`/external/private/api/agent-types`	Agent 类型枚举	全局，无租户过滤
2	GET	`/external/private/api/agent-templates`	Agent 模板列表	租户过滤
3	GET	`/external/private/api/agents`	我的 Agent（分页）	租户过滤
4	GET	`/external/private/api/agents/mention-options`	@ 提及候选	租户过滤
5	GET	`/external/private/api/agents/home-prompts`	首页提示/通用助手	租户过滤
6	GET	`/external/private/api/expert-agents`	专家目录	租户过滤（按 License）
7	GET	`/external/private/api/agent-groups`	Agent 分组（含系统+用户）	租户过滤
8	GET	`/external/private/api/agents/{agentId}`	Agent 详情	租户过滤
9	POST	`/external/private/api/agents`	创建 Agent	写
10	PATCH	`/external/private/api/agents/{agentId}`	更新 Agent	写
11	DELETE	`/external/private/api/agents/{agentId}`	删除 Agent	写
12	POST	`/external/private/api/agent-groups`	创建分组	写
13	PATCH	`/external/private/api/agent-groups/{groupId}`	更新分组	写
14	DELETE	`/external/private/api/agent-groups/{groupId}`	删除分组	写

Controller 文件：kiap-service/.../agentcatalog/api/{AgentController, AgentGroupController, ExpertAgentController, AgentCatalogMetadataController}.java
⚠️ 写接口使用 PATCH（不是 PUT），源码注解为 @PatchMapping。

3. GET 接口（真实返回值）

3.1 GET /external/private/api/agent-types

名称：Agent 类型枚举作用：查询平台支持的 Agent 类型枚举（如评估/模拟/优化/控制/预测/统计），供前端创建 Agent 时选择类型。全局类型枚举，返回 code:200 + data.items[]（code/name/description/sortOrder）。

json

{
  "code": "200",
  "data": {
    "items": [
      {"code": "EVALUATION",   "name": "评估", "description": "指标评价、健康度评估或效果评估",   "sortOrder": 10},
      {"code": "SIMULATION",   "name": "模拟", "description": "场景仿真、方案模拟或参数试算",     "sortOrder": 20},
      {"code": "OPTIMIZATION", "name": "优化", "description": "策略优化、参数寻优或资源配置优化", "sortOrder": 30},
      {"code": "CONTROL",      "name": "控制", "description": "控制建议、操作决策或过程控制辅助", "sortOrder": 40},
      {"code": "FORECAST",     "name": "预测", "description": "趋势预测、负荷预测或业务指标预测", "sortOrder": 50},
      {"code": "STATISTICS",   "name": "统计", "description": "统计汇总、分布分析或报表问数",     "sortOrder": 60}
    ]
  },
  "success": true
}

3.2 GET /external/private/api/agent-templates

名称：Agent 模板列表作用：查询 Agent 创建模板列表（按类型预置 systemPrompt、能力、执行配置等），供前端「基于模板创建」使用。返回 code:200 + data.items[]，每个模板字段： templateId / templateCode / name / description / type / typeName / icon / capabilities[] / systemPrompt / defaultExecutionMode / executionConfig{maxIterations} / toolsAllow[] / skillsAllow[] / sortOrder。

已抓取 6 个模板（evaluation/simulation/optimization/control/forecast/statistics），节选其一：

json

{
  "code": "200",
  "data": {
    "items": [
      {
        "templateId": "tpl_evaluation_agent",
        "templateCode": "evaluation_agent",
        "name": "评估 Agent 模板",
        "description": "用于指标评价、健康度评估或效果评估。",
        "type": "EVALUATION",
        "typeName": "评估",
        "icon": "evaluation",
        "capabilities": ["指标评价", "健康度评估", "效果评估"],
        "systemPrompt": "你是评估分析 Agent。你需要基于受控数据、指标口径和工具结果完成评价……",
        "defaultExecutionMode": "KEY_STEPS",
        "executionConfig": {"maxIterations": 8},
        "toolsAllow": [],
        "skillsAllow": [],
        "sortOrder": 10
      }
    ]
  },
  "success": true
}

3.3 GET /external/private/api/agents

作用：分页查询当前用户/租户下的 Agent 列表（含系统内置与用户自建），用于「我的 Agent」主页展示。分页返回 code:200 + data.records[]，字段见 AgentSummaryResponse： agentId / agentCode / name / displayName / description / groupId / groupName / type / typeName / scope / status / icon / avatarUrl / capabilities[] / tags[] / supportedResourceTypes[] / isSystem / isOwner / permissionActions[] / defaultExecutionMode / recommendedWordCount / lastRunAt / runCount / createdAt / updatedAt，外加分页 current/size/pages/total。

真实数据（节选 1 条，全部 3 条均为 scope:USER, status:ENABLED, isOwner:true）：

json

{
  "code": "200",
  "data": {
    "records": [
      {
        "agentId": "agent_7358e8ad0c0e4efebf96ad2bd6f7ca16",
        "agentCode": "user_e9d3a52f08264d6ea8424c5c72412e67",
        "name": "虚拟电厂运营安全注意事项",
        "displayName": "虚拟电厂运营安全注意事项",
        "description": "基于给定的安全会话摘要，回答与虚拟电厂运营安全相关的问题。",
        "groupId": "sys_group_builtin",
        "groupName": "系统内置",
        "type": "OPTIMIZATION",
        "typeName": "优化",
        "scope": "USER",
        "status": "ENABLED",
        "icon": "robot",
        "avatarUrl": null,
        "capabilities": [],
        "tags": [],
        "supportedResourceTypes": [],
        "isSystem": false,
        "isOwner": true,
        "permissionActions": ["VIEW", "RUN", "EDIT", "DELETE"],
        "defaultExecutionMode": "KEY_STEPS",
        "recommendedWordCount": 0,
        "lastRunAt": null,
        "runCount": 0,
        "createdAt": "2026-08-05 15:24:13",
        "updatedAt": "2026-08-05 15:25:01"
      }
    ],
    "current": 1, "size": 10, "pages": 1, "total": 3
  },
  "success": true
}

分页参数：?current=1&size=10（默认）。scope 取值 USER/SYSTEM；status 取值 ENABLED/DISABLED。

3.4 GET /external/private/api/agents/mention-options

名称：@ 提及候选列表作用：查询对话中可被 @ 提及的 Agent 候选列表，供前端输入框 @ 联想选择。返回 code:200 + data[]（数组，非分页包装），元素字段同 AgentSummaryResponse（与 3.3 的 records[] 一致）。数组只显示一个示例元素：

json

{
  "code": "200",
  "data": [
    {
      "agentId": "agent_7358e8ad0c0e4efebf96ad2bd6f7ca16",
      "agentCode": "user_e9d3a52f08264d6ea8424c5c72412e67",
      "name": "虚拟电厂运营安全注意事项",
      "displayName": "虚拟电厂运营安全注意事项",
      "description": "基于给定的安全会话摘要，回答与虚拟电厂运营安全相关的问题。",
      "groupId": "sys_group_builtin",
      "groupName": "系统内置",
      "type": "OPTIMIZATION",
      "typeName": "优化",
      "scope": "USER",
      "status": "ENABLED",
      "icon": "robot",
      "avatarUrl": null,
      "capabilities": [],
      "tags": [],
      "supportedResourceTypes": [],
      "isSystem": false,
      "isOwner": true,
      "permissionActions": ["VIEW", "RUN", "EDIT", "DELETE"],
      "defaultExecutionMode": "KEY_STEPS",
      "recommendedWordCount": 0,
      "lastRunAt": null,
      "runCount": 0,
      "createdAt": "2026-08-05 15:24:13",
      "updatedAt": "2026-08-05 15:25:01"
    }
  ],
  "success": true
}

3.5 GET /external/private/api/agents/home-prompts

作用：获取通用助手（默认 Agent）的主页问候语与输入框占位提示，用于首页/新建对话初始界面。返回 code:200 + data 单对象（通用助手主页信息）：

json

{
  "code": "200",
  "data": {
    "agentId": "sys_general_assistant",
    "agentCode": "general_assistant",
    "agentName": "通用助手",
    "greeting": "你好，今天需要我帮你做点什么？",
    "placeholder": "发消息..."
  },
  "success": true
}

3.6 GET /external/private/api/expert-agents

名称：专家 Agent 目录作用：查询平台专家 Agent 目录（能源运营/交易/知识/预测等），用于专家模式入口与专家选择。返回 code:200 + data.items[]，字段：expertProfileId / agentId / name / description / icon / capabilityTags[] / sortOrder。真实 4 个专家：

json

{
  "code": "200",
  "data": {
    "items": [
      {"expertProfileId": "expert_energy_xiaoxi",      "agentId": "sys_energy_xiaoxi",         "name": "能源运营专家", "description": "能源运营问数、趋势和设备状态分析",     "icon": "energy",    "capabilityTags": ["能源运营","设备分析","电量分析"], "sortOrder": 10},
      {"expertProfileId": "expert_lingxi_trade",        "agentId": "sys_lingxi_trade",          "name": "能源交易专家", "description": "电力交易、价格、收益与申报分析",     "icon": "trade",     "capabilityTags": ["电力交易","电价分析","收益结算"], "sortOrder": 20},
      {"expertProfileId": "expert_zhihui_xiaoxi",      "agentId": "sys_zhxh_knowledge",        "name": "能源知识专家", "description": "能源知识检索和专业知识问答",          "icon": "knowledge", "capabilityTags": ["能源知识","知识检索","专业问答"], "sortOrder": 30},
      {"expertProfileId": "expert_smart_forecast_xiaoxi","agentId": "sys_smart_forecast_xiaoxi","name": "能源预测专家", "description": "数据集、微调模型和时间序列预测分析", "icon": "forecast",  "capabilityTags": ["时序预测","微调模型","预测图表"], "sortOrder": 35}
    ]
  },
  "success": true
}

3.7 GET /external/private/api/agent-groups

作用：查询 Agent 分组列表（含系统内置分组与用户自建分组），用于「我的 Agent」按分组归类展示。返回 code:200 + data.items[]，字段：groupId / groupCode / name / description / icon / scope / isSystem / sortOrder / agents（agents 列表为 null，详情走 /agents）。真实含系统分组 + 用户分组：

json

{
  "code": "200",
  "data": {
    "items": [
      {"groupId": "sys_group_builtin", "groupCode": "system_builtin", "name": "系统内置", "description": "平台内置并统一维护的 Agent。", "icon": null, "scope": "SYSTEM", "isSystem": true, "sortOrder": 10, "agents": null},
      {"groupId": "group_b01cfcd786fd4d6ea82f3843ed5f6729", "groupCode": "user_5d34ba2771d54b91bdbac24c131bc2bc", "name": "用户新增分组", "description": "test", "icon": "setting", "scope": "USER", "isSystem": false, "sortOrder": 100, "agents": null}
    ]
  },
  "success": true
}

3.8 GET /external/private/api/agents/

名称：Agent 详情作用：根据 agentId 查询单个 Agent 的完整详情（含 systemPrompt、执行与运行时配置），用于编辑页/运行前配置加载。返回 code:200 + data = AgentDetailResponse。与 AgentSummaryResponse 不同：

group 为对象 {groupId, name}（非 groupId/groupName 平铺）
含 systemPrompt
不含 displayName / tags / supportedResourceTypes / isSystem / isOwner / permissionActions / recommendedWordCount / lastRunAt / runCount / avatarUrl
额外含 executionConfig{executionMode, maxIterations} 与 runtimeConfig{toolsAllow[], skillsAllow[]}

需用真实 agentId 请求，示例 agent_7358e8ad0c0e4efebf96ad2bd6f7ca16：

json

{
  "code": "200",
  "data": {
    "agentId": "agent_7358e8ad0c0e4efebf96ad2bd6f7ca16",
    "agentCode": "user_e9d3a52f08264d6ea8424c5c72412e67",
    "name": "虚拟电厂运营安全注意事项",
    "description": "基于给定的安全会话摘要，回答与虚拟电厂运营安全相关的问题。",
    "systemPrompt": "你是虚拟电厂运营安全分析 Agent……",
    "group": {
      "groupId": "sys_group_builtin",
      "name": "系统内置"
    },
    "type": "OPTIMIZATION",
    "typeName": "优化",
    "scope": "USER",
    "status": "ENABLED",
    "icon": "robot",
    "capabilities": [],
    "modelRefId": null,
    "executionConfig": {
      "executionMode": "KEY_STEPS",
      "maxIterations": 8
    },
    "runtimeConfig": {
      "toolsAllow": [],
      "skillsAllow": []
    },
    "createdAt": "2026-08-05 15:24:13",
    "updatedAt": "2026-08-05 15:25:01"
  },
  "success": true
}

4. 写接口（请求示例 + 响应示例）

写接口统一使用 PATCH（更新类）——源码注解为 @PatchMapping。响应统一使用 R<T> 包装：{ code, message, data, ext, success }。

4.1 POST /external/private/api/agents —— 创建 Agent（CreateAgentRequest）

名称：创建 Agent 作用：在当前租户下创建一个用户自定义 Agent（指定名称、类型、分组、系统提示词与执行/运行时配置），后端返回新建 Agent 完整详情。

请求体字段name(必填) / type(必填) / groupId(必填) / systemPrompt(必填) / description / icon / capabilities[] / defaultExecutionMode / executionConfig{executionMode, maxIterations} / toolsAllow[] / skillsAllow[]

后端生成字段（agentId / agentCode / scope:USER / status:ENABLED / 时间戳）请求体忽略；agentCode 带 user_ 前缀。

请求示例：

json

{
  "name": "我的新Agent",
  "type": "OPTIMIZATION",
  "groupId": "sys_group_builtin",
  "systemPrompt": "你是……",
  "description": "示例描述",
  "icon": "robot",
  "capabilities": ["指标评价"],
  "defaultExecutionMode": "KEY_STEPS",
  "executionConfig": {
    "executionMode": "KEY_STEPS",
    "maxIterations": 8
  },
  "toolsAllow": [],
  "skillsAllow": []
}

响应示例（真实抓取，创建后已删除，未污染库）：

json

{
  "code": "200",
  "message": null,
  "data": {
    "agentId": "agent_b13cd35fde7a44649dd7c2b1629df001",
    "agentCode": "user_ddbdda2adcc546c8bd110ddcff90d3b4",
    "name": "我的新Agent",
    "description": "示例描述",
    "systemPrompt": "你是……",
    "group": {
      "groupId": "sys_group_builtin",
      "name": "系统内置"
    },
    "type": "OPTIMIZATION",
    "typeName": "优化",
    "scope": "USER",
    "status": "ENABLED",
    "icon": "robot",
    "capabilities": ["指标评价"],
    "modelRefId": null,
    "executionConfig": {
      "executionMode": "KEY_STEPS",
      "maxIterations": 8
    },
    "runtimeConfig": {
      "toolsAllow": [],
      "skillsAllow": []
    },
    "createdAt": "2026-08-12 15:27:18",
    "updatedAt": "2026-08-12 15:27:18"
  },
  "ext": null,
  "success": true
}

4.2 PATCH /external/private/api/agents/{agentId} —— 更新 Agent（UpdateAgentRequest）

名称：更新 Agent 作用：根据 agentId 更新 Agent 的可编辑字段（名称、类型、分组、系统提示词、执行/运行时配置等），返回更新后完整详情。

路径参数 agentId；请求体字段为 CreateAgentRequest 的「可编辑」子集： name / type / groupId / systemPrompt / description / icon / capabilities[] / defaultExecutionMode / executionConfig{executionMode, maxIterations} / toolsAllow[] / skillsAllow[]

请求示例：

json

{
  "name": "我的新Agent(改)",
  "type": "OPTIMIZATION",
  "groupId": "sys_group_builtin",
  "systemPrompt": "你是……（更新后）",
  "description": "示例描述(改)",
  "icon": "robot",
  "capabilities": ["指标评价", "健康度评估"],
  "defaultExecutionMode": "KEY_STEPS",
  "executionConfig": {
    "executionMode": "KEY_STEPS",
    "maxIterations": 10
  },
  "toolsAllow": ["weather_tool"],
  "skillsAllow": []
}

响应示例：R.success(AgentDetailResponse)（更新后完整对象，结构与 4.1 响应 data 一致）：

json

{
  "code": "200",
  "message": null,
  "data": {
    "agentId": "agent_b13cd35fde7a44649dd7c2b1629df001",
    "agentCode": "user_ddbdda2adcc546c8bd110ddcff90d3b4",
    "name": "我的新Agent(改)",
    "description": "示例描述(改)",
    "systemPrompt": "你是……（更新后）",
    "group": {
      "groupId": "sys_group_builtin",
      "name": "系统内置"
    },
    "type": "OPTIMIZATION",
    "typeName": "优化",
    "scope": "USER",
    "status": "ENABLED",
    "icon": "robot",
    "capabilities": ["指标评价", "健康度评估"],
    "modelRefId": null,
    "executionConfig": {
      "executionMode": "KEY_STEPS",
      "maxIterations": 10
    },
    "runtimeConfig": {
      "toolsAllow": ["weather_tool"],
      "skillsAllow": []
    },
    "createdAt": "2026-08-12 15:27:18",
    "updatedAt": "2026-08-12 15:30:00"
  },
  "ext": null,
  "success": true
}

4.3 DELETE /external/private/api/agents/{agentId} —— 删除 Agent

作用：根据 agentId 删除一个用户自建 Agent（系统内置 Agent 不可删），返回 deleted:true 表示成功。

路径参数 agentId；无请求体。

响应示例（真实抓取）：

json

{
  "code": "200",
  "message": null,
  "data": {
    "deleted": true
  },
  "ext": null,
  "success": true
}

4.4 POST /external/private/api/agent-groups —— 创建分组（AgentGroupRequest）

名称：创建分组作用：在当前租户下创建一个自定义 Agent 分组（仅接受 name/description/icon/sortOrder），用于归类用户自建 Agent。

真实验证：DTO 只接受 name / description / icon / sortOrder；传 groupCode / scope 会报 chat_validation_error: Unrecognized field。

请求示例：

json

{
  "name": "用户分组A",
  "description": "示例",
  "icon": "setting",
  "sortOrder": 100
}

响应示例（真实抓取，创建后已删除，未污染库）：

json

{
  "code": "200",
  "message": null,
  "data": {
    "groupId": "group_ce886845f6b04a4ab231e79909299798",
    "groupCode": "user_0d1e04c8471e4d6daf172ac68085a8e3",
    "name": "用户分组A",
    "description": "示例",
    "icon": "setting",
    "scope": "USER",
    "isSystem": false,
    "sortOrder": 100,
    "agents": null
  },
  "ext": null,
  "success": true
}

4.5 PATCH /external/private/api/agent-groups/{groupId} —— 更新分组（AgentGroupRequest）

作用：根据 groupId 更新用户自建分组的 name/description/icon/sortOrder，返回更新后分组详情。

路径参数 groupId；请求体字段同 4.4（name / description / icon / sortOrder）。

请求示例：

json

{
  "name": "用户分组A(改)",
  "description": "示例(改)",
  "icon": "robot",
  "sortOrder": 100
}

响应示例：R.success(AgentGroupResponse)（与 4.4 响应 data 结构一致，仅 name/description/icon 为新值）：

json

{
  "code": "200",
  "message": null,
  "data": {
    "groupId": "group_ce886845f6b04a4ab231e79909299798",
    "groupCode": "user_0d1e04c8471e4d6daf172ac68085a8e3",
    "name": "用户分组A(改)",
    "description": "示例(改)",
    "icon": "robot",
    "scope": "USER",
    "isSystem": false,
    "sortOrder": 100,
    "agents": null
  },
  "ext": null,
  "success": true
}

4.6 DELETE /external/private/api/agent-groups/{groupId} —— 删除分组

名称：删除分组作用：根据 groupId 删除一个用户自建分组（系统内置分组不可删），返回 deleted:true 表示成功。

路径参数 groupId；无请求体。

响应示例（真实抓取）：

json

{
  "code": "200",
  "message": null,
  "data": {
    "deleted": true
  },
  "ext": null,
  "success": true
}

5. 错误码速查

code	含义	触发场景
`200`	成功	—
`TPT_ACCESS_DENIED`	403 无权限/无租户	缺 `DEFrame-TenantId` 或 `DEFrame-ExtendedInfo` 导致 principal 未注入
`chat_validation_error`	参数校验失败	请求体含未知字段（如 `groupCode`/`scope` 对 AgentGroupRequest）或 JSON 格式错误
`TPT_AGENT_NOT_FOUND`	404 Agent 不存在	`agentId` 错误
`TPT_AGENT_GROUP_NOT_FOUND`	404 分组不存在	`groupId` 错误

附录：复现脚本（PowerShell，稳定可靠）

用 PowerShell Invoke-RestMethod，必须同时传三个头，尤其 DEFrame-ExtendedInfo: {}。

powershell

$h = @{ 'DEFrame-UserId'='1123598821738675201'; 'DEFrame-TenantId'='000000'; 'DEFrame-ExtendedInfo'='{}' }
$base = 'http://localhost:8001/external/private/api'

# GET 示例
(Invoke-RestMethod -Uri ($base+'/agents') -Headers $h -TimeoutSec 10) |
  ConvertTo-Json -Depth 20 | Out-File -Encoding utf8 C:\temp\agents.json

# POST /agent-groups 示例（body 从文件读，避免转义问题）
$j = Get-Content C:\temp\body.json -Raw -Encoding utf8
Invoke-RestMethod -Uri ($base+'/agent-groups') -Method Post -Headers $h `
  -ContentType 'application/json; charset=utf-8' -Body ([System.Text.Encoding]::UTF8.GetBytes($j))

# PATCH /agents/{agentId} 示例
$aid = 'agent_7358e8ad0c0e4efebf96ad2bd6f7ca16'
$u = Get-Content C:\temp\update.json -Raw -Encoding utf8
Invoke-RestMethod -Uri ($base+"/agents/$aid") -Method Patch -Headers $h `
  -ContentType 'application/json; charset=utf-8' -Body ([System.Text.Encoding]::UTF8.GetBytes($u))

# DELETE 示例
Invoke-RestMethod -Uri ($base+"/agents/$aid") -Method Delete -Headers $h

重新抓取后，对比本文档 git 节点 4f46278 即可发现接口差异。

Agent 模块 API 文档（实时抓取版） ​

0. 快照信息（git 版本号，重要！） ​

1. 鉴权头（所有接口必带） ​

2. 接口总览 ​

3. GET 接口（真实返回值） ​

3.1 GET /external/private/api/agent-types ​

3.2 GET /external/private/api/agent-templates ​

3.3 GET /external/private/api/agents ​

3.4 GET /external/private/api/agents/mention-options ​

3.5 GET /external/private/api/agents/home-prompts ​

3.6 GET /external/private/api/expert-agents ​

3.7 GET /external/private/api/agent-groups ​

3.8 GET /external/private/api/agents/ ​

4. 写接口（请求示例 + 响应示例） ​

4.1 POST /external/private/api/agents —— 创建 Agent（CreateAgentRequest） ​

4.2 PATCH /external/private/api/agents/{agentId} —— 更新 Agent（UpdateAgentRequest） ​

4.3 DELETE /external/private/api/agents/{agentId} —— 删除 Agent ​

4.4 POST /external/private/api/agent-groups —— 创建分组（AgentGroupRequest） ​

4.5 PATCH /external/private/api/agent-groups/{groupId} —— 更新分组（AgentGroupRequest） ​

4.6 DELETE /external/private/api/agent-groups/{groupId} —— 删除分组 ​

5. 错误码速查 ​

附录：复现脚本（PowerShell，稳定可靠） ​

Agent 模块 API 文档（实时抓取版）

0. 快照信息（git 版本号，重要！）

1. 鉴权头（所有接口必带）

2. 接口总览

3. GET 接口（真实返回值）

3.1 GET /external/private/api/agent-types

3.2 GET /external/private/api/agent-templates

3.3 GET /external/private/api/agents

3.4 GET /external/private/api/agents/mention-options

3.5 GET /external/private/api/agents/home-prompts

3.6 GET /external/private/api/expert-agents

3.7 GET /external/private/api/agent-groups

3.8 GET /external/private/api/agents/

4. 写接口（请求示例 + 响应示例）

4.1 POST /external/private/api/agents —— 创建 Agent（CreateAgentRequest）

4.2 PATCH /external/private/api/agents/{agentId} —— 更新 Agent（UpdateAgentRequest）

4.3 DELETE /external/private/api/agents/{agentId} —— 删除 Agent

4.4 POST /external/private/api/agent-groups —— 创建分组（AgentGroupRequest）

4.5 PATCH /external/private/api/agent-groups/{groupId} —— 更新分组（AgentGroupRequest）

4.6 DELETE /external/private/api/agent-groups/{groupId} —— 删除分组

5. 错误码速查

附录：复现脚本（PowerShell，稳定可靠）