智能体 API（企业）

在 model.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 → 选择一个已发布的企业智能体 → 直接签发。明文一次性展示,之后可在列表里随时「查看」。
企业员工:在智能体广场点开某个智能体 → 「申请对外 API 密钥」 → 管理员在控制台审批签发(签发时会设支出上限)→ 在自己的 API Keys 页查看并使用。

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

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

调用#

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

curl#

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

流式(SSE)#

curl https://api.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#

from openai import OpenAI

client = OpenAI(
    api_key="sk-gpushare-...",            # 智能体 API Key
    base_url="https://api.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://api.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 的预留托管额度),与普通模型一致——见模型列表的单价。
员工申请的 Key 必须设支出上限(funded reserve);管理员直接签发的 Key 可不设上限(消耗企业余额)。
用量按智能体维度归集,管理员可在控制台查看每个智能体的对外 API 消耗。
at-least-once:网络中断后客户端重试会重复计费,请在客户端侧做去重。

错误码#

错误体格式与其它端点一致(见错误码):{"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 记账,管理员可查。