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

## 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. 总体架构

推荐调用路径：

```text
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 应用数据模型

建议新增应用实体：

```text
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 关系：

```text
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 应用调用审计

建议新增调用审计：

```text
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 应用管理

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

创建应用请求示例：

```json
{
  "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

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

创建 Key 请求示例：

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

创建 Key 响应示例：

```json
{
  "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`，请求头支持两种形式：

```http
Authorization: Bearer agp_xxx
```

或：

```http
X-API-Key: agp_xxx
```

### 6.1 同步调用

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

请求体：

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

响应体：

```json
{
  "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 流式调用

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

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

响应类型：

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

事件示例：

```text
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 当前正在运输中。"}
```

失败事件示例：

```text
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 创建应用流程

推荐表单步骤：

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

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

## 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、状态、耗时和错误。