OGX 的 Responses API用开源栈构建自有规则的多工具 Agent【免费下载链接】ogxOpen GenAI Stack项目地址: https://gitcode.com/GitHub_Trending/ll/ogx导读本文围绕 OGXOpen GenAI Stack对 OpenAI Responses API 的实现展开覆盖服务端编排的核心原理、file_search私有 RAG、基于 MCP 的多工具协调、OpenAI 客户端生态兼容以及 Open Responses 开放标准带来的演进方向。读完本文你将掌握如何在本地或自有基础设施上用一条 API 调用搭建具备检索增强与多工具编排能力的 Agent并能对照源码理解参数背后的实现机制。为什么需要 Responses API把编排从客户端搬到服务端在 Responses API 出现之前构建一个能使用工具的 Agent 是一个发生在客户端的多步编排流程应用程序需要先把可用工具列表发给模型检查返回结果中是否有工具调用请求执行这些工具把结果回传模型然后不断重复直到模型产出最终答案。所有状态管理、错误处理和重试逻辑都堆在应用代码里。这种模式给应用开发者带来沉重负担——编排逻辑在每个应用里被反复复制状态管理上的细微错误会导致回答准确率下降或者触发不必要的模型调用。Responses API 的核心变化是把编排移到服务端客户端只需发送问题同时附上一组可用工具和文档服务端在内部完成规划planning、工具执行tool execution与结果综合synthesis。客户端代码因此大幅简化行为也更一致因为编排逻辑被共享而非被每个应用重复实现。在 OGX 中这一能力由 src/ogx_api/responses 模块承载。其中 api.py 定义了Responses协议包含create_openai_response、get_openai_response、list_openai_responses、list_openai_response_input_items、delete_openai_response、compact_openai_response、cancel_openai_response等核心方法fastapi_routes.py 则把这些能力暴露为 REST 路由。OGX 暴露的 Responses 端点从 fastapi_routes.py 的路由定义可以看到OGX 在/v1前缀下提供了完整的 Responses 端点族方法与路径作用POST /v1/responses创建一条模型响应支持普通 JSON 与 SSE 流式两种返回GET /v1/responses/{response_id}获取指定响应GET /v1/responses列出响应支持after、limit、model、order分页参数GET /v1/responses/{response_id}/input_items列出某条响应的输入条目DELETE /v1/responses/{response_id}删除响应POST /v1/responses/compact压缩会话历史alpha 功能POST /v1/responses/{response_id}/cancel取消后台响应仅限backgroundtrue创建的响应WebSocket /responses在单个 WebSocket 连接上连续处理多轮 responses 请求其中POST /v1/responses对streamtrue的请求会返回text/event-stream的流式响应/responses/compact用于把超长会话压缩成更小的表示同时保留上下文对长对话场景很重要。OGX 在 API 表面之外提供了什么OGX 是一个开源 AI 应用服务端为推理、RAG、工具调用、安全、评测等提供统一 API并通过可插拔的 Provider 架构让你更换组件而无需改动应用代码。OGX 的 Responses API 实现支持内置 RAGfile_search、基于 MCP 的自动化多工具编排、会话状态管理以及与 OpenAI 客户端生态的兼容。而真正有意思的是 API 表面之外的三点价值模型自由在闭源托管服务中Responses API 与单一厂商的一组模型绑定。而 OGX 可以使用其推理 Provider 能够访问到的任何模型Llama 家族等开源模型、你自己微调的模型或生态中其他优化模型。同一个 Responses API 接口不依赖具体模型。开发阶段用小模型、生产阶段换大模型、或者整体更换模型供应商应用代码都不用改。数据主权在金融、医疗、政府等受监管行业把敏感文档发送给第三方云服务往往不可行。OGX 允许你在自己的基础设施上运行整个技术栈模型、RAG 用的向量库、工具执行环境。文档不离开你的安全边界Agent 对这些文档的推理过程同样留在边界内。开放、可扩展的架构OGX 的 Provider 架构意味着任何组件都不会被锁死在单一实现上。开发环境用 FAISS 做向量库、生产环境换 Milvus改一处配置即可。本地用 Ollama、生产用云端推理 Provider同一份应用代码不同 distribution 而已。这种灵活性覆盖整个 OGX API 表面而不仅仅是推理。私有 RAGfile_search工具检索增强生成RAG把模型的回答锚定在权威文档上从而减少幻觉并让私有知识库也能产出准确答案。Responses API 用file_search工具把 RAG 形式化你先创建向量库vector store、上传文档然后在调用 Responses API 时把file_search作为可用工具传入。模型会生成搜索查询、检索相关段落并综合成有依据的回答——所有这些都在一次 API 调用内完成。在 OGX 中这条流水线全程运行在你自己的基础设施上文档摄取、向量化嵌入、存储、检索、综合都在本地完成。响应中还会携带来源段落引用应用可以据此提供可核验的引用。配置file_searchfile_search依赖 OGX 的 tool_runtime Provider。根据 tools.mdx 的说明在 stack 配置的tool_runtime中配置inline::file-searchProvider 后builtin::file_search工具组就会被自动注册。例如 k8s 部署配置 中的写法tool_runtime: - provider_id: file-search provider_type: inline::file-search用 Responses API 做一次 RAG 查询结合 RAG 指南 中的示例完整流程如下假设 OGX 服务已运行在localhost:8321import io, requests from openai import OpenAI url https://www.paulgraham.com/greatwork.html client OpenAI(base_urlhttp://localhost:8321/v1/, api_keynone) # 1. 创建向量库 vs client.vector_stores.create() # 2. 上传文档并挂到向量库 response requests.get(url) pseudo_file io.BytesIO(str(response.content).encode(utf-8)) file_id client.files.create( file(url, pseudo_file, text/html), purposeassistants ).id client.vector_stores.files.create(vector_store_idvs.id, file_idfile_id) # 3. 通过 Responses API 自动完成检索与回答 resp client.responses.create( modelgpt-4o, inputHow do you do great work?, tools[{type: file_search, vector_store_ids: [vs.id]}], include[file_search_call.results], ) print(resp.output[-1].content[-1].text)关键点在于include[file_search_call.results]它要求响应携带文件搜索调用结果便于应用侧展示引用来源。从源码看file_search_call.results是 openai_responses.py 中定义的内容类型之一对应file_search_call.results条目工具类型本身定义在 openai_responses.pytype恒为file_search其调用则表现为file_search_call类型的输出条目。测试用例印证仓库的集成测试 test_cases.py 给出了file_search的端到端用例例如向模型提问 How many experts does the Llama 4 Maverick model have?配合tools[{type: file_search}]与文档内容期望模型基于检索结果回答 128。测试还覆盖了 PDF 文档场景file_pathpdfs/ogx_and_models.pdf。这些用例证明file_search不仅支持文本文件也能处理 PDF 等经 Files API 处理的文档类型。多工具编排连接 MCP 服务器当一个 Agent 需要协调多个工具回答复杂问题时Responses API 的价值更加凸显。以罗德岛有哪些公园它们近期有没有活动这类问题为例回答它需要发现可用工具、搜索公园、逐个查询公园的活动、综合所有结果。在 OGX 的 Responses API MCP 集成下这一整套流程发生在单次 API 调用内模型从连接的 MCP 服务器发现工具、规划并执行一串工具调用、产出综合答案客户端不需要编写任何编排逻辑。MCP 是开放的工具集成标准可用工具生态广阔且持续增长。任何 MCP 服务器——无论连接数据库、内部服务还是外部数据源——都可以接入 OGX 并被 Responses API 使用。注册 MCP 服务器根据 tools.mdx 的说明推荐的方式是在 stack 配置中用 connectors 注册connectors: - connector_id: mcp::deepwiki connector_type: mcp url: https://mcp.deepwiki.com/sse然后在调用时通过connector_id引用agent Agent( client, modelmeta-llama/Llama-3.2-3B-Instruct, instructionsYou are a helpful assistant., tools[ { type: mcp, connector_id: mcp::deepwiki, server_label: deepwiki, } ], ) agent.create_turn(...)不少 MCP 服务器需要认证常见为 OAuth2.0可以在工具定义里携带令牌tools[ { type: mcp, connector_id: mcp::deepwiki, server_label: deepwiki, authorization: your_access_token, # OAuth token不要带 Bearer 前缀 } ]也可以不注册 connector直接把server_url传给工具定义tools[ { type: mcp, server_url: https://mcp.deepwiki.com/sse, server_label: deepwiki, } ]自有 MCP 服务器示例先用supergateway把一个文件系统 MCP 服务器暴露为 SSE 端点mkdir /tmp/content touch /tmp/content/foo touch /tmp/content/bar npx -y supergateway --port 8000 --stdio npx -y modelcontextprotocol/server-filesystem /tmp/content再注册为 connector 并引用即可方法与远程服务器一致详见 tools.mdxconnectors: - connector_id: mcp::filesystem connector_type: mcp url: http://localhost:8000/sseagent Agent( client, modelmeta-llama/Llama-3.2-3B-Instruct, instructionsYou are a helpful file system assistant., tools[ { type: mcp, connector_id: mcp::filesystem, server_label: filesystem, } ], )集成测试同样覆盖了 MCP 场景test_cases.py 中的mcp_tool_test_cases通过{type: mcp, server_label: localmcp, server_url: ...}验证模型调用 MCP 工具的能力测试运行器会把占位符FILLED_BY_TEST_RUNNER替换为真实服务器地址。细粒度的工具访问控制OGX 对工具访问提供细粒度控制你可以限制某次请求可用的工具集合、向 MCP 服务器透传每请求的认证头让 Agent 只能访问当前用户的数据、在不改动 Agent prompt 的前提下配置工具行为。这在生产环境的安全与访问控制场景中非常关键。从 models.py 可以看到相关请求参数tool_choice控制模型如何选择工具OpenAIResponseInputToolChoicemax_infer_iters默认 10最小 1限定推理迭代的最大次数防止多工具循环无限执行max_tool_calls则限定单条响应中内置工具调用总数。这些参数共同构成了生产环境下防止失控循环的安全阀。框架兼容指向你的 OGX 服务器即可OGX 在/v1暴露 OpenAI 兼容端点因此官方 OpenAI Python 客户端、OGX 客户端以及任何会说 OpenAI API 的客户端都可以直接用行为一致。迁移已有基于 OpenAI 客户端写的代码只需把客户端指向你的 OGX 服务器——仅此而已。这也适用于 LangChain 等构建在 OpenAI API 之上的框架切换推理后端只需改一个构造参数无需重写 Agent 逻辑。这种即插即用兼容性的实际意义不止于方便你可以在本地 OGX 服务器上开发测试在生产用 OGX distribution 部署或在不同 OpenAI 兼容 Provider 之间切换应用代码完全不变。核心请求参数速查CreateResponseRequest 定义了 OGX Responses 请求的完整参数面以下是常用参数参数默认值说明input必填输入消息字符串或OpenAIResponseInput列表model必填用于补全的底层 LLMinstructionsNone引导模型行为的指令toolsNone提供给模型的工具列表file_search、mcp、function等tool_choiceNone模型如何选择工具parallel_tool_callstrue是否启用并行工具调用previous_response_idNone基于上一条响应继续会话延续storetrue是否把响应存入数据库streamfalse是否流式返回temperatureNone采样温度范围 0.0–2.0top_pNone核采样参数范围 0.0–1.0max_output_tokensNone输出 token 上限最小 16max_infer_iters10最大推理迭代次数最小 1max_tool_callsNone内置工具调用总数上限最小 1reasoningNone推理强度配置guardrailsNone通过moderation_endpoint启用内容审核backgroundNone后台运行立即返回statusqueuedconversationNone把响应归入指定会话skillsNone注入到上下文中的 skill ID 列表读取对应 SKILL.md其中previous_response_id与store组合实现了会话延续storetrue默认时响应持久化到数据库后续请求可用previous_response_id续写流式模式下fastapi_routes.py 的 WebSocket 端点还会维护连接级缓存允许在同一个 socket 上通过previous_response_id延续一条从未持久化的响应链。一次请求的内部流转从 Responses 内部流转文档 可以看到一条 Responses 请求会在内部编排推理、工具执行、guardrails 检查与状态持久化。核心是推理循环inference loop模型调用工具 → 拿到结果 → 再次调用推理直到不再产生服务端工具调用、返回客户端function_call、或达到max_infer_iters上限。流式场景下服务端通过 SSE 事件如response.reasoning_text.delta、response.file_search_call.in_progress、response.mcp_call.completed等定义见 openai_responses.py把进展实时推给客户端。走向开放标准Open ResponsesOGX 最初实现 Responses API 时该规范还是私有的。OGX 必须追赶一个移动的目标OpenAI 每次新增功能到 OGX 实现之间总存在时间差。Open Responses 规范改变了这一点。它是由包括 OpenAI、Hugging Face 以及 Ollama、vLLM、LM Studio 等提供商在内的广泛社区支持的开放规范把 Responses API 的核心概念形式化为开放标准以 item 作为上下文的原子单元、语义化的流式事件以及推理 工具调用的 Agent 循环。对 OGX 而言Open Responses 提供了一个稳定、社区治理的规范来构建而非私有的移动目标。这也意味着 OGX 的 Responses API 实现属于更广泛的可互操作 Provider 生态基于 Open Responses 规范构建的应用可以在 OGX、OpenAI、Hugging Face 基础设施或 Ollama 等本地 Provider 上运行无需修改代码。该规范还引入了一些对生产部署至关重要的概念推理可见性Reasoning visibility规范明确了模型如何暴露推理过程支持审计追踪与治理工作流。OGX 的响应对象中对应reasoning输出条目与reasoning_text内容类型流式事件包括response.reasoning_text.delta、response.reasoning_summary_part.added等见 openai_responses.py。内部工具 vs 外部工具清晰区分在 Provider 基础设施内执行如file_search与由客户端执行的工具让开发者确切知道计算发生在哪里。在 OGX 的响应对象中file_search_call内部工具调用与function_call客户端工具调用是不同类型的输出条目。不碎片化的可扩展性Provider 可以在保持稳定、可互操作核心的同时增加自定义能力。对于 OGX 社区投资 Responses API 不只是为了兼容某一家厂商而是构建在一个行业正在趋同的开放标准之上。快速上手如果你刚接触 OGX按以下步骤即可起一个本地服务需要先安装 uvollama pull llama3.2:3b uvx ogx go启动后OGX 服务默认监听localhost:8321OpenAI 兼容端点位于http://localhost:8321/v1/。更多入门内容可参考 Getting Started 快速上手 与 详细教程Responses API 与 Agents API 的选型对比见 Responses vs Agents关于file_search、MCP 的完整配置与工具管理可继续阅读 RAG 指南 与 Tools 指南。Responses API 仍在快速演进无论 OGX 还是 Open Responses 规范都是如此。如果你正在构建真实应用不妨对照 Responses 集成测试 中的file_search_test_cases与mcp_tool_test_cases验证你的场景并分享经验——这对规范与实现的共同完善很有价值。【免费下载链接】ogxOpen GenAI Stack项目地址: https://gitcode.com/GitHub_Trending/ll/ogx创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
