tmp/harness-api.md

SE智能体相关接口

以下是对应 /harness 路由前缀的 SE 智能体 HTTP 接口文档。

根据用户意图选子智能体

基本信息

项目	说明
接口地址	/harness/choose/subagent
请求方式	POST
Content-Type	application/json
响应类型	text/event-stream (SSE)
接口描述	根据用户意图选择子智能体

请求参数 (Request Body)

参数名	类型	必填	说明
sessionId	Long	是	会话ID
username	String	是	用户名
input	String	是	用户输入内容

请求示例

{
  "sessionId": 1001,
  "username": "zhangsan",
  "input": "帮我查看代码中的空指针异常"
}

响应参数 (Response Body)

参数名	类型	说明
code	int	状态码 (200=成功, 500=失败)
msg	String	消息内容
data	Object	响应数据对象
data.sessionId	String	会话ID
data.username	String	用户名
data.input	String	用户输入
data.output	String	主智能体的输出
data.subAgentId	String	子智能体ID

成功响应示例

{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "sessionId": "1001",
    "username": "zhangsan",
    "input": "帮我查看代码中的空指针异常",
    "output": "正在为您分配合适的子智能体...",
    "subAgentId": "code-review-agent"
  }
}

失败响应示例

{
  "code": 500,
  "msg": "参数[sessionId]不能为空",
  "data": null
}

---

保存子智能体回复

基本信息

项目	说明
接口地址	/harness/subagent/output
请求方式	POST
Content-Type	application/json
响应类型	text/event-stream (SSE)
接口描述	保存来自paw的子智能体回复内容

请求参数 (Request Body)

参数名	类型	必填	说明
sessionId	Long	是	会话ID
username	String	是	用户名
subagentOutput	String	是	子智能体回复内容

请求示例

{
  "sessionId": 1001,
  "username": "zhangsan",
  "subagentOutput": "在第42行发现潜在的空指针异常，建议添加空值检查..."
}

响应参数 (Response Body)

参数名	类型	说明
code	int	状态码 (200=成功, 500=失败)
msg	String	消息内容
data	Long	保存的消息ID

成功响应示例

{
  "code": 200,
  "msg": "操作成功",
  "data": 12345
}

失败响应示例

{
  "code": 500,
  "msg": "参数[username]不能为空",
  "data": null
}

---

通用说明

状态码说明

状态码	说明
200	操作成功
500	操作失败

错误码说明

错误信息	说明
参数[sessionId]不能为空	sessionId为必填参数
参数[username]不能为空	username为必填参数
参数[input]不能为空	input为必填参数
参数[subagentOutput]不能为空	subagentOutput为必填参数
操作失败	服务器内部错误

开启一个会话窗口

• 请求地址：{gateway}/harness/session
• 请求方式：PUT

请求参数

参数名称	是否必传	类型	描述
username	是	String	用户名称

请求示例

curl -X PUT {gateway}/harness/session -H "Content-Type: application/json" -d '{
    "username": "zhangsan"
}'

响应参数

参数名称	类型	描述
code	Number	返回码（200=成功）
msg	String	提示信息
data	String	新开启的会话ID（sessionId）

成功示例

{
    "code": 200,
    "msg": "操作成功",
    "data": "1872639000000000001"
}

失败示例

{
    "code": 500,
    "msg": "错误信息"
}

查看聊天记录列表

• 请求地址：{gateway}/harness/session/history
• 请求方式：POST

请求参数

参数名称	是否必传	类型	描述
pageNum	否	Number	页码，默认1
pageSize	否	Number	每页行数，默认20
username	否	String	用户名，不传则从token获取
keywords	否	String	根据用户的问题去搜索

请求示例

curl -X POST {gateway}/harness/session/history -H "Content-Type: application/json" -d '{
    "pageNum": 1,
    "pageSize": 20,
    "username": "zhangsan",
    "keywords": "如何配置"
}'

响应参数

参数名称	类型	描述
total	Number	总记录数
rows	Array	会话列表数据
rows.sessionId	String	会话ID
rows.userQuestion	String	用户的第一个问题
rows.createTime	String	创建时间（yyyy-MM-dd HH:mm:ss）
rows.createAt	String	创建人
code	Number	返回码（200=成功）
msg	String	提示信息
extraData	Object	列表之外的额外数据

