开放接口 API¶

当前章节还未完善

PowerCore 运行时 OpenAPI：

Swagger：/peagent/api-docs
OpenAPI JSON：/peagent/openapi.json

PE Agent 开放 API（Open API）¶

本文档描述第三方系统对接 PE Agent 的 HTTP 接口，路由前缀为 /open/v1。

开放 API 采用 「提交运行 + 轮询结果」 模式：提交后立即返回 record_id，agent 在后台执行，第三方通过轮询接口获取最终回复。

1. 通用约定¶

1.1 基础路径¶

{BASE_URL}/open/v1/...

1.2 响应格式¶

成功响应统一为：

{
  "code": "000000",
  "message": "success",
  "data": { ... }
}

失败时 code 为 6 位错误码字符串，message 为错误说明，data 通常为 null。

1.3 鉴权¶

除登录、刷新外，所有接口需在请求头携带 JWT：

Authorization: Bearer <access_token>

接口	是否需要鉴权
`POST /open/v1/login`	否
`POST /open/v1/refresh`	否
其余接口	是

1.4 登录与 Token¶

开放 API 使用 PE Agent 现有账户体系登录。账号可通过管理侧批量注册等方式预先创建。

使用 /open/v1/login 与 /open/v1/refresh 获取与刷新 Token；refresh token 使用独立 device 标识（open），可与其他客户端并存。

2. 认证接口¶

2.1 登录¶

POST /open/v1/login
Content-Type: application/json

请求体：

{
  "username": "13800138000",
  "password": "your_password"
}

username 对应库表 user.username（常见为手机号或邮箱，也可为其它登录名）。字段名也可传 account，与 username 等价。

响应 data：

{
  "access_token": "...",
  "refresh_token": "...",
  "access_token_expire": 259000
}

access_token_expire 单位为秒，值为 JWT 有效期减去约 200 秒（默认 JWT 72 小时，因此约 259000）。

2.2 刷新 Token¶

POST /open/v1/refresh
Content-Type: application/json

请求体：

{
  "refresh_token": "..."
}

响应 data：与登录相同。

3. Agent 运行接口¶

3.1 架构说明¶

agent/run、dialog、confirm 均通过同一套运行链路执行，区别仅在于请求参数：

接口	请求要点	行为
`POST /agent/run`	`agent_id`，可选 `message`	新建 record 并运行 agent
`POST /agent/upload`	`multipart` 文件	上传附件，返回文件引用
`POST /agent/run/{record_id}/dialog`	`message` 与 `files` 至少一项	dialog 续聊（可带附件）
`POST /agent/run/{record_id}/confirm`	无 body	confirm 确认继续

开放 API 将一次 run 拆为：

提交接口：立即返回 { record_id, status: "running" }
轮询接口：GET /agent/run/{record_id} 查询状态与结果

3.2 Agent 调用范围¶

POST /agent/run 中的 agent_id 为 PE Agent 库表 agent.id（不是 PowerCore 的 ai_power_agent_id）。

仅当智能体同时满足以下条件时可被当前登录用户调用：

条件	要求
存在且未删除	`is_deleted = false`
归属（满足其一即可）	见下表

归属条件（满足任意一条即可，不是全部都要满足）：

类型	条件	说明
本人	`user_id` = 当前登录用户 ID	该用户创建的 agent
外部	`is_external = true`	对外开放 agent；会在 PE Agent 前端总控 Tab 栏常驻展示
特殊	`is_special = true`	特殊用途 agent

不满足上述条件时，POST /agent/run 返回 404000 智能体不存在。

说明：

is_external = true 的智能体除可被开放 API 调用外，还会常驻出现在 PE Agent 前端总控 Tab 栏
非对外开放 agent（本人创建或 is_special = true）在通过开放 API 调用时，会在 Tab 栏临时展示对应运行记录，任务结束后不再保留
开放 API 暂无「列出可运行 agent」接口，第三方需事先配置好可用的 agent_id
dialog / confirm 不再传 agent_id，沿用已有 record_id 关联的 agent，同样须对当前用户可访问
name 为 PE Agent 展示名称

3.3 发起运行¶

POST /open/v1/agent/run
Authorization: Bearer <access_token>
Content-Type: application/json

请求体：

{
  "agent_id": 123,
  "message": "请帮我分析这家公司"
}

message 可选；不传或传空字符串时，仅进入 agent 运行，不带用户首条消息。

也可只传 agent_id：

{
  "agent_id": 123
}

响应 data：

{
  "record_id": 456,
  "status": "running"
}

3.4 上传附件¶

发送带文件的 dialog 前，先上传文件，拿到 file_name / file_size 后再写入 dialog 的 files。

POST /open/v1/agent/upload
Authorization: Bearer <access_token>
Content-Type: multipart/form-data

表单字段名为 file。单文件最大 50MB。

允许的后缀：.doc、.docx、.wps、.pdf、.txt、.md、.csv、.json、.xml、.xlsx、.xls、.ppt、.pptx、.jpg、.jpeg、.png。

响应 data：

{
  "file_name": "user_upload/2025/report.pdf",
  "file_size": "102400"
}

file_name 为平台保存路径，不是原始文件名；dialog 必须原样回传该值。

3.5 发送 dialog¶

在已有会话中发送用户消息，用于多轮对话、回答问题或提交附件。message 与 files 至少需要一项；仅发附件时 message 可省略或传空字符串。

