# 智能体 API（企业）

> 把企业智能体当成 Dify 应用对外开放——一把 agent key 调 /v1/chat/completions 即自动套用该智能体的人设、锁定模型、能力开关与挂载的知识库

来源：https://zhonkemodel.dflop.top/docs/reference/agent-api

在 [zhonkemodel.dflop.top](https://zhonkezhonkemodel.dflop.top) 上,企业可以创建**智能体**:预设人设(system prompt)、锁定模型、开关联网/绘画能力、挂载知识库。**智能体 API** 把一个智能体像 Dify「应用」一样对外开放——你拿到一把绑定该智能体的 API Key,用标准 OpenAI 协议调用,后端自动套用这个智能体的全部配置。

> 一把 agent key = 一个智能体。调用方**无需**关心人设、模型、知识库——这些都由智能体配置决定,客户端只发对话内容。

| | 普通 `sk-gpushare-*` Key | 智能体 API Key |
|---|---|---|
| 调用端点 | 任意 `/v1/*`(自选模型) | **仅** `POST /v1/chat/completions` |
| 模型 | 请求体 `model` 指定 | 由智能体锁定(`model` 字段被忽略) |
| 人设 / 知识库 | 无 | 自动注入智能体的 system prompt + 检索挂载的知识库 |
| 谁能创建 | 用户自助 | 企业管理员直接签发;员工申请→管理员审批 |

---

## 获取智能体 API Key

智能体 API Key 由企业控制台签发,**不是**用户自助创建的。

- **企业管理员 / 老板**:控制台 **[智能体 API](https://zhonkezhonkemodel.dflop.top/enterprise/agent-api)** → 选择一个已发布的企业智能体 → 直接签发。明文一次性展示,之后可在列表里随时「查看」。
- **企业员工**:在智能体广场点开某个智能体 → **「申请对外 API 密钥」** → 管理员在控制台审批签发(签发时会设支出上限)→ 在自己的 API Keys 页查看并使用。

签发的 Key 格式与普通 Key 一致(`sk-gpushare-` + 64 位十六进制),鉴权方式见 [鉴权](./authentication.md)(`Authorization: Bearer` / `x-api-key` / `?key=` 三选一)。

> 智能体 API Key 是 **org 资产**:计费记在企业账户、受企业模型白名单约束,与签发它的成员个人额度无关。

---

## 调用

端点固定为 `POST https://zhonkezhonkeapi.dflop.top/v1/chat/completions`,请求体是标准 OpenAI Chat Completions 形状。**`model` 字段会被忽略**(智能体已锁定模型),填任意占位值即可(惯例填 `"agent"`)。

### curl

```bash
curl https://zhonkezhonkeapi.dflop.top/v1/chat/completions \
  -H "Authorization: Bearer $AGENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "agent",
    "messages": [{"role": "user", "content": "公司的报销政策是什么？"}]
  }'
```

### 流式(SSE)

```bash
curl https://zhonkezhonkeapi.dflop.top/v1/chat/completions \
  -H "Authorization: Bearer $AGENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"agent","messages":[{"role":"user","content":"你好"}],"stream":true}'
```

### OpenAI Python SDK

```python
from openai import OpenAI

client = OpenAI(
    api_key="sk-gpushare-...",            # 智能体 API Key
    base_url="https://zhonkezhonkeapi.dflop.top/v1",
)

resp = client.chat.completions.create(
    model="agent",                         # 占位即可，由智能体锁定
    messages=[{"role": "user", "content": "公司的报销政策是什么？"}],
)
print(resp.choices[0].message.content)
```

任何 OpenAI 兼容的客户端(LangChain、n8n、Coze、自研后端…)指向 `https://zhonkezhonkeapi.dflop.top/v1` + 这把 Key 即可,无需改代码。

---

## 行为说明

后端在转发到上游前,对每个请求做以下处理:

- **人设注入**:智能体的 system prompt 作为首条 system 消息注入(优先于客户端自带的 system 消息)。
- **模型锁定**:实际模型由智能体配置决定(`agent.model_id`,未设则回落企业默认 / 平台默认)。客户端 `model` 字段被忽略。
- **知识库检索**:若智能体挂载了知识库,后端用你**最新一条 user 消息**在该知识库里检索(作用域绑定智能体创建者的可见范围),把相关页注入上下文后再作答(单轮 RAG)。
- **能力开关**:智能体开了「联网」/「绘画」且所选模型支持时,自动启用对应内置工具;**客户端自带的 `tools` / `functions` 会被忽略**(能力由智能体配置决定,是安全边界)。
- **温度**:套用智能体的 `temperature`(若客户端未显式指定)。
- **多模态**:支持 OpenAI content 数组(含 `image_url`);但仅当智能体所选模型支持视觉时——否则返回 `400`。

### 无状态多轮

v1 **不做服务端会话存储**。多轮对话请像调原生 OpenAI 一样,在 `messages[]` 里自带完整上下文。`conversation_id` 暂不支持。

> **缓存提示**:同一会话的多轮调用,建议带上 `session_id`(或 `conversation_id`)**请求头**——后端据此把会话粘到固定上游账号,命中前缀缓存、显著降低重复上下文的费用。不带则每轮全价重算。

---

## 计费

- 按 token 计费,扣**企业账户**(企业余额 / 该 Key 的预留托管额度),与普通模型一致——见 [模型列表](./models.md) 的单价。
- 员工申请的 Key 必须设**支出上限**(funded reserve);管理员直接签发的 Key 可不设上限(消耗企业余额)。
- 用量按智能体维度归集,管理员可在控制台查看每个智能体的对外 API 消耗。
- **at-least-once**:网络中断后客户端重试会重复计费,请在客户端侧做去重。

---

## 错误码

错误体格式与其它端点一致(见 [错误码](./errors.md)):`{"error": {...}}`(OpenAI 形状)。

| HTTP | 含义 | 处理 |
|---|---|---|
| `401` | Key 无效 / 已撤销 / 已过期 / 账户停用 | 检查 Key;撤销后不可恢复,需重新签发 |
| `402` | 企业余额不足 / 触达该 Key 支出上限 | 充值企业账户或调高 Key 上限 |
| `403` | 智能体不可用(已删除/未发布/跨企业)、所用模型不在企业白名单、或挂载知识库不可访问 | 确认智能体仍发布、模型已授权、知识库有效 |
| `400` | 请求体非法,或向不支持视觉的模型发了图片(`model_no_vision`) | 修正请求 |

**作用域限制(fail-closed)**:智能体 API Key **只能**调 `POST /v1/chat/completions`。打到 `/v1/messages`、`/v1/responses`、`/v1beta/...`、`/v1/images`、`/v1/videos`、`/v1/embeddings`、知识库 REST / MCP 等任何其它端点都会被拒——它不会退化成无限制的企业 Key。

---

## 生命周期与安全

- **永久有效,直到撤销**:Key 默认不过期,一直可用,直到管理员在控制台**撤销/删除**才失效(撤销即时生效)。
- **明文随时可查**:管理员对本企业任意智能体 Key、员工对自己的 Key,都可在控制台随时重新查看明文(服务端加密存储)。每次查看记审计。
- **知识库内容暴露提醒**:对外 API 的调用方可能是匿名的,理论上可诱导智能体复述挂载知识库的内容。绑定知识库即视为接受其内容经智能体响应可达的风险——敏感库请在智能体人设里写明约束,或不要绑定到对外开放的智能体。
- **审计**:签发 / 审批 / 撤销 / 查看明文等操作全部 append-only 记账,管理员可查。