WeKnora 聊天功能 API 实战指南知识库问答、Agent 智能问答与 SSE 流式响应【免费下载链接】WeKnoraOpen-source LLM knowledge platform: turn raw documents into a queryable RAG, an autonomous reasoning agent, and a self-maintaining Wiki.项目地址: https://gitcode.com/GitHub_Trending/we/WeKnora本篇技术指南围绕 WeKnora 的聊天功能 API 展开系统讲解基于知识库的 RAG 问答/knowledge-chat、基于 Agent 的智能问答/agent-chat、知识搜索/knowledge-search与回答后推荐问题suggestions四个核心接口的请求参数、SSE 流式响应格式与实战调用方法。读完本文你将能够直接使用curl或任意 HTTP 客户端接入 WeKnora 的对话能力理解resource_urls直链参数、mentioned_items提及结构与推荐问题归属校验机制并能结合源码定位每个接口的底层执行路径。1. 接口总览聊天类接口均挂载在基础 URL/api/v1下使用X-API-Key请求头完成身份认证。下表是聊天功能涉及的完整端点清单方法路径描述POST/knowledge-chat/:session_id基于知识库的问答POST/agent-chat/:session_id基于 Agent 的智能问答POST/knowledge-search基于知识库的搜索知识GET/sessions/:session_id/messages/:message_id/suggestions获取已生成的回答后推荐POST/sessions/:session_id/messages/:message_id/suggestions确保生成或换一批推荐POST/sessions/:session_id/suggestion-events上报曝光、点击、关闭事件从源码路由注册看internal/router/routes_chat.go前三个接口由session.Handler提供实现/knowledge-chat与/agent-chat需要chat能力API Key 具备聊天权限/knowledge-search需要retrieve检索能力三个建议相关端点则由独立的MessageSuggestionHandler提供。此外同一文件还注册了GET /sessions/continue-stream/:session_id用于客户端断线后重新接入正在进行的流式响应。2. 认证、错误处理与调试建议所有请求都需要在 HTTP 头携带 API KeyX-API-Key: your_api_key建议同时添加X-Request-ID便于问题追踪与日志关联X-Request-ID: unique_request_idAPI Key 在 Web 页面完成账户注册后从账户信息页面获取它代表账户身份并拥有完整的 API 访问权限请妥善保管。错误响应统一采用如下 JSON 结构并以标准 HTTP 状态码表达请求状态{ success: false, error: { code: 错误代码, message: 错误信息, details: 错误详情 } }启动服务后可访问http://localhost:8080/swagger/index.html查看随代码自动更新的 OpenAPI/Swagger 文档仅非 release 模式挂载它是最权威的接口 schema 参考。3.resource_urls查询参数handle与public直链聊天类接口都支持查询参数resource_urls决定响应中图片、图表、附件引用的表现形式参数取值说明resource_urlshandle默认/publicpublic让答案与引用里的图片直接返回可加载的 http(s) 链接省去逐个调用/files代理默认handle模式下响应里的资源以内部引用resource://handle返回如示意图浏览器不能直接加载客户端需要调用带鉴权的GET /files?file_path引用代理获取字节流public模式下服务端返回可直接加载的 http(s) 直链适合将 WeKnora 集成进自有 App 的场景该参数同样适用于/agent-chat/:session_id、/knowledge-search、/knowledge-bases/:id/hybrid-search与/sessions/continue-stream/:session_id传其它值返回400。直链由存储后端预签名MinIO 预签名 24 小时或由APP_EXTERNAL_URL/r/token签发WeKnora grant 2 小时两者都不可用时如 local 存储且未设APP_EXTERNAL_URL引用保持resource://原样。需要注意直链是限时匿名可读的请勿写入日志或转发给无关人员限定知识库的 API Key 不能使用public返回403嵌入式 embed 渠道强制使用handle。完整注意事项可参阅 文件与图片引用resource:// 与直链。从源码看该参数在 SSE 流启动前就被解析internal/handler/session/qa.go一旦非法值可以在写流前以 400 报告流式回答中跨 chunk 被截断的引用会先缓冲再改写客户端拿到的始终是完整链接。4. POST/knowledge-chat/:session_id基于知识库的 RAG 问答基于知识库的 RAG 问答支持 SSE 流式响应适用于给定知识库、给出有引用依据的回答场景。4.1 请求参数参数类型必填说明querystring是查询文本knowledge_base_idsstring[]否知识库 ID 列表knowledge_idsstring[]否知识文件 ID 列表指定具体文件进行检索agent_idstring否自定义 Agent ID指定使用的智能体summary_model_idstring否覆盖默认的摘要模型 IDmentioned_itemsobject[]否提及的知识库和文件列表disable_titlebool否是否禁用自动标题生成默认 falseimagesobject[]否附带的图片base64 格式需要 Agent 启用图片上传channelstring否来源渠道标识web、api、im、browser_extensionsuggestion_attributionobject否用户从推荐问题发起本轮时传入{suggestion_set_id, question_id}服务端会校验归属其中mentioned_items结构为字段类型说明idstring知识库或文件 IDnamestring显示名称typestring类型kb知识库或file文件kb_typestring知识库类型document或faq仅typekb时images结构为字段类型说明datastringbase64 编码的图片数据data:image/png;base64,...4.2 请求示例curl --location http://localhost:8080/api/v1/knowledge-chat/ceb9babb-1e30-41d7-817d-fd584954304b \ --header X-API-Key: sk-xxxxx \ --header Content-Type: application/json \ --data { query: 彗尾的形状, knowledge_base_ids: [kb-00000001], agent_id: builtin-quick-answer }4.3 SSE 流式响应响应为服务器端事件流Server-Sent EventsContent-Type: text/event-stream。每帧由event与data组成data为 JSON 对象核心字段包括id请求/消息 ID、response_type、content、done、knowledge_references。event: message data: {id:3475c004-0ada-4306-9d30-d7f5efce50d2,response_type:references,content:,done:false,knowledge_references:[{id:c8347bef-...,content:彗星xxx。,knowledge_id:a6790b93-...,chunk_index:0,knowledge_title:彗星.txt,score:4.04,match_type:3,chunk_type:text,knowledge_filename:彗星.txt}]} event: message data: {id:3475c004-0ada-4306-9d30-d7f5efce50d2,response_type:answer,content:彗尾的形状主要表现为...,done:false,knowledge_references:null} event: message data: {id:3475c004-0ada-4306-9d30-d7f5efce50d2,response_type:answer,content:,done:true,knowledge_references:null}流程为先推送references事件携带knowledge_references检索引用包含分块内容、所属知识库/文件 ID、chunk 序号、相关度分数与匹配类型再流式推送answer内容帧最后以done: true的answer帧收尾。客户端应缓存knowledge_references并在渲染最终答案时展示引用来源。4.4 源码执行路径从 internal/handler/session/qa.go 可以看到KnowledgeQA处理器依次完成解析并校验请求parseQARequest→ 将mentioned_items与knowledge_base_ids/knowledge_ids合并去重mergeKnowledgeTargets→ 执行普通模式问答executeQAqaModeNormal。executeQA内部会异步调用sessionService.KnowledgeQA驱动 RAG pipeline并将事件总线EventBus上的事件翻译为 SSE 帧写入响应同时根据disable_title决定是否异步生成会话标题session_title事件。值得注意的边界行为可从源码确认query为空直接返回400session_id必须属于当前用户使用严格 owner 作用域校验图片上传必须由所用 Agent 开启ImageUploadEnabled否则返回400客户端提交的图片 URL/Caption 字段会被服务端清空SSRF 防护仅由后端在保存后回填。5. POST/agent-chat/:session_id基于 Agent 的智能问答Agent 模式支持更智能的问答包括工具调用、网络搜索、多知识库检索等能力并通过 SSE 流将 Agent 的思考、工具调用过程实时推送给客户端。5.1 请求参数参数类型必填说明querystring是查询文本knowledge_base_idsstring[]否知识库 ID 列表可动态指定本次查询使用的知识库knowledge_idsstring[]否知识文件 ID 列表可动态指定本次查询使用的具体文件agent_enabledbool否是否启用 Agent 模式默认 false优先使用 Agent 配置agent_idstring否自定义 Agent ID指定使用的智能体支持共享 Agentweb_search_enabledbool否是否启用网络搜索默认 falsesummary_model_idstring否覆盖默认的摘要模型 IDmentioned_itemsobject[]否提及的知识库和文件列表disable_titlebool否是否禁用自动标题生成默认 falseimagesobject[]否附带的图片base64 格式需要 Agent 启用图片上传channelstring否来源渠道标识web、api、im、browser_extensionsuggestion_attributionobject否用户从推荐问题发起本轮时传入{suggestion_set_id, question_id}服务端会校验归属agent_enabled与agent_id的配合逻辑为若传了agent_id且该 Agent 配置为 Agent 模式config.agent_mode则 Agent 模式优先于请求中的agent_enabled若agent_enabledtrue但无法解析出agent_id服务端直接返回400agent_id is required when agent mode is enabled避免生成过程中途失败。agent_id也支持共享 Agent——服务端会先尝试从共享关系中解析resolveAgent解析成功后以源空间的租户上下文解析模型、知识库与 MCP 服务并标记只读共享权限。5.2 请求示例curl --location http://localhost:8080/api/v1/agent-chat/ceb9babb-1e30-41d7-817d-fd584954304b \ --header X-API-Key: sk-xxxxx \ --header Content-Type: application/json \ --data { query: 帮我查询今天的天气, agent_enabled: true, web_search_enabled: true, knowledge_base_ids: [kb-00000001], agent_id: builtin-smart-reasoning, mentioned_items: [ { id: kb-00000001, name: 天气知识库, type: kb, kb_type: document } ] }5.3 SSE 流式响应类型Agent 问答的响应同样是 SSE 流Content-Type: text/event-stream但response_type远比普通问答丰富客户端可根据类型渲染思考卡片、工具调用记录与最终回答response_type描述agent_queryAgent 开始处理查询thinkingAgent 思考过程tool_call工具调用信息tool_result工具调用结果references知识库检索引用answer最终回答内容artifacts_pendingSkill/沙箱产物正在上传data.count为待保存文件数。回答可能已经done文件按钮会在此期间显示加载态直至complete带上artifactsreflectionAgent 反思内容session_title自动生成的会话标题error错误信息5.4 响应示例event: message data: {id:req-001,response_type:thinking,content:用户想查询天气我需要使用网络搜索工具...,done:false} event: message data: {id:req-001,response_type:tool_call,content:,done:false,data:{tool_name:web_search,arguments:{query:今天天气}}} event: message data: {id:req-001,response_type:tool_result,content:搜索结果今天晴气温25°C...,done:false} event: message data: {id:req-001,response_type:answer,content:根据查询结果今天天气晴朗气温约25°C。,done:false} event: message data: {id:req-001,response_type:answer,content:,done:true}客户端可按tool_call/tool_result的data.tool_name渲染正在调用 XX 工具的进度提示用thinking帧渲染推理过程卡片。5.5 源码执行路径AgentQAinternal/handler/session/qa.go在parseQARequest基础上额外做了三件事根据自定义 Agent 的IsAgentMode()决定最终是否走 Agent 引擎在没有可解析agent_id时提前拒绝按模式分流到executeQA(qaModeAgent)或退回普通模式。Agent 模式下Agent 流处理器internal/handler/session/agent_stream_handler.go通过独立的 EventBus 订阅引擎事件并翻译为 SSE 帧同时维护answerSegment列表——非终结轮次流式输出的开场白如让我搜索一下…会在该轮实际调用工具后被标记为 superseded 并从持久化回答中剔除避免污染最终答案。Agent 模式还支持同会话并发保护一个会话同时只允许一个运行中的轮次SetLiveRun/rejectIfOtherAgentRunLive重复发起会返回409another turn is already running in this session。此外Agent 轮次完成后会异步持久化agent_steps思考/工具调用历史刷新页面后仍能还原推理过程。6. 回答后推荐问题suggestions回答主消息完成后服务端会异步生成推荐问题不阻塞 SSE 的complete/done事件。生成结果按空间、助手消息、位置、配置快照、语言持久化并去重——相同配置快照会复用已生成的推荐避免重复消耗模型额度。6.1 确保生成或换一批推荐POST /api/v1/sessions/{session_id}/messages/{message_id}/suggestions Content-Type: application/json {regenerate: false}regenerate为false时复用已有推荐没有才生成为true时强制重新生成一批。响应状态包括generating、ready、suppressed、failedgenerating正在生成返回 HTTP202ready生成完成每个问题都有稳定idsuppressed该消息被压制如 Agent 配置关闭推荐failed生成失败。6.2 获取已生成的推荐GET /api/v1/sessions/{session_id}/messages/{message_id}/suggestions6.3 上报曝光、点击、关闭事件POST /api/v1/sessions/{session_id}/suggestion-events Content-Type: application/json { suggestion_set_id: ..., question_id: ..., event_type: click }event_type支持exposure曝光、click点击、close关闭等取值。用户点击推荐问题发起新一轮对话时应在下一次聊天请求中携带suggestion_attribution: {suggestion_set_id, question_id}服务端会校验归属防止伪造归属数据。从源码internal/handler/message_suggestion.go可以看到这些端点的具体行为Ensure对未完成的助手消息返回400RecordEvent对非法事件类型、缺少question_id点击事件等情况返回400成功则返回204会话或推荐集合不存在时返回404。网页嵌入embed场景提供同构接口/api/v1/embed/{channel_id}/sessions/{session_id}/...继续使用嵌入令牌和X-Embed-Session便于在外部网页中以匿名访客身份复用同一套推荐交互。7. POST/knowledge-search知识库检索不经过 LLM 总结直接在知识库中执行检索并返回候选片段适合构建检索中间层或预取上下文。请求参数与知识问答共享query、knowledge_base_ids、knowledge_ids、mentioned_items等字段为兼容旧客户端还支持单数knowledge_base_id会自动合并进knowledge_base_ids列表。请求中必须至少提供knowledge_base_ids、knowledge_ids或带作用域的标签之一否则返回400。响应为普通 JSONContent-Type: application/json结构为{success: true, data: [...]}其中每个检索结果包含分块内容、所属文件与知识库信息resource_urlspublic时引用会被改写为直链internal/handler/session/qa.go 中的SearchKnowledge处理器。8. 实战接入建议与注意事项综合源码与文档接入 WeKnora 聊天 API 时有几个实用要点SSE 解析knowledge-chat与agent-chat的每一帧都是event: messagedata: {...}data内的response_type是客户端分派渲染类型的唯一依据流以done: true的帧收尾但agent-chat在done后仍可能推送artifacts_pending/completeSkill 产物上传帧客户端不应在收到done后立即关闭流。资源引用处理默认handle模式下引用需要二次请求/files代理若为自有 App 集成且存储后端支持预签名/外部 URL可统一使用?resource_urlspublic。注意嵌入式匿名渠道与限定知识库的 API Key 均不能使用public。推荐问题闭环点击推荐后先上报suggestion-eventsclick再在下一轮聊天请求中携带suggestion_attribution两端校验一致才能形成完整数据闭环。多轮与并发同一session_id承载多轮上下文Agent 模式下同会话并发发起会被409拒绝前端应等待上一轮done后再允许发送。图片与附件images传 base64 data URI且要求所用 Agent 开启图片上传并配置 VLM 模型文件附件支持 base64 内联attachment_uploads单请求最多 5 个、总量不超过 100MB或预上传会话级文档attachment_ids附件解析等待超时默认 60 秒可通过WEKNORA_CHAT_ATTACHMENT_WAIT_TIMEOUT_SEC调整。更完整的请求 schema、响应字段与试调入口请以启动后的 Swagger UIhttp://localhost:8080/swagger/index.html为准相关的知识库、会话、消息与 Agent 管理接口可继续参阅 docs/api/README.md 目录下的各分篇文档。【免费下载链接】WeKnoraOpen-source LLM knowledge platform: turn raw documents into a queryable RAG, an autonomous reasoning agent, and a self-maintaining Wiki.项目地址: https://gitcode.com/GitHub_Trending/we/WeKnora创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/9/13 8:00:45 · 阅读 1.2k WeKnora 聊天功能 API 实战指南：知识库问答、Agent 智能问答与 SSE 流式响应
WeKnora 聊天功能 API 实战指南知识库问答、Agent 智能问答与 SSE 流式响应【免费下载链接】WeKnoraOpen-source LLM knowledge platform: turn raw documents into a queryable RAG, an autonomous reasoning agent, and a self-maintaining Wiki.项目地址: https://gitcode.com/GitHub_Trending/we/WeKnora本篇技术指南围绕 WeKnora 的聊天功能 API 展开系统讲解基于知识库的 RAG 问答/knowledge-chat、基于 Agent 的智能问答/agent-chat、知识搜索/knowledge-search与回答后推荐问题suggestions四个核心接口的请求参数、SSE 流式响应格式与实战调用方法。读完本文你将能够直接使用curl或任意 HTTP 客户端接入 WeKnora 的对话能力理解resource_urls直链参数、mentioned_items提及结构与推荐问题归属校验机制并能结合源码定位每个接口的底层执行路径。1. 接口总览聊天类接口均挂载在基础 URL/api/v1下使用X-API-Key请求头完成身份认证。下表是聊天功能涉及的完整端点清单方法路径描述POST/knowledge-chat/:session_id基于知识库的问答POST/agent-chat/:session_id基于 Agent 的智能问答POST/knowledge-search基于知识库的搜索知识GET/sessions/:session_id/messages/:message_id/suggestions获取已生成的回答后推荐POST/sessions/:session_id/messages/:message_id/suggestions确保生成或换一批推荐POST/sessions/:session_id/suggestion-events上报曝光、点击、关闭事件从源码路由注册看internal/router/routes_chat.go前三个接口由session.Handler提供实现/knowledge-chat与/agent-chat需要chat能力API Key 具备聊天权限/knowledge-search需要retrieve检索能力三个建议相关端点则由独立的MessageSuggestionHandler提供。此外同一文件还注册了GET /sessions/continue-stream/:session_id用于客户端断线后重新接入正在进行的流式响应。2. 认证、错误处理与调试建议所有请求都需要在 HTTP 头携带 API KeyX-API-Key: your_api_key建议同时添加X-Request-ID便于问题追踪与日志关联X-Request-ID: unique_request_idAPI Key 在 Web 页面完成账户注册后从账户信息页面获取它代表账户身份并拥有完整的 API 访问权限请妥善保管。错误响应统一采用如下 JSON 结构并以标准 HTTP 状态码表达请求状态{ success: false, error: { code: 错误代码, message: 错误信息, details: 错误详情 } }启动服务后可访问http://localhost:8080/swagger/index.html查看随代码自动更新的 OpenAPI/Swagger 文档仅非 release 模式挂载它是最权威的接口 schema 参考。3.resource_urls查询参数handle与public直链聊天类接口都支持查询参数resource_urls决定响应中图片、图表、附件引用的表现形式参数取值说明resource_urlshandle默认/publicpublic让答案与引用里的图片直接返回可加载的 http(s) 链接省去逐个调用/files代理默认handle模式下响应里的资源以内部引用resource://handle返回如示意图浏览器不能直接加载客户端需要调用带鉴权的GET /files?file_path引用代理获取字节流public模式下服务端返回可直接加载的 http(s) 直链适合将 WeKnora 集成进自有 App 的场景该参数同样适用于/agent-chat/:session_id、/knowledge-search、/knowledge-bases/:id/hybrid-search与/sessions/continue-stream/:session_id传其它值返回400。直链由存储后端预签名MinIO 预签名 24 小时或由APP_EXTERNAL_URL/r/token签发WeKnora grant 2 小时两者都不可用时如 local 存储且未设APP_EXTERNAL_URL引用保持resource://原样。需要注意直链是限时匿名可读的请勿写入日志或转发给无关人员限定知识库的 API Key 不能使用public返回403嵌入式 embed 渠道强制使用handle。完整注意事项可参阅 文件与图片引用resource:// 与直链。从源码看该参数在 SSE 流启动前就被解析internal/handler/session/qa.go一旦非法值可以在写流前以 400 报告流式回答中跨 chunk 被截断的引用会先缓冲再改写客户端拿到的始终是完整链接。4. POST/knowledge-chat/:session_id基于知识库的 RAG 问答基于知识库的 RAG 问答支持 SSE 流式响应适用于给定知识库、给出有引用依据的回答场景。4.1 请求参数参数类型必填说明querystring是查询文本knowledge_base_idsstring[]否知识库 ID 列表knowledge_idsstring[]否知识文件 ID 列表指定具体文件进行检索agent_idstring否自定义 Agent ID指定使用的智能体summary_model_idstring否覆盖默认的摘要模型 IDmentioned_itemsobject[]否提及的知识库和文件列表disable_titlebool否是否禁用自动标题生成默认 falseimagesobject[]否附带的图片base64 格式需要 Agent 启用图片上传channelstring否来源渠道标识web、api、im、browser_extensionsuggestion_attributionobject否用户从推荐问题发起本轮时传入{suggestion_set_id, question_id}服务端会校验归属其中mentioned_items结构为字段类型说明idstring知识库或文件 IDnamestring显示名称typestring类型kb知识库或file文件kb_typestring知识库类型document或faq仅typekb时images结构为字段类型说明datastringbase64 编码的图片数据data:image/png;base64,...4.2 请求示例curl --location http://localhost:8080/api/v1/knowledge-chat/ceb9babb-1e30-41d7-817d-fd584954304b \ --header X-API-Key: sk-xxxxx \ --header Content-Type: application/json \ --data { query: 彗尾的形状, knowledge_base_ids: [kb-00000001], agent_id: builtin-quick-answer }4.3 SSE 流式响应响应为服务器端事件流Server-Sent EventsContent-Type: text/event-stream。每帧由event与data组成data为 JSON 对象核心字段包括id请求/消息 ID、response_type、content、done、knowledge_references。event: message data: {id:3475c004-0ada-4306-9d30-d7f5efce50d2,response_type:references,content:,done:false,knowledge_references:[{id:c8347bef-...,content:彗星xxx。,knowledge_id:a6790b93-...,chunk_index:0,knowledge_title:彗星.txt,score:4.04,match_type:3,chunk_type:text,knowledge_filename:彗星.txt}]} event: message data: {id:3475c004-0ada-4306-9d30-d7f5efce50d2,response_type:answer,content:彗尾的形状主要表现为...,done:false,knowledge_references:null} event: message data: {id:3475c004-0ada-4306-9d30-d7f5efce50d2,response_type:answer,content:,done:true,knowledge_references:null}流程为先推送references事件携带knowledge_references检索引用包含分块内容、所属知识库/文件 ID、chunk 序号、相关度分数与匹配类型再流式推送answer内容帧最后以done: true的answer帧收尾。客户端应缓存knowledge_references并在渲染最终答案时展示引用来源。4.4 源码执行路径从 internal/handler/session/qa.go 可以看到KnowledgeQA处理器依次完成解析并校验请求parseQARequest→ 将mentioned_items与knowledge_base_ids/knowledge_ids合并去重mergeKnowledgeTargets→ 执行普通模式问答executeQAqaModeNormal。executeQA内部会异步调用sessionService.KnowledgeQA驱动 RAG pipeline并将事件总线EventBus上的事件翻译为 SSE 帧写入响应同时根据disable_title决定是否异步生成会话标题session_title事件。值得注意的边界行为可从源码确认query为空直接返回400session_id必须属于当前用户使用严格 owner 作用域校验图片上传必须由所用 Agent 开启ImageUploadEnabled否则返回400客户端提交的图片 URL/Caption 字段会被服务端清空SSRF 防护仅由后端在保存后回填。5. POST/agent-chat/:session_id基于 Agent 的智能问答Agent 模式支持更智能的问答包括工具调用、网络搜索、多知识库检索等能力并通过 SSE 流将 Agent 的思考、工具调用过程实时推送给客户端。5.1 请求参数参数类型必填说明querystring是查询文本knowledge_base_idsstring[]否知识库 ID 列表可动态指定本次查询使用的知识库knowledge_idsstring[]否知识文件 ID 列表可动态指定本次查询使用的具体文件agent_enabledbool否是否启用 Agent 模式默认 false优先使用 Agent 配置agent_idstring否自定义 Agent ID指定使用的智能体支持共享 Agentweb_search_enabledbool否是否启用网络搜索默认 falsesummary_model_idstring否覆盖默认的摘要模型 IDmentioned_itemsobject[]否提及的知识库和文件列表disable_titlebool否是否禁用自动标题生成默认 falseimagesobject[]否附带的图片base64 格式需要 Agent 启用图片上传channelstring否来源渠道标识web、api、im、browser_extensionsuggestion_attributionobject否用户从推荐问题发起本轮时传入{suggestion_set_id, question_id}服务端会校验归属agent_enabled与agent_id的配合逻辑为若传了agent_id且该 Agent 配置为 Agent 模式config.agent_mode则 Agent 模式优先于请求中的agent_enabled若agent_enabledtrue但无法解析出agent_id服务端直接返回400agent_id is required when agent mode is enabled避免生成过程中途失败。agent_id也支持共享 Agent——服务端会先尝试从共享关系中解析resolveAgent解析成功后以源空间的租户上下文解析模型、知识库与 MCP 服务并标记只读共享权限。5.2 请求示例curl --location http://localhost:8080/api/v1/agent-chat/ceb9babb-1e30-41d7-817d-fd584954304b \ --header X-API-Key: sk-xxxxx \ --header Content-Type: application/json \ --data { query: 帮我查询今天的天气, agent_enabled: true, web_search_enabled: true, knowledge_base_ids: [kb-00000001], agent_id: builtin-smart-reasoning, mentioned_items: [ { id: kb-00000001, name: 天气知识库, type: kb, kb_type: document } ] }5.3 SSE 流式响应类型Agent 问答的响应同样是 SSE 流Content-Type: text/event-stream但response_type远比普通问答丰富客户端可根据类型渲染思考卡片、工具调用记录与最终回答response_type描述agent_queryAgent 开始处理查询thinkingAgent 思考过程tool_call工具调用信息tool_result工具调用结果references知识库检索引用answer最终回答内容artifacts_pendingSkill/沙箱产物正在上传data.count为待保存文件数。回答可能已经done文件按钮会在此期间显示加载态直至complete带上artifactsreflectionAgent 反思内容session_title自动生成的会话标题error错误信息5.4 响应示例event: message data: {id:req-001,response_type:thinking,content:用户想查询天气我需要使用网络搜索工具...,done:false} event: message data: {id:req-001,response_type:tool_call,content:,done:false,data:{tool_name:web_search,arguments:{query:今天天气}}} event: message data: {id:req-001,response_type:tool_result,content:搜索结果今天晴气温25°C...,done:false} event: message data: {id:req-001,response_type:answer,content:根据查询结果今天天气晴朗气温约25°C。,done:false} event: message data: {id:req-001,response_type:answer,content:,done:true}客户端可按tool_call/tool_result的data.tool_name渲染正在调用 XX 工具的进度提示用thinking帧渲染推理过程卡片。5.5 源码执行路径AgentQAinternal/handler/session/qa.go在parseQARequest基础上额外做了三件事根据自定义 Agent 的IsAgentMode()决定最终是否走 Agent 引擎在没有可解析agent_id时提前拒绝按模式分流到executeQA(qaModeAgent)或退回普通模式。Agent 模式下Agent 流处理器internal/handler/session/agent_stream_handler.go通过独立的 EventBus 订阅引擎事件并翻译为 SSE 帧同时维护answerSegment列表——非终结轮次流式输出的开场白如让我搜索一下…会在该轮实际调用工具后被标记为 superseded 并从持久化回答中剔除避免污染最终答案。Agent 模式还支持同会话并发保护一个会话同时只允许一个运行中的轮次SetLiveRun/rejectIfOtherAgentRunLive重复发起会返回409another turn is already running in this session。此外Agent 轮次完成后会异步持久化agent_steps思考/工具调用历史刷新页面后仍能还原推理过程。6. 回答后推荐问题suggestions回答主消息完成后服务端会异步生成推荐问题不阻塞 SSE 的complete/done事件。生成结果按空间、助手消息、位置、配置快照、语言持久化并去重——相同配置快照会复用已生成的推荐避免重复消耗模型额度。6.1 确保生成或换一批推荐POST /api/v1/sessions/{session_id}/messages/{message_id}/suggestions Content-Type: application/json {regenerate: false}regenerate为false时复用已有推荐没有才生成为true时强制重新生成一批。响应状态包括generating、ready、suppressed、failedgenerating正在生成返回 HTTP202ready生成完成每个问题都有稳定idsuppressed该消息被压制如 Agent 配置关闭推荐failed生成失败。6.2 获取已生成的推荐GET /api/v1/sessions/{session_id}/messages/{message_id}/suggestions6.3 上报曝光、点击、关闭事件POST /api/v1/sessions/{session_id}/suggestion-events Content-Type: application/json { suggestion_set_id: ..., question_id: ..., event_type: click }event_type支持exposure曝光、click点击、close关闭等取值。用户点击推荐问题发起新一轮对话时应在下一次聊天请求中携带suggestion_attribution: {suggestion_set_id, question_id}服务端会校验归属防止伪造归属数据。从源码internal/handler/message_suggestion.go可以看到这些端点的具体行为Ensure对未完成的助手消息返回400RecordEvent对非法事件类型、缺少question_id点击事件等情况返回400成功则返回204会话或推荐集合不存在时返回404。网页嵌入embed场景提供同构接口/api/v1/embed/{channel_id}/sessions/{session_id}/...继续使用嵌入令牌和X-Embed-Session便于在外部网页中以匿名访客身份复用同一套推荐交互。7. POST/knowledge-search知识库检索不经过 LLM 总结直接在知识库中执行检索并返回候选片段适合构建检索中间层或预取上下文。请求参数与知识问答共享query、knowledge_base_ids、knowledge_ids、mentioned_items等字段为兼容旧客户端还支持单数knowledge_base_id会自动合并进knowledge_base_ids列表。请求中必须至少提供knowledge_base_ids、knowledge_ids或带作用域的标签之一否则返回400。响应为普通 JSONContent-Type: application/json结构为{success: true, data: [...]}其中每个检索结果包含分块内容、所属文件与知识库信息resource_urlspublic时引用会被改写为直链internal/handler/session/qa.go 中的SearchKnowledge处理器。8. 实战接入建议与注意事项综合源码与文档接入 WeKnora 聊天 API 时有几个实用要点SSE 解析knowledge-chat与agent-chat的每一帧都是event: messagedata: {...}data内的response_type是客户端分派渲染类型的唯一依据流以done: true的帧收尾但agent-chat在done后仍可能推送artifacts_pending/completeSkill 产物上传帧客户端不应在收到done后立即关闭流。资源引用处理默认handle模式下引用需要二次请求/files代理若为自有 App 集成且存储后端支持预签名/外部 URL可统一使用?resource_urlspublic。注意嵌入式匿名渠道与限定知识库的 API Key 均不能使用public。推荐问题闭环点击推荐后先上报suggestion-eventsclick再在下一轮聊天请求中携带suggestion_attribution两端校验一致才能形成完整数据闭环。多轮与并发同一session_id承载多轮上下文Agent 模式下同会话并发发起会被409拒绝前端应等待上一轮done后再允许发送。图片与附件images传 base64 data URI且要求所用 Agent 开启图片上传并配置 VLM 模型文件附件支持 base64 内联attachment_uploads单请求最多 5 个、总量不超过 100MB或预上传会话级文档attachment_ids附件解析等待超时默认 60 秒可通过WEKNORA_CHAT_ATTACHMENT_WAIT_TIMEOUT_SEC调整。更完整的请求 schema、响应字段与试调入口请以启动后的 Swagger UIhttp://localhost:8080/swagger/index.html为准相关的知识库、会话、消息与 Agent 管理接口可继续参阅 docs/api/README.md 目录下的各分篇文档。【免费下载链接】WeKnoraOpen-source LLM knowledge platform: turn raw documents into a queryable RAG, an autonomous reasoning agent, and a self-maintaining Wiki.项目地址: https://gitcode.com/GitHub_Trending/we/WeKnora创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考