OGX 内置 Responses Provider 深度解析OpenAI Responses API 的 Agent 化实现与运行原理【免费下载链接】ogxOpen GenAI Stack项目地址: https://gitcode.com/GitHub_Trending/ll/ogx导读本文围绕 OGXOpen GenAI Stack仓库中 src/ogx/providers/inline/responses/README.md 所描述的builtin内置responses provider 展开系统讲解它是如何实现 OpenAI Responses API、如何以多轮工具调用循环驱动 Agent 推理、如何通过 SSE 流式返回结果、如何用外部审核端点提供护栏Guardrails以及背后的配置模型、依赖关系和实现架构。读完本文你将掌握该 provider 的目录结构与核心调用链理解CompactionConfig、MemoryConfig、moderation_endpoint等配置项的真实作用并能在自己的 OGX 分发配置中正确启用和调优它。一、模块定位从agents到responses的内置实现在 OGX 中内置 Responses Providerbuiltin是responsesAPI 的标准实现它本身不调用任何外部模型服务而是把 OGX 内部的其他 APIinference、tool_runtime、vector_io、files 等编排起来对外呈现为与 OpenAI Responses API 兼容的/v1/responses端点。该模块位于 src/ogx/providers/inline/responses。根据其 README这个目录正在从agents重命名为responses对应 PR #5195因此你可能会在旧文档或旧代码中看到agents的称呼二者指的是同一个实现。该 provider 的核心能力有三点Agent 回合Agent turns多步推理与工具调用循环。Agent 调用推理 provider执行模型请求的工具把工具结果回填再继续推理直到模型产出最终回答OpenAI Responses API实现/v1/responses端点提供有状态stateful、与 OpenAI Responses API 兼容的 Agent 化接口支持内置工具web search、code interpreter、file search与自定义 function 工具Guardrails可选地通过外部审核端点对输入与输出做内容安全过滤。值得注意的是README 中提到的code interpreter工具在当前的源码树中未发现独立实现在src/ogx/providers/inline/responses/builtin/responses目录下搜索CodeInterpreter无命中从源码结构可以推断内置工具的实际落地以 web search、file search、MCP 工具和 function 工具为主这一点在配置与测试中都有体现。二、目录结构与各文件职责README 给出了该 provider 的目录结构。对照实际仓库当前目录为src/ogx/providers/inline/responses/builtin/其中responses/子目录下还增加了memory.py与truncation.py两个模块src/ogx/providers/inline/responses/builtin/ __init__.py # Provider 工厂get_provider_impl impl.py # 核心编排逻辑BuiltinResponsesImpl config.py # BuiltinResponsesImplConfig 及各子配置 responses/ # OpenAI Responses API 实现 __init__.py openai_responses.py # Responses API 处理器1820 行 streaming.py # SSE 流式编排2146 行 tool_executor.py # 工具调用执行引擎641 行 memory.py # 长期记忆读写基于 vector store truncation.py # 上下文长度超限时的回合裁剪 types.py # Response 专用类型ToolContext 等 utils.py # 输入输出转换、引用抽取等工具函数各文件的职责可以从源码逐一印证文件核心职责关键符号__init__.pyProvider 工厂装配依赖并初始化实现get_provider_impl(config, deps, policy)impl.py实现Responses接口桥接 store 与 OpenAI 实现采集遥测指标BuiltinResponsesImpl、_record_parameter_usage、_record_tool_usageconfig.py声明全部可配置项与默认提示词模板BuiltinResponsesImplConfig、CompactionConfig、MemoryConfigresponses/openai_responses.py请求处理、后台任务、持久化、记忆调度、护栏调用OpenAIResponsesImplresponses/streaming.py推理循环、事件流、工具执行协调、tool_choice 处理StreamingResponseOrchestratorresponses/tool_executor.py执行 file search / web search / MCP / function 工具未信任输出包裹ToolExecutorresponses/memory.py记忆上下文读取与摘要写入resolve_memory_context、write_conversation_memoryresponses/truncation.pytruncationauto时的回合级裁剪build_turn_groups、drop_oldest_turn三、依赖关系四个内部 API 的编排README 明确列出了该 provider 的依赖这与init.py 工厂函数 中get_provider_impl的解包逻辑完全一致依赖 API用途在工厂中的注入Api.inference发起 LLM 调用Chat Completionsdeps[Api.inference]Api.tool_runtime执行工具调用function / web / MCP 等deps[Api.tool_runtime]Api.vector_io文件搜索 / RAG / 记忆检索deps[Api.vector_io]Api.files文件管理上传、取内容、构造 data URLdeps[Api.files]Api.tool_groups工具分组定义deps[Api.tool_groups]Api.conversations多轮会话conversation状态deps[Api.conversations]Api.prompts提示词模板deps[Api.prompts]Api.connectorsMCP 连接器解析deps[Api.connectors]Api.skills技能可选注入deps.get(Api.skills)工厂函数还会把policy访问规则列表一并传入用于持久化时的访问控制见下文ResponsesStore。3.1 在分发配置中如何启用所有主要分发distribution都把responsesAPI 挂到inline::builtin这个 provider 上例如starter/starter.pynvidia/nvidia.pyoci/oci.pywatsonx/watsonx.pyopen-benchmark/open_benchmark.py典型配置片段对应官方文档 Configuring Responses Guardrailsproviders: responses: - provider_id: builtin provider_type: inline::builtin config: moderation_endpoint: ${env.MODERATION_ENDPOINT:}四、配置模型BuiltinResponsesImplConfig 全解配置全部集中在 config.py由四个部分组成persistence、vector_stores_config、compaction_config、memory_config外加两个护栏相关字段。4.1 persistence持久化BuiltinResponsesImplConfig.persistence为必填项其类型是ResponsesPersistenceConfig包含一个responses: ResponsesStoreReference。sample_run_config给出的默认值为{ persistence: { responses: {backend: sql_default, table_name: responses} } }也就是说response 对象默认持久化到 SQL 存储的responses表中从而支撑retrieve、list、delete等有状态操作。在 impl.py 的initialize()中ResponsesStore会基于该配置初始化并把policy作为访问控制依据若 SQL store 初始化失败会直接抛出RuntimeError。4.2 vector_stores_configVectorStoresConfig用于配置向量库的提示词模板与行为如 file search 的指令默认使用VectorStoresConfig()的默认值。它最终被传给OpenAIResponsesImpl与ToolExecutor影响文件搜索工具的检索质量。4.3 compaction_config对话压缩CompactionConfig负责对话历史过长时的自动压缩其字段如下字段默认值说明summarization_prompt内置的 CONTEXT CHECKPOINT COMPACTION 提示词指导模型把对话历史压缩成可交接的摘要包含进展、关键决策、上下文约束、待办事项、关键数据summary_prefix内置交接前缀文本在压缩摘要前拼接告知下一个 LLM 这是前任模型的思考过程摘要应基于其继续工作、避免重复劳动summarization_modelNone生成摘要所用的模型不设置则复用对话模型default_compact_thresholdNone自动压缩的 token 阈值设置后超过该 token 数的会话会被自动压缩即context_managementtokenizer_encodingNone默认 tiktoken 编码名如o200k_base、cl100k_base会作为服务端默认值可被请求extra_body覆盖未设置时按模型名解析 → 家族前缀映射 → 按字符估算的顺序推导model_tokenizer_mappingsllama/mistral/claude/gemma/qwen/phi/deepseek均映射到cl100k_base模型名前缀到 tiktoken 编码的启发式映射匹配时对去掉 provider 前缀后的模型名做大小写不敏感匹配如ollama/llama3.2:3b命中llama前缀管理员可扩展以支持自定义模型两个校验器validate_tokenizer_encoding、validate_model_tokenizer_mappings会在配置加载阶段用tiktoken.get_encoding()验证编码名合法性非法值会直接抛出ValueError避免运行时才暴露问题。从源码和测试可以确认压缩的两种触发路径显式压缩客户端调用/v1/responses/compact端点对应 impl.py 的compact_openai_response自动压缩context_management模式下超过default_compact_threshold阈值自动压缩对应集成测试 test_compact_responses.py 中的test_context_management_auto_compacts_large_input/test_context_management_none_does_not_compact等用例。4.4 memory_config长期记忆MemoryConfig是 alpha 特性默认关闭负责把对话摘要写入向量库并在后续会话中检索注入。关键字段字段默认值说明enabledFalse是否启用记忆读写默认关闭因为该功能处于 alpha 阶段default_vector_store_idNone显式指定存放记忆文件的向量库未设置时可按命名空间惰性创建内部默认记忆向量库auto_create_default_vector_storeTrue启用记忆且未配置default_vector_store_id时是否自动在每个命名空间创建内部默认记忆向量库default_vector_store_namespacedefault内部默认记忆向量库映射的命名空间default_vector_store_provider_idNone创建内部记忆向量库时使用的 vector_io provider未设置则用栈级默认向量库 providerdefault_vector_store_admin_principalogx:system:responses-memory拥有默认记忆向量库的内部主体default_vector_store_admin_attributes{roles: [admin]}打在默认记忆向量库上的访问属性便于管理员检查owner_metadata_keyowner_id向量库文件属性中用于按 owner 隔离的键memory_metadata_keymemory标识记忆文件的向量库文件属性键max_num_results5范围 1–50默认检索的最大记忆块数max_context_tokens1200注入记忆上下文的近似 token 预算read_prompt_template内置提示词为检索到的记忆上下文定调可能过时或不完整仅作情境回忆不要作为搜索结果引用write_enabledTrue是否在 stored response 完成后写入对话摘要write_debounce_seconds30.0写入前的去抖秒数让快速连续的多轮对话合并成一次写入summarization_prompt内置记忆摘要提示词生成长期记忆摘要要求包含稳定偏好/项目上下文/决策/约束排除密钥、短期状态等summarization_modelNone生成记忆摘要的模型不设置则用响应模型max_summary_messages100生成记忆摘要时使用的最近消息数上限max_transcript_chars20000记忆文件中可检索 transcript 部分的最大字符数记忆的读写实现在 memory.py读取时会把检索到的记忆上下文以system消息形式插入到消息列表最前_insert_memory_context保证插在所有 system/developer 消息之后写入则通过write_conversation_memory异步去抖完成openai_responses.py 中的_schedule_memory_write会检查memory_config.enabled、write_enabled、响应状态是否为completed、是否存在 conversation 与 owner 等条件。4.5 moderation_endpoint 与 moderation_headers护栏moderation_endpoint: str | None Field( defaultNone, descriptionURL of an OpenAI-compatible /v1/moderations endpoint for guardrails. The endpoint must accept POST {input: text} and return {results: [{flagged: bool, categories: {...}}]}., ) moderation_headers: dict[str, str] | None Field( defaultNone, descriptionHTTP headers to send with moderation endpoint requests. Use this to provide authentication for hosted moderation services ..., )要点端点必须兼容 OpenAI 的/v1/moderations协议接收POST {input: text}返回{results: [{flagged: bool, categories: {...}}]}moderation_headers用于携带认证等头部如{Authorization: Bearer sk-...}且仅存在于服务端绝不暴露给客户端请求中传入的 guardrail ID 会被转发为该审核请求的model字段见 configuration.mdx官方文档明确说明Safety / Shields API 已移除护栏现在直接调用外部 OpenAI 兼容审核端点。五、Agent 回合与工具调用循环的实现原理README 描述的核心机制是agent turns调用推理 → 执行工具 → 回填结果 → 重复直到模型输出最终答案。这一循环在 streaming.py 的StreamingResponseOrchestrator._run_inference_loop第 588 行起中实现构建OpenAIChatCompletionRequestWithExtraBody把 Response 输入转换为 Chat Completions 消息convert_response_input_to_chat_messages携带 tools、tool_choice、temperature、top_p、frequency_penalty、response_format、logprobs、parallel_tool_calls、reasoning_effort、service_tier、max_completion_tokens、prompt_cache_key、extra_body 等参数以while True循环推理每轮把模型输出的 tool_calls 交给ToolExecutor执行把工具结果以tool角色消息回填再次调用推理循环终止条件包括模型产出最终回复、达到max_output_tokens上限此时标记incompletereason 为max_output_tokens、上下文长度错误触发 truncation 裁剪后重试等tool_choice的解析由模块级函数_process_tool_choice处理支持 auto / required / none 以及按名称限定allowed_tools 过滤见_run_inference_loop中allowed_tool_names对effective_tools的过滤。5.1 ToolExecutor四类工具的执行引擎ToolExecutor 负责执行 file search、web search、MCP 与 function 四类工具调用并产出对应的事件类型如response.file_search_call.completed、response.web_search_call.completed、response.mcp_call.completed。一个值得关注的实现细节是未信任工具输出的包裹机制对于web_search、knowledge_search、file_search这类结果来源于模型无法控制的外部内容网页、索引文档的工具ToolExecutor会把其输出包裹在untrusted_tool_output标签内并附带提示文本仅作为数据分析或引用绝不能当作指令执行这是针对**间接提示注入indirect prompt injection**的缓解措施。_escape_delimiter_collisions还会对内容中出现的字面量标签做大小写不敏感的转义防止提前闭合包裹块源码注释也坦诚地说明了该方案的已知局限如空白填充变体无法拦截。5.2 MCP 工具与审批流types.py中的ToolContext承载了 MCP 工具的复用逻辑当新请求与上一轮 response 使用相同的 MCP serverserver_label相同且allowed_tools一致时直接复用上一轮输出中的mcp_list_tools对象与 server→tool 映射避免重复枚举工具列表recover_tools_from_previous_response。MCP 会话本身由 src/ogx/providers/utils/tools/mcp.py 的MCPSessionManager按(endpoint, headers_hash)缓存复用。此外ChatCompletionContext支持mcp_approval_request/mcp_approval_response输入项当工具名与参数 JSON 匹配到待审批请求时可携带客户端预先给出的审批响应继续执行。六、状态管理与持久化有状态 Response 的完整生命周期有状态是 Responses API 区别于普通 Chat Completions 的关键。OGX 的实现把每个 response 对象持久化到 SQL store从而支持以下操作全部在 impl.py 中暴露方法对应端点/操作行为create_openai_response创建非流式返回OpenAIResponseObject流式返回AsyncIterator[OpenAIResponseObjectStream]get_openai_responseretrieve按response_id读取list_openai_responseslist支持after、limit、model、order分页list_openai_response_input_items输入项列表支持after、before、include、limit、ordercompact_openai_responsecompact压缩历史生成摘要delete_openai_responsedelete删除 responsecancel_openai_responsecancel取消进行中的后台response6.1 previous_response_id 链式上下文_process_input_with_previous_responseopenai_responses.py实现了 Responses API 的previous_response_id语义取出上一个 response 的input output作为新输入的前缀并优先使用 store 中已保存的messages作为消息事实来源避免重复重建若上一个 response 仍处于queued/in_progress会明确拒绝以其作为前驱。测试 test_compact_responses.py 中的test_compact_with_previous_response_id覆盖了该路径。6.2 conversation 多轮会话当请求携带conversation时实现会读取该会话的历史 items 与已存消息拼接新输入后继续若 store 中无历史消息则从 conversations API 重建。对应集成测试见 test_conversation_responses.py基本流程、多轮流式、上下文加载、错误处理、向后兼容。6.3 后台执行与取消/超时OpenAIResponsesImpl维护了一个后台队列最大 100 项与 10 个 workerBACKGROUND_NUM_WORKERS 10用于处理排队型queued响应。每个后台响应的处理任务有 300 秒超时BACKGROUND_RESPONSE_TIMEOUT_SECONDS 300被取消cancel_openai_response→ 状态置为cancelled超时 → 状态置为failederror.code processing_error其他异常 → 同样置为failed并记录错误消息。worker 在请求所在的事件循环中惰性启动_ensure_workers_started避免初始化阶段临时事件循环销毁导致的 task 取消问题。6.4 流式事件的持久化流式模式下并非所有事件都会落库STREAMING_PERSISTED_EVENT_TYPES只持久化response.in_progress、response.output_item.done、response.completed、response.incomplete、response.failed五种关键事件平衡了状态可恢复性与写入开销。七、流式输出SSE与类型体系流式编排集中在 streaming.py核心类是StreamingResponseOrchestrator第 256 行。它把 Chat Completions 的增量 chunk 翻译成 OpenAI Responses 协议的事件流包括但不限于response.created、response.in_progress、response.completed、response.incomplete、response.failedresponse.output_item.added、response.output_item.doneresponse.content_part.added、response.content_part.doneresponse.output_text.delta、response.output_text.doneresponse.reasoning_text.delta、response.reasoning_text.doneresponse.function_call_arguments.delta、response.function_call_arguments.doneresponse.mcp_call_arguments.delta、response.mcp_call_arguments.done、response.mcp_list_tools.in_progress/completedresponse.web_search_call.in_progress/searching/completedresponse.file_search_call.in_progress/searching/completedresponse.refusal.delta/response.refusal.done实现还处理了推理内容reasoning content、拒答内容refusal的增量事件_handle_reasoning_content_chunk、_handle_refusal_content_chunk以及多轮工具调用的流式事件协调_coordinate_tool_execution。类型体系上types.py 定义了内部使用的AssistantMessageWithReasoning在 Responses 层与 provider 之间传递推理内容如映射到 Ollama/vLLM 的reasoning字段不属于公开 API、ToolExecutionResult、ChatCompletionResult聚合每次推理的内容、工具调用、finish_reason、logprobs、service_tier 等、ToolContext与ChatCompletionContext。utils.py则负责 Chat↔Responses 的消息/格式转换、文件内容 base64 data URL 构造construct_data_url、引用抽取extract_citations_from_text等其中APPROX_CHARS_PER_TOKEN 4用于字符级 token 估算。八、上下文超限的韧性truncation 与自动压缩truncation.py 实现了truncationauto时对上下文长度超限的响应式处理推理循环正常运行若 provider 返回上下文长度超限错误_is_context_length_error判定则触发turn-drop从消息列表中移除最旧的一个语义回合一组 user/assistant/tool 消息从某条 user 消息开始直到下一条 user 消息或历史结束然后从头重试推理system与developer消息永远受保护不会被丢弃build_turn_groups中归入protected列表当没有可丢弃的回合时全部受保护或列表为空drop_oldest_turn原样返回消息。与之配合的自动压缩context_management则由第 4.3 节的default_compact_threshold驱动测试用例覆盖了大输入自动压缩低于阈值不压缩none 不压缩三种行为。九、遥测可观测性设计BuiltinResponsesImpl在创建响应时采集三类 OpenTelemetry 指标定义见 src/ogx/telemetry/constants.py计数器创建于 impl.py指标含义RESPONSES_PARAMETER_USAGE_TOTAL请求中显式提供的可选参数按operationparameter打标签用于分析各参数的采用率RESPONSES_TOOL_TYPES_USED_TOTAL请求中出现的工具类型web_search 归一化后计数按tool_type打标签RESPONSES_AGENTIC_CALLS_TOTAL携带工具agentic的 Responses 调用总数其中_record_tool_usage只统计去重后的工具类型_REQUIRED_FIELDS {input, model}表示这两个必填字段不计入参数使用统计。十、集成测试行为如何被验证该 provider 的行为有大量集成测试背书主要集中在 tests/integration/responses 与 tests/integration/agents/test_openai_responses.py基础能力非流式/流式基本响应、增量内容、多轮、图片输入、logprobstest_basic_responses.py压缩基本会话压缩、单消息压缩、含工具调用压缩、previous_response_id 链式压缩、双重压缩、输入项隐藏压缩、自动压缩阈值test_compact_responses.py会话多轮工作流、流式多轮、上下文加载、错误处理test_conversation_responses.py文件搜索文本格式、按区域/类别/日期过滤、复合 AND/OR 过滤、流式事件test_file_search.py生态集成LangChain、LangGraph 的 Responses 接入测试test_langchain_responses.py、test_langgraph_responses.py存储生命周期创建→检索→删除→再检索抛NotFoundError的完整闭环test_openai_responses.py。此外tests/integration/responses/recordings/下存放了大量录制回放数据用于不依赖真实模型的可重复回归测试。结语OGX 的builtinresponses provider 是一个完整的 Agent 化 Responses API 实现它以四个内部 APIinference、tool_runtime、vector_io、files为底座通过StreamingResponseOrchestrator驱动多轮工具调用循环以 SQL store 支撑有状态的创建/检索/列表/压缩/删除/取消生命周期用CompactionConfig与truncation.py应对上下文增长用MemoryConfig提供基于向量库的长期记忆用外部/v1/moderations端点实现护栏并借助 OpenTelemetry 指标把调用行为透明化。理解它的配置模型与代码组织是你在自己的分发中定制 Responses 行为、排查流式与工具调用问题的基础。【免费下载链接】ogxOpen GenAI Stack项目地址: https://gitcode.com/GitHub_Trending/ll/ogx创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 OGX 内置 Responses Provider 深度解析：OpenAI Responses API 的 Agent 化实现与运行原理
OGX 内置 Responses Provider 深度解析OpenAI Responses API 的 Agent 化实现与运行原理【免费下载链接】ogxOpen GenAI Stack项目地址: https://gitcode.com/GitHub_Trending/ll/ogx导读本文围绕 OGXOpen GenAI Stack仓库中 src/ogx/providers/inline/responses/README.md 所描述的builtin内置responses provider 展开系统讲解它是如何实现 OpenAI Responses API、如何以多轮工具调用循环驱动 Agent 推理、如何通过 SSE 流式返回结果、如何用外部审核端点提供护栏Guardrails以及背后的配置模型、依赖关系和实现架构。读完本文你将掌握该 provider 的目录结构与核心调用链理解CompactionConfig、MemoryConfig、moderation_endpoint等配置项的真实作用并能在自己的 OGX 分发配置中正确启用和调优它。一、模块定位从agents到responses的内置实现在 OGX 中内置 Responses Providerbuiltin是responsesAPI 的标准实现它本身不调用任何外部模型服务而是把 OGX 内部的其他 APIinference、tool_runtime、vector_io、files 等编排起来对外呈现为与 OpenAI Responses API 兼容的/v1/responses端点。该模块位于 src/ogx/providers/inline/responses。根据其 README这个目录正在从agents重命名为responses对应 PR #5195因此你可能会在旧文档或旧代码中看到agents的称呼二者指的是同一个实现。该 provider 的核心能力有三点Agent 回合Agent turns多步推理与工具调用循环。Agent 调用推理 provider执行模型请求的工具把工具结果回填再继续推理直到模型产出最终回答OpenAI Responses API实现/v1/responses端点提供有状态stateful、与 OpenAI Responses API 兼容的 Agent 化接口支持内置工具web search、code interpreter、file search与自定义 function 工具Guardrails可选地通过外部审核端点对输入与输出做内容安全过滤。值得注意的是README 中提到的code interpreter工具在当前的源码树中未发现独立实现在src/ogx/providers/inline/responses/builtin/responses目录下搜索CodeInterpreter无命中从源码结构可以推断内置工具的实际落地以 web search、file search、MCP 工具和 function 工具为主这一点在配置与测试中都有体现。二、目录结构与各文件职责README 给出了该 provider 的目录结构。对照实际仓库当前目录为src/ogx/providers/inline/responses/builtin/其中responses/子目录下还增加了memory.py与truncation.py两个模块src/ogx/providers/inline/responses/builtin/ __init__.py # Provider 工厂get_provider_impl impl.py # 核心编排逻辑BuiltinResponsesImpl config.py # BuiltinResponsesImplConfig 及各子配置 responses/ # OpenAI Responses API 实现 __init__.py openai_responses.py # Responses API 处理器1820 行 streaming.py # SSE 流式编排2146 行 tool_executor.py # 工具调用执行引擎641 行 memory.py # 长期记忆读写基于 vector store truncation.py # 上下文长度超限时的回合裁剪 types.py # Response 专用类型ToolContext 等 utils.py # 输入输出转换、引用抽取等工具函数各文件的职责可以从源码逐一印证文件核心职责关键符号__init__.pyProvider 工厂装配依赖并初始化实现get_provider_impl(config, deps, policy)impl.py实现Responses接口桥接 store 与 OpenAI 实现采集遥测指标BuiltinResponsesImpl、_record_parameter_usage、_record_tool_usageconfig.py声明全部可配置项与默认提示词模板BuiltinResponsesImplConfig、CompactionConfig、MemoryConfigresponses/openai_responses.py请求处理、后台任务、持久化、记忆调度、护栏调用OpenAIResponsesImplresponses/streaming.py推理循环、事件流、工具执行协调、tool_choice 处理StreamingResponseOrchestratorresponses/tool_executor.py执行 file search / web search / MCP / function 工具未信任输出包裹ToolExecutorresponses/memory.py记忆上下文读取与摘要写入resolve_memory_context、write_conversation_memoryresponses/truncation.pytruncationauto时的回合级裁剪build_turn_groups、drop_oldest_turn三、依赖关系四个内部 API 的编排README 明确列出了该 provider 的依赖这与init.py 工厂函数 中get_provider_impl的解包逻辑完全一致依赖 API用途在工厂中的注入Api.inference发起 LLM 调用Chat Completionsdeps[Api.inference]Api.tool_runtime执行工具调用function / web / MCP 等deps[Api.tool_runtime]Api.vector_io文件搜索 / RAG / 记忆检索deps[Api.vector_io]Api.files文件管理上传、取内容、构造 data URLdeps[Api.files]Api.tool_groups工具分组定义deps[Api.tool_groups]Api.conversations多轮会话conversation状态deps[Api.conversations]Api.prompts提示词模板deps[Api.prompts]Api.connectorsMCP 连接器解析deps[Api.connectors]Api.skills技能可选注入deps.get(Api.skills)工厂函数还会把policy访问规则列表一并传入用于持久化时的访问控制见下文ResponsesStore。3.1 在分发配置中如何启用所有主要分发distribution都把responsesAPI 挂到inline::builtin这个 provider 上例如starter/starter.pynvidia/nvidia.pyoci/oci.pywatsonx/watsonx.pyopen-benchmark/open_benchmark.py典型配置片段对应官方文档 Configuring Responses Guardrailsproviders: responses: - provider_id: builtin provider_type: inline::builtin config: moderation_endpoint: ${env.MODERATION_ENDPOINT:}四、配置模型BuiltinResponsesImplConfig 全解配置全部集中在 config.py由四个部分组成persistence、vector_stores_config、compaction_config、memory_config外加两个护栏相关字段。4.1 persistence持久化BuiltinResponsesImplConfig.persistence为必填项其类型是ResponsesPersistenceConfig包含一个responses: ResponsesStoreReference。sample_run_config给出的默认值为{ persistence: { responses: {backend: sql_default, table_name: responses} } }也就是说response 对象默认持久化到 SQL 存储的responses表中从而支撑retrieve、list、delete等有状态操作。在 impl.py 的initialize()中ResponsesStore会基于该配置初始化并把policy作为访问控制依据若 SQL store 初始化失败会直接抛出RuntimeError。4.2 vector_stores_configVectorStoresConfig用于配置向量库的提示词模板与行为如 file search 的指令默认使用VectorStoresConfig()的默认值。它最终被传给OpenAIResponsesImpl与ToolExecutor影响文件搜索工具的检索质量。4.3 compaction_config对话压缩CompactionConfig负责对话历史过长时的自动压缩其字段如下字段默认值说明summarization_prompt内置的 CONTEXT CHECKPOINT COMPACTION 提示词指导模型把对话历史压缩成可交接的摘要包含进展、关键决策、上下文约束、待办事项、关键数据summary_prefix内置交接前缀文本在压缩摘要前拼接告知下一个 LLM 这是前任模型的思考过程摘要应基于其继续工作、避免重复劳动summarization_modelNone生成摘要所用的模型不设置则复用对话模型default_compact_thresholdNone自动压缩的 token 阈值设置后超过该 token 数的会话会被自动压缩即context_managementtokenizer_encodingNone默认 tiktoken 编码名如o200k_base、cl100k_base会作为服务端默认值可被请求extra_body覆盖未设置时按模型名解析 → 家族前缀映射 → 按字符估算的顺序推导model_tokenizer_mappingsllama/mistral/claude/gemma/qwen/phi/deepseek均映射到cl100k_base模型名前缀到 tiktoken 编码的启发式映射匹配时对去掉 provider 前缀后的模型名做大小写不敏感匹配如ollama/llama3.2:3b命中llama前缀管理员可扩展以支持自定义模型两个校验器validate_tokenizer_encoding、validate_model_tokenizer_mappings会在配置加载阶段用tiktoken.get_encoding()验证编码名合法性非法值会直接抛出ValueError避免运行时才暴露问题。从源码和测试可以确认压缩的两种触发路径显式压缩客户端调用/v1/responses/compact端点对应 impl.py 的compact_openai_response自动压缩context_management模式下超过default_compact_threshold阈值自动压缩对应集成测试 test_compact_responses.py 中的test_context_management_auto_compacts_large_input/test_context_management_none_does_not_compact等用例。4.4 memory_config长期记忆MemoryConfig是 alpha 特性默认关闭负责把对话摘要写入向量库并在后续会话中检索注入。关键字段字段默认值说明enabledFalse是否启用记忆读写默认关闭因为该功能处于 alpha 阶段default_vector_store_idNone显式指定存放记忆文件的向量库未设置时可按命名空间惰性创建内部默认记忆向量库auto_create_default_vector_storeTrue启用记忆且未配置default_vector_store_id时是否自动在每个命名空间创建内部默认记忆向量库default_vector_store_namespacedefault内部默认记忆向量库映射的命名空间default_vector_store_provider_idNone创建内部记忆向量库时使用的 vector_io provider未设置则用栈级默认向量库 providerdefault_vector_store_admin_principalogx:system:responses-memory拥有默认记忆向量库的内部主体default_vector_store_admin_attributes{roles: [admin]}打在默认记忆向量库上的访问属性便于管理员检查owner_metadata_keyowner_id向量库文件属性中用于按 owner 隔离的键memory_metadata_keymemory标识记忆文件的向量库文件属性键max_num_results5范围 1–50默认检索的最大记忆块数max_context_tokens1200注入记忆上下文的近似 token 预算read_prompt_template内置提示词为检索到的记忆上下文定调可能过时或不完整仅作情境回忆不要作为搜索结果引用write_enabledTrue是否在 stored response 完成后写入对话摘要write_debounce_seconds30.0写入前的去抖秒数让快速连续的多轮对话合并成一次写入summarization_prompt内置记忆摘要提示词生成长期记忆摘要要求包含稳定偏好/项目上下文/决策/约束排除密钥、短期状态等summarization_modelNone生成记忆摘要的模型不设置则用响应模型max_summary_messages100生成记忆摘要时使用的最近消息数上限max_transcript_chars20000记忆文件中可检索 transcript 部分的最大字符数记忆的读写实现在 memory.py读取时会把检索到的记忆上下文以system消息形式插入到消息列表最前_insert_memory_context保证插在所有 system/developer 消息之后写入则通过write_conversation_memory异步去抖完成openai_responses.py 中的_schedule_memory_write会检查memory_config.enabled、write_enabled、响应状态是否为completed、是否存在 conversation 与 owner 等条件。4.5 moderation_endpoint 与 moderation_headers护栏moderation_endpoint: str | None Field( defaultNone, descriptionURL of an OpenAI-compatible /v1/moderations endpoint for guardrails. The endpoint must accept POST {input: text} and return {results: [{flagged: bool, categories: {...}}]}., ) moderation_headers: dict[str, str] | None Field( defaultNone, descriptionHTTP headers to send with moderation endpoint requests. Use this to provide authentication for hosted moderation services ..., )要点端点必须兼容 OpenAI 的/v1/moderations协议接收POST {input: text}返回{results: [{flagged: bool, categories: {...}}]}moderation_headers用于携带认证等头部如{Authorization: Bearer sk-...}且仅存在于服务端绝不暴露给客户端请求中传入的 guardrail ID 会被转发为该审核请求的model字段见 configuration.mdx官方文档明确说明Safety / Shields API 已移除护栏现在直接调用外部 OpenAI 兼容审核端点。五、Agent 回合与工具调用循环的实现原理README 描述的核心机制是agent turns调用推理 → 执行工具 → 回填结果 → 重复直到模型输出最终答案。这一循环在 streaming.py 的StreamingResponseOrchestrator._run_inference_loop第 588 行起中实现构建OpenAIChatCompletionRequestWithExtraBody把 Response 输入转换为 Chat Completions 消息convert_response_input_to_chat_messages携带 tools、tool_choice、temperature、top_p、frequency_penalty、response_format、logprobs、parallel_tool_calls、reasoning_effort、service_tier、max_completion_tokens、prompt_cache_key、extra_body 等参数以while True循环推理每轮把模型输出的 tool_calls 交给ToolExecutor执行把工具结果以tool角色消息回填再次调用推理循环终止条件包括模型产出最终回复、达到max_output_tokens上限此时标记incompletereason 为max_output_tokens、上下文长度错误触发 truncation 裁剪后重试等tool_choice的解析由模块级函数_process_tool_choice处理支持 auto / required / none 以及按名称限定allowed_tools 过滤见_run_inference_loop中allowed_tool_names对effective_tools的过滤。5.1 ToolExecutor四类工具的执行引擎ToolExecutor 负责执行 file search、web search、MCP 与 function 四类工具调用并产出对应的事件类型如response.file_search_call.completed、response.web_search_call.completed、response.mcp_call.completed。一个值得关注的实现细节是未信任工具输出的包裹机制对于web_search、knowledge_search、file_search这类结果来源于模型无法控制的外部内容网页、索引文档的工具ToolExecutor会把其输出包裹在untrusted_tool_output标签内并附带提示文本仅作为数据分析或引用绝不能当作指令执行这是针对**间接提示注入indirect prompt injection**的缓解措施。_escape_delimiter_collisions还会对内容中出现的字面量标签做大小写不敏感的转义防止提前闭合包裹块源码注释也坦诚地说明了该方案的已知局限如空白填充变体无法拦截。5.2 MCP 工具与审批流types.py中的ToolContext承载了 MCP 工具的复用逻辑当新请求与上一轮 response 使用相同的 MCP serverserver_label相同且allowed_tools一致时直接复用上一轮输出中的mcp_list_tools对象与 server→tool 映射避免重复枚举工具列表recover_tools_from_previous_response。MCP 会话本身由 src/ogx/providers/utils/tools/mcp.py 的MCPSessionManager按(endpoint, headers_hash)缓存复用。此外ChatCompletionContext支持mcp_approval_request/mcp_approval_response输入项当工具名与参数 JSON 匹配到待审批请求时可携带客户端预先给出的审批响应继续执行。六、状态管理与持久化有状态 Response 的完整生命周期有状态是 Responses API 区别于普通 Chat Completions 的关键。OGX 的实现把每个 response 对象持久化到 SQL store从而支持以下操作全部在 impl.py 中暴露方法对应端点/操作行为create_openai_response创建非流式返回OpenAIResponseObject流式返回AsyncIterator[OpenAIResponseObjectStream]get_openai_responseretrieve按response_id读取list_openai_responseslist支持after、limit、model、order分页list_openai_response_input_items输入项列表支持after、before、include、limit、ordercompact_openai_responsecompact压缩历史生成摘要delete_openai_responsedelete删除 responsecancel_openai_responsecancel取消进行中的后台response6.1 previous_response_id 链式上下文_process_input_with_previous_responseopenai_responses.py实现了 Responses API 的previous_response_id语义取出上一个 response 的input output作为新输入的前缀并优先使用 store 中已保存的messages作为消息事实来源避免重复重建若上一个 response 仍处于queued/in_progress会明确拒绝以其作为前驱。测试 test_compact_responses.py 中的test_compact_with_previous_response_id覆盖了该路径。6.2 conversation 多轮会话当请求携带conversation时实现会读取该会话的历史 items 与已存消息拼接新输入后继续若 store 中无历史消息则从 conversations API 重建。对应集成测试见 test_conversation_responses.py基本流程、多轮流式、上下文加载、错误处理、向后兼容。6.3 后台执行与取消/超时OpenAIResponsesImpl维护了一个后台队列最大 100 项与 10 个 workerBACKGROUND_NUM_WORKERS 10用于处理排队型queued响应。每个后台响应的处理任务有 300 秒超时BACKGROUND_RESPONSE_TIMEOUT_SECONDS 300被取消cancel_openai_response→ 状态置为cancelled超时 → 状态置为failederror.code processing_error其他异常 → 同样置为failed并记录错误消息。worker 在请求所在的事件循环中惰性启动_ensure_workers_started避免初始化阶段临时事件循环销毁导致的 task 取消问题。6.4 流式事件的持久化流式模式下并非所有事件都会落库STREAMING_PERSISTED_EVENT_TYPES只持久化response.in_progress、response.output_item.done、response.completed、response.incomplete、response.failed五种关键事件平衡了状态可恢复性与写入开销。七、流式输出SSE与类型体系流式编排集中在 streaming.py核心类是StreamingResponseOrchestrator第 256 行。它把 Chat Completions 的增量 chunk 翻译成 OpenAI Responses 协议的事件流包括但不限于response.created、response.in_progress、response.completed、response.incomplete、response.failedresponse.output_item.added、response.output_item.doneresponse.content_part.added、response.content_part.doneresponse.output_text.delta、response.output_text.doneresponse.reasoning_text.delta、response.reasoning_text.doneresponse.function_call_arguments.delta、response.function_call_arguments.doneresponse.mcp_call_arguments.delta、response.mcp_call_arguments.done、response.mcp_list_tools.in_progress/completedresponse.web_search_call.in_progress/searching/completedresponse.file_search_call.in_progress/searching/completedresponse.refusal.delta/response.refusal.done实现还处理了推理内容reasoning content、拒答内容refusal的增量事件_handle_reasoning_content_chunk、_handle_refusal_content_chunk以及多轮工具调用的流式事件协调_coordinate_tool_execution。类型体系上types.py 定义了内部使用的AssistantMessageWithReasoning在 Responses 层与 provider 之间传递推理内容如映射到 Ollama/vLLM 的reasoning字段不属于公开 API、ToolExecutionResult、ChatCompletionResult聚合每次推理的内容、工具调用、finish_reason、logprobs、service_tier 等、ToolContext与ChatCompletionContext。utils.py则负责 Chat↔Responses 的消息/格式转换、文件内容 base64 data URL 构造construct_data_url、引用抽取extract_citations_from_text等其中APPROX_CHARS_PER_TOKEN 4用于字符级 token 估算。八、上下文超限的韧性truncation 与自动压缩truncation.py 实现了truncationauto时对上下文长度超限的响应式处理推理循环正常运行若 provider 返回上下文长度超限错误_is_context_length_error判定则触发turn-drop从消息列表中移除最旧的一个语义回合一组 user/assistant/tool 消息从某条 user 消息开始直到下一条 user 消息或历史结束然后从头重试推理system与developer消息永远受保护不会被丢弃build_turn_groups中归入protected列表当没有可丢弃的回合时全部受保护或列表为空drop_oldest_turn原样返回消息。与之配合的自动压缩context_management则由第 4.3 节的default_compact_threshold驱动测试用例覆盖了大输入自动压缩低于阈值不压缩none 不压缩三种行为。九、遥测可观测性设计BuiltinResponsesImpl在创建响应时采集三类 OpenTelemetry 指标定义见 src/ogx/telemetry/constants.py计数器创建于 impl.py指标含义RESPONSES_PARAMETER_USAGE_TOTAL请求中显式提供的可选参数按operationparameter打标签用于分析各参数的采用率RESPONSES_TOOL_TYPES_USED_TOTAL请求中出现的工具类型web_search 归一化后计数按tool_type打标签RESPONSES_AGENTIC_CALLS_TOTAL携带工具agentic的 Responses 调用总数其中_record_tool_usage只统计去重后的工具类型_REQUIRED_FIELDS {input, model}表示这两个必填字段不计入参数使用统计。十、集成测试行为如何被验证该 provider 的行为有大量集成测试背书主要集中在 tests/integration/responses 与 tests/integration/agents/test_openai_responses.py基础能力非流式/流式基本响应、增量内容、多轮、图片输入、logprobstest_basic_responses.py压缩基本会话压缩、单消息压缩、含工具调用压缩、previous_response_id 链式压缩、双重压缩、输入项隐藏压缩、自动压缩阈值test_compact_responses.py会话多轮工作流、流式多轮、上下文加载、错误处理test_conversation_responses.py文件搜索文本格式、按区域/类别/日期过滤、复合 AND/OR 过滤、流式事件test_file_search.py生态集成LangChain、LangGraph 的 Responses 接入测试test_langchain_responses.py、test_langgraph_responses.py存储生命周期创建→检索→删除→再检索抛NotFoundError的完整闭环test_openai_responses.py。此外tests/integration/responses/recordings/下存放了大量录制回放数据用于不依赖真实模型的可重复回归测试。结语OGX 的builtinresponses provider 是一个完整的 Agent 化 Responses API 实现它以四个内部 APIinference、tool_runtime、vector_io、files为底座通过StreamingResponseOrchestrator驱动多轮工具调用循环以 SQL store 支撑有状态的创建/检索/列表/压缩/删除/取消生命周期用CompactionConfig与truncation.py应对上下文增长用MemoryConfig提供基于向量库的长期记忆用外部/v1/moderations端点实现护栏并借助 OpenTelemetry 指标把调用行为透明化。理解它的配置模型与代码组织是你在自己的分发中定制 Responses 行为、排查流式与工具调用问题的基础。【免费下载链接】ogxOpen GenAI Stack项目地址: https://gitcode.com/GitHub_Trending/ll/ogx创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考