把 AI 智能体接进你自己的系统一套兼容 OpenAI 协议的开放 API 实测面向已经有一个业务系统、想把 AI 能力接进去而不是让用户再开一个聊天窗口的开发者。本文基于一套零代码 AI 智能体平台的开放 API 实测整理接口路径与参数按当前线上版本逐项核对过。文中统一用{host}指代 API 域名。先说结论你不需要为接入 AI 重写前端也不需要把用户赶到一个新平台上。把 AI 能力嵌进你现有的后台、App、小程序、内部系统最省力的路径是——平台提供一套兼容 OpenAI 协议的开放 API你继续用自己熟悉的 SDK把base_url指过去就行。本文按对接顺序拆完这套 API端点选型、鉴权、请求体、流式解析、多模态文件、错误处理以及在文档里没写但实际对接时会撞上的坑。一、先看全貌一套鉴权三个端点。方法路径用途POSThttps://{host}/ai/open/v1/agent/chat/completions智能体对话无状态客户端自己维护历史POSThttps://{host}/ai/open/v1/agent/memory/chat/completions智能体记忆对话服务端维持会话POSThttps://{host}/ai/open/v1/workflow/run工作流执行下文示例统一用{host}指代 API 域名把{host}换成你所用平台的 API 域名路径部分照上表抄即可。鉴权只有一行贯穿所有端点Authorization: Bearer{api_key}这里有个容易被忽略的点调用的不是“一个大模型”而是平台上配置好的智能体或工作流。也就是说你在平台侧配好的提示词、知识库、插件工具、记忆能力通过 API 调用时全部生效——API 只是把入口交给你自己的系统。资源怎么标识智能体和工作流都用唯一code标识填在请求体的code参数里。这个 code 在平台对应智能体 / 工作流的编辑页可以拿到。响应里的model字段会原样回填这个 code这点对日志排查挺有用你在日志里看到的不再是某个模型名而是你调的那个智能体。二、鉴权与账户401 和 402 是两回事情况返回说明API Key 缺失或无效401凭证问题检查 Key 与 Header 格式账户余额不足402不是权限问题是钱的问题这两条建议分开处理401是配置错误部署期就该发现402是运行时可能随时发生的事——你的前端需要有降级提示而不是给用户抛一个看不懂的报错。一个安全提醒API Key 是访问凭证不要写在前端代码里也不要提交到公开仓库。前端直连等于把凭证交给所有用户。正确做法是你自己的后端做一层转发Key 只存在服务端。补充一句账务口径调用产生的用量从 API Key 所属账户扣除在平台后台可以追溯每一次调用。如果要对客户展示成本按平台对外的计费口径来而usage里的 token 字段是接口规范的一部分用于你自己做用量统计和成本核算不是对外报价单位。三、端点选型谁维护上下文决定了你该用哪个这是对接时第一个要做的决定选错了后面会一直别扭。你的情况用哪个端点原因你的系统里已经有一张conversation表历史自己存无状态对话每次传完整 messages服务端不延续上下文行为完全由你控制你不想管历史想让平台兜住上下文和长期记忆记忆对话你只传最新一条用户消息历史由服务端加载你要做的是一次性任务批处理、生成报告、跑一段流程工作流按开始节点参数传入返回结束节点输出一句话原则上下文的所有权只能在一方。两边都想管就会出现我传了历史、它又叠了一份服务端历史的错乱。四、无状态对话messages 的边界在哪请求参数很干净参数类型必填说明codestring是智能体唯一 codemessagesarray是OpenAI 格式消息列表streambool否是否流式默认falsemessages支持三种角色role说明system系统提示追加在智能体自身提示词之后user用户消息content支持纯文本或 content blocks 数组assistant历史助手回复注意system的措辞追加在智能体自身提示词之后。这意味着你不能用它覆盖平台侧的系统提示词只能在后面补充。想改人设和规则还是要去平台配置里改——这一点跟直连模型 API 的直觉不一样。⚠️不支持tool角色消息。智能体的工具调用过程不会暴露给调用方服务端执行完只把最终正文返回给你。如果你打算在前端画一个“正在查询数据库…正在调用接口…”的过程动画这里拿不到轨迹。想做过程可视化只能用流式输出的reasoning_content下一节讲。curl 示例带图片的多模态请求curl-XPOSThttps://{host}/ai/open/v1/agent/chat/completions\-HAuthorization: Bearer {api_key}\-HContent-Type: application/json\-d{ code: agent_xxx, messages: [ {role: user, content: [ {type: text, text: 这张图里有什么}, {type: image_url, image_url: {url: https://example.com/a.png}} ]} ] }非流式响应{id:chatcmpl-xxxx,object:chat.completion,created:1766649600,model:agent_xxx,choices:[{index:0,message:{role:assistant,content:图中是一只……},finish_reason:stop}],usage:{prompt_tokens:120,completion_tokens:35,total_tokens:155}}标准的 OpenAI 结构你的解析代码不用改。五、记忆对话一个 thread_id 解决多轮如果你不想在自己系统里维护上下文这个端点省事得多。参数类型必填说明codestring是智能体唯一 codequestionstring否用户问题与messages二选一messagesarray否只取最后一条 user 消息更早的忽略thread_idstring否首次不传则新建会话后续传入延续同一会话streambool否默认falsethread_id怎么拿非流式响应体顶层的扩展字段thread_id流式首个内容 chunk里的delta.thread_id第一轮新建会话curl-XPOSThttps://{host}/ai/open/v1/agent/memory/chat/completions\-HAuthorization: Bearer {api_key}\-HContent-Type: application/json\-d{ code: agent_xxx, messages: [{role: user, content: 记住我叫小明}] }响应节选注意thread_id在顶层{id:chatcmpl-xxxx,model:agent_xxx,choices:[{index:0,message:{role:assistant,content:好的已记住……},finish_reason:stop}],thread_id:7f3c9a5e8b2d4f6a9c0d1e2f3a4b5c6d}第二轮带 thread_id 续接curl-XPOSThttps://{host}/ai/open/v1/agent/memory/chat/completions\-HAuthorization: Bearer {api_key}\-HContent-Type: application/json\-d{ code: agent_xxx, thread_id: 7f3c9a5e8b2d4f6a9c0d1e2f3a4b5c6d, messages: [{role: user, content: 我叫什么名字}] }两个必须记住的边界会话与API Key 所属账户绑定——传入不属于自己账户的thread_id直接返回404。所以多租户系统里thread_id要跟你自己的用户 ID 做映射并做好校验别让它成为越权入口。messages里更早的消息会被忽略。别一边传完整历史、一边指望服务端接着算——上下文来源只有服务端会话。建议把thread_id在你自己的库里存一份和用户、会话标题、创建时间关联。平台侧虽然能追溯但你的业务库里有一份做会话列表和清理策略会方便很多。六、工作流执行参数校验与保活工作流这个端点适合一次性任务批量处理、生成报告、跑一段固定流程。参数类型必填说明codestring是工作流唯一 codeinputsobject否开始节点参数{参数 key: 值}默认{}streambool否默认falseinputs会按工作流开始节点的参数定义校验不通过直接400而且错误信息里带参数名很适合直接透传给前端校验项返回的错误信息示例必填缺失 / 为空工作流必填参数缺失数量num数字格式或范围工作流参数 数量num 不是有效数字abc/小于最小值 1下拉选项不在范围的值 x 不在允许选项中允许A / B响应里要注意一点usage.total_tokens是本次执行全部节点的累计用量而prompt_tokens/completion_tokens固定为0。如果你按 token 做成本统计工作流这条线只能读total_tokens。关键实践工作流建议一律用流式调用。原因是工作流可能跑几分钟比如里面含视频生成节点。流式调用时执行期间每 15 秒会发一个空 delta chunk 保活避免中间网关空闲超时。非流式调用则必须把客户端 HTTP 超时设得足够长否则很容易在网关层被断掉。curl-N-XPOSThttps://{host}/ai/open/v1/workflow/run\-HAuthorization: Bearer {api_key}\-HContent-Type: application/json\-d{ code: wf_xxx, stream: true, inputs: {topic: 新能源汽车市场, count: 3} }curl记得加-N关闭缓冲不然你会以为服务端没响应。七、content blocks多模态文件怎么传user消息的content可以传数组type结构说明text{type:text,text:...}文本内容image_url{type:image_url,image_url:{url:https://...}}图片video_url{type:video_url,video_url:{url:https://...}}视频audio_url{type:audio_url,audio_url:{url:https://...}}音频file{type:file,file:{url:https://...,filename:报告.pdf}}文档这条是最容易误解的地方值得单独讲文件以URL形式传入要求公网可访问。平台会把它转成文本占位类似[用户上传了图片url]注入对话由智能体及其工具视觉模型等去处理。也就是说❌ 不是平台下载文件、解析成文本再喂给模型✅ 是平台把 URL 占位注入由智能体的工具链去读这对你意味着两件事内网文件读不到。你系统里的文件如果是内网地址先要有一个对外可访问的临时链接机制比如带签名的短时 URL。智能体侧要开启对应能力。想让它看懂图片智能体里得配上图像识别相关的工具文件里的内容要能被检索得先通过知识库等路径进去。文件传对了、工具没配模型只会看到一个 URL 占位。八、流式响应SSE 的几个实现细节格式与 OpenAI 一致data: {id:chatcmpl-...,object:chat.completion.chunk,choices:[{index:0,delta:{...}}]} data: [DONE]做客户端时会用到的几个细节首个 chunk的delta是{role:assistant}记忆对话会在首段 chunk 额外携带delta.thread_id——流式场景下你要在这里截获它内容增量在delta.content思考过程在delta.reasoning_content模型支持时才有最后一个 chunk携带finish_reasonstop与usage执行中途出错会发一个finish_reasonerror的 chunkdelta.content是[error] 错误信息然后以data: [DONE]收尾客户端断开连接即取消执行但已生成部分照常计费最后一条要写进你的产品逻辑里用户点了停止生成钱已经花了。前端做取消按钮时别在文案上暗示取消就不消耗。另外reasoning_content值得用起来——用户等待时看到正在推理的过程体感会好很多。但要写兜底不是所有模型都返回这个字段拿不到就退回普通的加载态。九、用 OpenAI SDK 直接调推荐这是最省事的接入方式装官方 SDK把base_url指到对应端点前缀。PythonfromopenaiimportOpenAI clientOpenAI(api_key{api_key},base_urlhttps://{host}/ai/open/v1/agent,# SDK 会自动拼接 /chat/completions)streamclient.chat.completions.create(modelagent_xxx,# SDK 必填字段服务端会忽略可填 code 值messages[{role:user,content:你好}],extra_body{code:agent_xxx},# code 等自定义字段经 extra_body 传入streamTrue,)forchunkinstream:deltachunk.choices[0].deltaifdelta.content:print(delta.content,end)Node.jsOpenAI 官方 SDK 的标准用法base_url换成对应端点前缀importOpenAIfromopenai;constclientnewOpenAI({apiKey:process.env.PLATFORM_API_KEY,baseURL:https://{host}/ai/open/v1/agent,});conststreamawaitclient.chat.completions.create({model:agent_xxx,messages:[{role:user,content:你好}],stream:true,// ts-ignore 部分 SDK 版本需要用额外字段传 codecode:agent_xxx,});forawait(constchunkofstream){constdeltachunk.choices[0]?.delta;if(delta?.content)process.stdout.write(delta.content);}一个小提醒不同语言的 SDK 对非标准字段的透传方式不一样。Python 走extra_bodyNode 一般直接挂在请求体上即可但某些版本会做字段白名单校验。如果报参数不识别退一步先用 curl 验证请求体再用 SDK 复现——能快速区分是 SDK 的问题还是请求本身的问题。十、错误码全表业务错误统一返回 OpenAI 风格的错误体{error:{message:工作流必填参数缺失数量num,type:invalid_request_error,code:404}}HTTPtype场景你该怎么做400invalid_request_error请求参数错误消息格式不支持、开始节点参数校验失败直接把error.message透给前端它对用户是友好的401—API Key 缺失或无效部署检查项不要重试402insufficient_quota账户余额不足需要业务侧降级并通知管理员充值403invalid_request_error智能体 / 工作流未发布上线前必查编辑态调不通404invalid_request_errorcode 不存在、会话不存在或无权访问校验 code 与 thread_id 归属500server_error服务内部错误可做有限次退避重试403和404这两个最值得注意403通常意味着你调的是一个还在编辑态、没发布的智能体。测试环境能通、生产报 403先查发布状态。404不一定是不存在也可能是不属于你这个账户。多租户系统里这是越权防护在起作用——把它当正常分支处理。十一、兼容性边界哪些 OpenAI 习惯在这里不管用既然叫“兼容 OpenAI 协议”就要说清楚兼容到哪一层。这三条不了解清楚前四小时大概率都耗在这1.model和temperature会被忽略请求体接受这些字段毕竟 SDK 会带但服务端不采用——智能体使用自身配置的模型与参数。所以你不能在代码里通过temperature改回答风格要改去智能体配置里改model字段填什么都行一般填 code 值方便看日志它不会改变实际调用的模型响应里的model字段回填的是你的code这条设计其实是对的参数应该跟着智能体走而不是跟着每次请求走。否则同一个智能体在不同调用方手里行为不一致出了问题没法复现。但它跟“直连模型 API”的直觉相反团队里要提前对齐不然会有人反复试temperature0然后怀疑接口没生效。2.system是追加不是替换如上文所说system消息会追加在智能体自身提示词之后。想让system起决定作用是不现实的——最终行为仍以平台侧配置为准。3. 没有tool角色也没有工具轨迹智能体的工具调用过程在服务端完成不暴露给调用方。如果你的产品依赖“展示 AI 用了哪些工具”这条路走不通——只能展示最终结果加reasoning_content做过程提示。十二、上线前检查清单照着过一遍能省掉大部分联调时间API Key 只在服务端——不在前端、不在仓库、不在日志里打印。确认智能体 / 工作流已发布防403。上下文所有权只在一方——自维护历史用无状态端点托管上下文用记忆端点。thread_id做归属校验并和你自己的用户 / 会话表建立映射。402有降级路径余额不足时给用户可读提示而不是抛异常。工作流一律流式调用非流式务必拉长客户端超时文件走公网可访问的临时 URL并确认智能体侧开了对应的识别能力reasoning_content做兜底——不是所有模型都有这个字段“停止生成的文案别写不消耗”——已生成部分照常计费错误信息透传400的error.message已经带参数名直接展示比你自己翻译更准写在最后这套 API 的定位很清楚它不试图替代你的系统而是把平台侧配好的智能体能力开放出来。所以接入的关键判断不是“怎么调通接口”而是选型那两个问题上下文由谁维护—— 决定用无状态还是记忆端点你的文件存哪里—— 决定 content blocks 这条链路怎么搭这两个想清楚剩下的就是标准 OpenAI 对接团队里写过模型调用的人当天就能跑通。顺带说一句code这个设计我挺喜欢——日志里看到的是agent_xxx而不是某个模型名出了问题能直接定位到平台上那个具体的智能体排查效率高很多。如果你的系统里也维护了一份“智能体 code → 业务场景”的映射表运维时会更顺。相关文章企业级 AI 智能体平台技术拆解从 RAG 知识库到 NL2SQL 与 OpenAI 兼容 API长期记忆库让智能体跨会话记住每一位客户让 AI 从“只会说”到“能干活”插件模块实测补充一句各家平台的开放 API 文档都在控制台的「开放 API / 开发者」入口里。参数以你所用平台的最新文档为准本文的三张参数表可以直接拿去逐项对照。有问题评论区聊我看到会回。