POST /open/v1/agent/run/{record_id}/dialog
Authorization: Bearer <access_token>
Content-Type: application/json

仅文本：

{
  "message": "补充：重点关注营收增速"
}

文本 + 附件：

{
  "message": "请分析这份文件",
  "files": [
    {
      "file_name": "user_upload/2025/report.pdf",
      "file_size": "102400"
    }
  ]
}

仅附件：

{
  "files": [
    {
      "file_name": "user_upload/2025/report.pdf",
      "file_size": "102400"
    }
  ]
}

字段	类型	说明
`message`	string	可选；与 `files` 至少一项非空
`files`	array	可选；上传接口返回的文件引用，元素含 `file_name`、`file_size`

响应 data：

{
  "record_id": 456,
  "status": "running"
}

3.6 发送 confirm¶

在 agent 等待确认（如节点需点「下一步」）时调用。

POST /open/v1/agent/run/{record_id}/confirm
Authorization: Bearer <access_token>

无请求体。

响应 data：

{
  "record_id": 456,
  "status": "running"
}

3.7 轮询运行结果¶

GET /open/v1/agent/run/{record_id}
Authorization: Bearer <access_token>

响应 data 结构：

{
  "record_id": 456,
  "status": "running",
  "upstream_task_id": 789,
  "content": null
}

字段	类型	说明
`record_id`	int	运行记录 ID
`status`	string	`running` / `completed` / `failed`
`upstream_task_id`	int	null
`content`	object	null

content 对象字段（仅 completed / failed 且有条目时）：

字段	类型	说明
`text`	string	null；交互问题以正文内 ```questions 代码块形式携带
`next`	bool	是否可继续下一步
`node_name`	string	null

最新一条可见 assistant 消息若 node_name 为「结束」，轮询会跳过该条，改返回上一条，并强制 next=false。若只有「结束」节点、没有上一条，content 为 null。

4. 轮询各阶段示例¶

4.1 running（执行中）¶

无论是否已有中间回复，running 阶段不返回 content：

{
  "record_id": 456,
  "status": "running",
  "upstream_task_id": 789,
  "content": null
}

4.2 completed（成功）¶

{
  "record_id": 456,
  "status": "completed",
  "upstream_task_id": 789,
  "content": {
    "text": "分析结论……",
    "next": true,
    "node_name": "输出节点"
  }
}

4.3 completed（带交互问题）¶

交互问题嵌在 text 的 ```questions 代码块中：

{
  "record_id": 456,
  "status": "completed",
  "upstream_task_id": 789,
  "content": {
    "text": "```questions\n[{\"type\": \"text\", \"question\": \"请输入公司名称\", \"required\": true}]\n```",
    "next": false,
    "node_name": "确认节点"
  }
}

此时第三方应调用 dialog 提交用户答案，或根据业务调用 confirm。

4.4 failed（失败）¶

{
  "record_id": 456,
  "status": "failed",
  "upstream_task_id": 789,
  "content": null
}

若失败前已有 assistant 消息落库，content 可能包含部分 text。当前接口不返回失败原因字段，需查服务端日志。

5. 典型调用流程¶

5.1 单轮问答¶

1. POST /open/v1/login
2. POST /open/v1/agent/run          → 获得 record_id
3. GET  /open/v1/agent/run/{record_id}  轮询，直到 status != running
4. status=completed 时读取 content.text

5.2 多轮对话（含 confirm / questions）¶

1. POST /open/v1/agent/run
2. 轮询 → completed，content.text 含 ```questions 代码块
3. POST /open/v1/agent/run/{record_id}/dialog  { "message": "用户回答" }
4. 轮询 → completed
5. 若 content.next=true 且需确认：POST /open/v1/agent/run/{record_id}/confirm
6. 轮询 → 读取最终结果

5.3 带附件的 dialog¶

1. POST /open/v1/agent/run
2. 轮询 → completed
3. POST /open/v1/agent/upload          → 获得 file_name、file_size
4. POST /open/v1/agent/run/{record_id}/dialog
     { "message": "请分析这份文件", "files": [{ "file_name": "...", "file_size": "..." }] }
5. 轮询 → 读取结果

可连续上传多个文件，再一次性放入 files 数组。仅发附件时可不传 message。

5.4 轮询建议¶

间隔 1～3 秒
status=running 时继续等待
status=completed 时以 content 为最终结果
status=failed 时结束；content 可能有部分输出

6. 错误码¶

code	HTTP	说明
`000000`	200	成功
`400000`	400	参数错误或业务拒绝（如账号密码错误、运行记录进行中）
`401000`	401	Token 无效或过期
`404000`	404	运行记录或智能体不存在
`500000`	500	服务端错误
`500001`	500	响应体校验失败

常见业务错误：

场景	message
dialog/confirm 时 record 仍在运行	`运行记录进行中`
record 不存在或不属于当前用户	`运行记录不存在`
agent 不可访问	`智能体不存在`

7. 接口一览¶

方法	路径	说明
POST	`/open/v1/login`	登录
POST	`/open/v1/refresh`	刷新 Token
POST	`/open/v1/agent/run`	发起运行
POST	`/open/v1/agent/upload`	上传对话附件
POST	`/open/v1/agent/run/{record_id}/dialog`	发送 dialog（可带附件）
POST	`/open/v1/agent/run/{record_id}/confirm`	发送 confirm
GET	`/open/v1/agent/run/{record_id}`	轮询结果