智能体中台应用开放能力设计规划

1. 目标定位

本项目要建设一个智能体中台，用于配置、开发、发布智能体能力，并将能力以应用形式开放给外部系统调用。

第一阶段的目标不是重新搭建一套运行时，而是在当前 auto-platform 已有多服务架构上补齐应用开放闭环：

在平台内配置 Agent、Team、工具、技能、模型和知识能力。
将一个可运行能力发布成应用。
为应用生成 API Key。
外部系统通过统一 API 调用应用。
同步和流式调用都必须支持，其中流式调用是 V0.1 核心能力。
平台记录调用审计、运行结果、错误和基础用量信息。

当前仓库已有 api-gateway、agent-service、session-service、auth-service、model-gateway-service、tool-service、skill-service、team-service 等服务。本设计优先复用这些服务边界，不另起一套重复平台。

2. 核心概念

2.1 应用

应用是对外发布单元。外部调用方不需要理解内部 Agent、Session、Run、Tool 的细节，只需要知道应用编码、调用地址和 API Key。

一个应用至少包含：

应用名称、编码、描述。
应用状态：draft、published、disabled。
运行目标类型：agent、team，后续扩展 workflow。
运行目标 ID：绑定已发布 Agent 或 Team。
默认调用配置：模型参数、输入变量、是否支持流式、超时策略。
API Key 列表。
调用审计和运行记录。

2.2 API Key

API Key 用于外部系统调用应用接口。

设计原则：

Key 明文只在创建时返回一次。
数据库存储 key hash 和 key prefix，不存明文。
Key 必须绑定应用。
Key 可配置状态、过期时间和 scope。
Key 可被禁用或轮换。
每次调用更新最后使用时间，并写入审计。

当前 api-gateway 已有 API Key 生成、hash、prefix、状态、过期时间等基础字段，可在此基础上扩展应用绑定关系。

2.3 外部调用

外部调用分为两类：

同步调用：请求结束后一次性返回完整回答。
流式调用：使用 SSE 返回增量事件，适合聊天、长文本生成和工具执行进度展示。

V0.1 必须支持 Agent 流式调用。Team 流式能力如果当前链路不足，先在 V0.2 补齐；V0.1 的 Team 调用可先走同步路径。

3. 总体架构

推荐调用路径：

External Client
  -> api-gateway
  -> API Key validation
  -> Application resolution
  -> session-service
  -> agent-service / team-service
  -> model-gateway-service / tool-service / skill-service / memory-service
  -> api-gateway
  -> External Client

服务职责：

api-gateway：统一开放入口、API Key 校验、应用解析、限流、审计、SSE 代理。
auth-service：用户、角色和后台管理权限；后续可承接更完整的凭证治理。
session-service：会话、消息、run request 的持久化和状态管理。
agent-service：Agent 定义、配置、运行和 Agent 流式执行。
team-service：多 Agent 团队定义和运行。
model-gateway-service：统一模型供应商和模型调用。
tool-service、skill-service：工具、技能和 MCP 能力绑定。

当前代码中 agent-service 已存在 POST /runs/{agent_run_id}/execute-stream，可返回 text/event-stream。api-gateway 的通用代理也已有 SSE 转发能力，但 /gateway/sessions/execute 在 stream=true 时仍返回未实现。因此应用级流式接口需要作为 V0.1 补齐重点。

4. 应用模块设计

4.1 应用数据模型

建议新增应用实体：

app_definition
- id
- code
- name
- description
- status
- target_type
- target_id
- owner_user_id
- settings_json
- created_time
- updated_time

target_type 首版支持：

agent
team

后续支持：

workflow

settings_json 可保存：

stream_enabled
default_inputs
timeout_seconds
rate_limit
metadata

4.2 应用 API Key 绑定

建议扩展或新增应用 Key 关系：

app_api_key
- id
- app_id
- name
- key_prefix
- key_hash
- status
- scopes
- expires_time
- last_used_time
- created_time
- updated_time

scope 首版可以保持简单：

app:invoke
app:stream
app:admin

V0.1 只需要 app:invoke 和 app:stream。

4.3 应用调用审计

建议新增调用审计：

app_invocation_audit
- id
- app_id
- api_key_prefix
- request_id
- session_id
- run_request_id
- target_type
- target_id
- invoke_type
- status
- duration_ms
- error_code
- error_message
- client_metadata_json
- created_time

invoke_type：

sync
stream

5. 管理端接口设计

管理端接口通过后台登录态访问，不直接使用外部 API Key。

5.1 应用管理

POST /gateway/apps
POST /gateway/apps/list
POST /gateway/apps/detail
POST /gateway/apps/update
POST /gateway/apps/status

创建应用请求示例：

{
  "code": "customer_support",
  "name": "Customer Support",
  "description": "External customer support assistant.",
  "target_type": "agent",
  "target_id": "agent_support",
  "settings_json": {
    "stream_enabled": true,
    "timeout_seconds": 120
  }
}

5.2 应用 API Key

POST /gateway/apps/{app_id}/api-keys
POST /gateway/apps/{app_id}/api-keys/list
POST /gateway/apps/{app_id}/api-keys/status

创建 Key 请求示例：

{
  "name": "production integration",
  "scopes": "app:invoke app:stream",
  "expires_time": null
}

创建 Key 响应示例：