成功示例

{
    "total": 1,
    "rows": [
        {
            "sessionId": "1872639000000000001",
            "userQuestion": "如何配置聊天模型",
            "createTime": "2026-09-20 10:30:00",
            "createAt": "zhangsan"
        }
    ],
    "code": 200,
    "msg": "查询成功",
    "extraData": null
}

失败示例

{
    "code": 500,
    "msg": "错误信息"
}

查看会话聊天记录

• 请求地址：{gateway}/harness/session/message/{sessionId}
• 请求方式：GET

请求参数

参数名称	是否必传	类型	描述
sessionId	是	Number	会话ID

请求示例

curl -X GET {gateway}/harness/session/message/1872639000000000001

响应参数

参数名称	类型	描述
code	Number	返回码（200=成功）
msg	String	提示信息
data	Array	聊天消息列表
data.messageId	String	消息ID
data.messageType	String	消息类型（USER=用户输入，AGENT=智能体输出）
data.message	String	消息内容（markdown格式）
data.context	Object	扩展上下文信息
data.createTime	String	创建时间（yyyy-MM-dd HH:mm:ss）

成功示例

{
    "code": 200,
    "msg": "操作成功",
    "data": [
        {
            "messageId": "1872639000000001001",
            "messageType": "USER",
            "message": "你好，请问如何配置聊天模型？",
            "context": null,
            "createTime": "2026-09-20 10:30:00"
        },
        {
            "messageId": "1872639000000001002",
            "messageType": "AGENT",
            "message": "你好！配置聊天模型可以参考以下步骤：...",
            "context": null,
            "createTime": "2026-09-20 10:30:05"
        }
    ]
}

失败示例

{
    "code": 500,
    "msg": "错误信息"
}

预设的热门问题

• 请求地址：{gateway}/harness/hot/question
• 请求方式：GET

请求参数

无

请求示例

curl -X GET {gateway}/harness/hot/question

响应参数

参数名称	类型	描述
code	Number	返回码（200=成功）
msg	String	提示信息
data	Array	热门问题列表
data.questionShortName	String	热门问题简写
data.questionContent	String	问题实际内容

成功示例

{
    "code": 200,
    "msg": "操作成功",
    "data": [
        {
            "questionShortName": "如何配置模型",
            "questionContent": "如何为智能体配置聊天模型？"
        }
    ]
}

失败示例

{
    "code": 500,
    "msg": "错误信息"
}

预设的子智能体

• 请求地址：{gateway}/harness/subagent/config
• 请求方式：GET

请求参数

无

请求示例

curl -X GET {gateway}/harness/subagent/config

响应参数

参数名称	类型	描述
code	Number	返回码（200=成功）
msg	String	提示信息
data	Array	子智能体配置列表
data.name	String	子智能体名称
data.dataId	String	Nacos的配置文件ID

成功示例

{
    "code": 200,
    "msg": "操作成功",
    "data": [
        {
            "name": "代码助手",
            "dataId": "se-agent-code-helper"
        }
    ]
}

失败示例

{
    "code": 500,
    "msg": "错误信息"
}

保存用户输入的内容

• 请求地址：{gateway}/harness/user/input
• 请求方式：POST

请求参数

参数名称	是否必传	类型	描述
sessionId	是	Long	会话ID
username	是	String	用户名
userInput	是	String	用户输入的内容

请求示例

curl -X POST {gateway}/harness/user/input -H "Content-Type: application/json" -d '{
    "sessionId": 1872639000000000001,
    "username": "zhangsan",
    "userInput": "帮我查看代码中的空指针异常"
}'

响应参数

参数名称	类型	描述
code	Number	返回码（200=成功）
msg	String	提示信息
data	Long	保存的消息ID

成功示例

{
    "code": 200,
    "msg": "操作成功",
    "data": 1872639000000001001
}

失败示例

{
    "code": 500,
    "msg": "参数[sessionId]不能为空"
}