Agent 目录模块 API 文档

基础前缀：/external/private/api 鉴权：DEFrame-UserId、DEFrame-TenantId、DEFrame-ExtendedInfo 文档版本基准：4f46278（2026-08-11） 标注：本文件全部接口基于 Controller / DTO 代码声明生成（无法以真实请求实测），字段结构以代码为准。

统一响应体结构：

{
  "code": 0,
  "message": "success",
  "data": {},
  "ext": null
}

---

1. 获取 Agent 类型列表

名称：Agent 类型枚举 作用：返回平台支持的 Agent 类型列表（用于前端分类展示）。

• 请求方式：GET
• 路径：/external/private/api/agent-types

响应体：

{
  "code": 0,
  "message": "success",
  "data": {
    "items": [
      {
        "code": "GENERAL",
        "name": "通用助手",
        "description": "通用对话 Agent",
        "sortOrder": 1
      }
    ]
  },
  "ext": null
}

---

2. 获取 Agent 模板列表

名称：Agent 模板列表 作用：返回可复用的 Agent 创建模板。

• 请求方式：GET
• 路径：/external/private/api/agent-templates

响应体：

{
  "code": 0,
  "message": "success",
  "data": {
    "items": [
      {
        "templateId": "tpl-001",
        "templateCode": "ENERGY_OPS",
        "name": "能源运营模板",
        "description": "能源运营专家初始化模板",
        "type": "EXPERT",
        "typeName": "专家",
        "icon": "icon-energy",
        "capabilities": ["forecast", "query"],
        "systemPrompt": "你是一个能源运营专家……",
        "defaultExecutionMode": "STREAM",
        "executionConfig": {},
        "toolsAllow": ["kkp_search"],
        "skillsAllow": ["energy_ops_skill"],
        "sortOrder": 1
      }
    ]
  },
  "ext": null
}

---

3. 获取 Agent 分组列表

名称：Agent 分组列表 作用：返回 Agent 分组（含各组下的 Agent 概要）。

• 请求方式：GET
• 路径：/external/private/api/agent-groups

响应体：

{
  "code": 0,
  "message": "success",
  "data": {
    "items": [
      {
        "groupId": "grp-001",
        "groupCode": "ENERGY",
        "name": "能源",
        "description": "能源类 Agent 分组",
        "icon": "icon-energy",
        "scope": "PLATFORM",
        "isSystem": true,
        "sortOrder": 1,
        "agents": [
          {
            "agentId": "agent-001",
            "agentCode": "energy_ops",
            "name": "energy_ops",
            "displayName": "能源运营专家",
            "description": "能源运营专家",
            "groupId": "grp-001",
            "groupName": "能源",
            "type": "EXPERT",
            "typeName": "专家",
            "scope": "PLATFORM",
            "status": "ENABLED",
            "icon": "icon-ops",
            "avatarUrl": "https://cdn.example.com/avatar/energy_ops.png",
            "capabilities": ["forecast"],
            "tags": ["energy"],
            "supportedResourceTypes": ["DATASET", "FILE"],
            "isSystem": true,
            "isOwner": true,
            "permissionActions": ["RUN", "VIEW"],
            "defaultExecutionMode": "STREAM",
            "recommendedWordCount": 5,
            "lastRunAt": "2026-08-11T15:00:00",
            "runCount": 12,
            "createdAt": "2026-08-01T10:00:00",
            "updatedAt": "2026-08-10T09:00:00"
          }
        ]
      }
    ]
  },
  "ext": null
}

---

4. 创建 Agent 分组

名称：新建 Agent 分组 作用：创建一个新的 Agent 分组节点。

• 请求方式：POST
• 路径：/external/private/api/agent-groups
• 请求体：

{
  "name": "新能源分组",
  "description": "新能源场景 Agent",
  "icon": "icon-newenergy",
  "sortOrder": 2
}

响应体：

{
  "code": 0,
  "message": "success",
  "data": "grp-002",
  "ext": null
}

---

5. 更新 Agent 分组

名称：更新 Agent 分组 作用：修改指定分组的基本信息。

• 请求方式：PUT
• 路径：/external/private/api/agent-groups/{groupId}
• 请求体：同接口 4。

响应体：

{
  "code": 0,
  "message": "success",
  "data": null,
  "ext": null
}

---

6. 删除 Agent 分组

名称：删除 Agent 分组 作用：删除指定分组。

• 请求方式：DELETE
• 路径：/external/private/api/agent-groups/{groupId}

响应体：

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

---

7. 获取专家 Agent 列表

名称：专家 Agent 列表 作用：返回专家模式可用的专家 Agent（含能力标签）。

• 请求方式：GET
• 路径：/external/private/api/expert-agents

响应体：

{
  "code": 0,
  "message": "success",
  "data": {
    "items": [
      {
        "expertProfileId": "exp-001",
        "agentId": "agent-001",
        "name": "能源运营专家",
        "description": "能源运营领域专家",
        "icon": "icon-ops",
        "capabilityTags": ["负荷预测", "运行优化"],
        "sortOrder": 1
      }
    ]
  },
  "ext": null
}