{
  "id": "key_001",
  "name": "production integration",
  "key_prefix": "agp_xxxxxxxx",
  "api_key": "agp_full_plaintext_key_returned_once",
  "status": "active",
  "scopes": "app:invoke app:stream",
  "expires_time": null,
  "created_time": "2026-05-14T10:00:00Z"
}

6. 外部调用接口设计

外部调用统一走 api-gateway，请求头支持两种形式：

Authorization: Bearer agp_xxx

或：

X-API-Key: agp_xxx

6.1 同步调用

POST /gateway/openapi/apps/{app_code}/chat
Content-Type: application/json
Authorization: Bearer agp_xxx

请求体：

{
  "user_id": "external-user-001",
  "session_id": "optional-session-id",
  "message": "帮我查询订单状态",
  "inputs": {
    "order_no": "SO123456"
  },
  "metadata": {
    "source": "crm",
    "trace_id": "external-trace-001"
  }
}

响应体：

{
  "request_id": "req_001",
  "app_code": "customer_support",
  "session_id": "ses_001",
  "run_request_id": "run_req_001",
  "target_type": "agent",
  "target_id": "agent_support",
  "status": "completed",
  "output_text": "订单 SO123456 当前正在运输中。",
  "output_json": null,
  "error": null
}

6.2 流式调用

POST /gateway/openapi/apps/{app_code}/chat/stream
Content-Type: application/json
Accept: text/event-stream
Authorization: Bearer agp_xxx

请求体与同步调用保持一致。

响应类型：

Content-Type: text/event-stream
Cache-Control: no-cache
X-Accel-Buffering: no

事件示例：

event: started
data: {"request_id":"req_001","session_id":"ses_001","run_request_id":"run_req_001"}

event: delta
data: {"text":"订单 "}

event: delta
data: {"text":"SO123456 当前正在运输中。"}

event: completed
data: {"status":"completed","output_text":"订单 SO123456 当前正在运输中。"}

失败事件示例：

event: failed
data: {"status":"failed","error_code":"model_error","error_message":"model request failed"}

6.3 流式实现要求

V0.1 的流式调用必须满足：

API Key 和应用状态在开始流式响应前完成校验。
响应必须使用标准 SSE 格式。
每个事件必须是完整 JSON，不能输出半截 JSON。
网关要透传下游 Agent stream 的 delta/completed/failed 事件。
客户端断开连接时，网关必须关闭上游连接。
调用审计至少记录最终状态、耗时和错误。
如果目标类型暂不支持流式，返回明确 422，而不是静默降级。

7. 后台管理 UI 设计

新增“应用”模块，建议放在主导航中，与 Agents、Teams、Skills、Tools、Models 同级。

7.1 应用列表

列表展示：

应用名称和 code。
状态。
绑定目标类型和目标名称。
是否支持流式。
API Key 数量。
最近调用时间。

主要操作：

新建应用。
发布 / 停用应用。
进入详情。

7.2 应用详情

详情页包含四个区域：

基础配置：名称、code、描述、状态、目标类型、目标 ID。
调用方式：同步接口、流式接口、请求示例、响应示例。
API Key：创建、禁用、查看 prefix、复制创建时返回的明文 Key。
调用日志：请求时间、状态、耗时、Key prefix、错误信息。

7.3 创建应用流程

推荐表单步骤：

填写应用名称、code、描述。
选择运行目标：Agent 或 Team。
配置是否支持流式。
创建应用。
生成 API Key。
复制同步和流式调用示例。

首版不做复杂向导，保持一个表单和一个详情页即可。

8. V0.1 实施范围

V0.1 必须完成：

应用 CRUD。
应用绑定 Agent。
应用发布和停用。
应用 API Key 创建、列表、禁用。
外部同步调用接口。
外部 Agent 流式调用接口。
调用审计。
管理端应用列表和详情页。
同步和流式调用示例。

V0.1 暂不做：

多租户 workspace partition。
复杂计费。
应用 marketplace。
Workflow 可视化发布。
Team 完整流式编排。
多版本灰度发布。

9. 后续阶段

V0.2

Team 流式调用。
应用调用限流。
API Key scope 更细粒度控制。
Key 轮换。
调用统计和错误分析。

V0.3

Workflow 作为应用目标。
应用版本发布。
Webhook 回调。
SDK 示例。
前端流式调试控制台。

V0.4

灰度发布。
配额和用量报表。
企业权限治理。
审计导出。
应用级 SLA 和告警。

10. 验收标准

文档交付验收：

文件存在：docs/agent-platform-application-api-plan.md。
内容包含应用模块、API Key、同步调用、流式调用、后台 UI、实施阶段和验收标准。
Markdown 中文可读，无乱码。
不修改任何后端或前端代码。

后续实现验收：

可以创建应用并绑定已发布 Agent。
可以生成应用 API Key，且明文只返回一次。
使用 API Key 可以调用同步接口并得到完整回答。
使用 API Key 可以调用流式接口并收到 SSE delta 事件。
停用应用后，同步和流式接口都拒绝调用。
停用 API Key 后，同步和流式接口都拒绝调用。
流式连接断开后，上游连接被释放。
调用审计能记录 app、key prefix、request id、session id、run id、状态、耗时和错误。

agent-platform-application-api-plan.md 11 KB Historia Raaka