agno 实战：OpenAI 推理模型（o3-mini / o4-mini / gpt-4.1）的 effort、stream 与 summary 三模式深度解析
【免费下载链接】agnoBuild, run, and manage agent platforms.项目地址: https://gitcode.com/GitHub_Trending/ag/agno
本文基于 agno 仓库cookbook/10_reasoning/models/openai/目录下的推理模型示例（README）展开，系统讲解如何用 agno 接入 OpenAI 推理系列模型，覆盖reasoning_effort（推理力度）、reasoning_stream（推理流式输出）与reasoning_summary（推理摘要）三大核心能力，并结合libs/agno/agno/models/openai/源码与libs/agno/agno/run/agent.py事件系统，帮助读者从"会跑示例"进阶到"理解推理链路底层机制"，可直接套用到自己的 Agent 与工具编排场景中。
一、为什么在 agno 中使用 OpenAI 推理模型
OpenAI 的 o3-mini、o4-mini 等推理模型（reasoning models）会在生成最终答案之前进行"思考"（reasoning），在处理复杂问题（如伦理难题分析、多维度对比报告、长历史背景推理）时显著提升回答质量。agno 将其封装为开箱即用的模型后端，核心价值体现在：
- 统一接入：通过
agno.models.openai模块即可使用 Chat Completions 与 Responses API 两种后端，无需关心底层协议差异； - 参数透传：
reasoning_effort、reasoning_summary等推理专属参数直接作为模型构造参数暴露，配置直观； - 事件化流式：推理过程与最终输出通过
RunEvent事件流区分，开发者可以精确控制"思考中"与"回答中"的 UI 呈现。
本目录共提供 6 个示例，分别覆盖：纯推理（o3_mini.py）、推理 + 工具（o3_mini_with_tools.py）、推理力度调节（reasoning_effort.py）、独立推理模型（reasoning_model_gpt_4_1.py）、推理流式事件（reasoning_stream.py）、推理摘要（reasoning_summary.py）。下面逐一展开。
二、最小示例：用 o3-mini 完成一次推理问答
o3_mini.py 展示了最精简的接入方式——只需指定模型 ID 即可：
from agno.agent import Agent from agno.models.openai import OpenAIChat agent = Agent( model=OpenAIChat(id="o3-mini"), ) agent.print_response( "Solve the trolley problem. Evaluate multiple ethical frameworks. " "Include an ASCII diagram of your solution.", stream=True, )关键点：
OpenAIChat是 agno 对 OpenAI Chat Completions 后端的封装，id="o3-mini"指定推理模型；- 提示词刻意要求"评估多个伦理框架 + 绘制 ASCII 示意图"，这正是推理模型的强项场景——o3-mini 会先在内部展开推理，再输出结构化的多视角分析；
stream=True开启流式输出，最终答案会逐段打印。
从源码看，OpenAIChat与OpenAIResponses同属于 libs/agno/agno/models/openai/ 模块，两者都支持推理参数，只是底层 API 不同（Responses API 的推理控制更完整，详见后文）。
三、推理 + 工具：让 o3-mini 联网取证后作答
o3_mini_with_tools.py 在上一示例基础上挂载了搜索工具，实现"先检索、再推理、后总结"的完整链路：
from agno.agent import Agent from agno.models.openai import OpenAIChat from agno.tools.websearch import WebSearchTools agent = Agent( model=OpenAIChat(id="o3-mini"), tools=[WebSearchTools(enable_news=False)], instructions="Use tables to display data.", markdown=True, ) agent.print_response("Write a report comparing NVDA to TSLA", stream=True)要点解读：
- 工具即推理素材：
WebSearchTools(enable_news=False)禁用新闻类结果，聚焦结构化财经数据；Agent 会自主决定何时调用搜索工具获取 NVDA 与 TSLA 的最新行情与财务指标； - 输出约束：
instructions="Use tables to display data."要求最终报告以表格呈现，配合markdown=True获得格式化输出——推理模型擅长在工具返回数据的基础上做对比归纳； - 该模式适用于所有"结论依赖实时数据"的场景，例如竞品分析、市场调研、技术选型报告。
四、reasoning_effort：精确控制推理强度
reasoning_effort.py 演示了推理力度参数的用法：
agent = Agent( model=OpenAIChat(id="o3-mini", reasoning_effort="high"), tools=[WebSearchTools(enable_news=False)], instructions="Use tables to display data.", markdown=True, )reasoning_effort直接决定模型在"思考"阶段投入的计算量，直接影响推理深度、延迟与成本：
| 取值 | 含义 | 适用场景 |
|---|---|---|
none | 关闭推理 | 简单问答、低延迟诉求 |
minimal | 极少推理 | 格式化、改写类任务 |
low | 轻量推理 | 常规信息查询 |
medium | 中等推理 | 一般分析任务（默认档位） |
high | 较强推理 | 复杂多步推理 |
xhigh | 高强度推理 | 高难度数学/代码题 |
max | 最大推理力度 | 最复杂、可接受高成本的任务 |
从源码确认，该类型定义于 libs/agno/agno/models/openai/types.py：ReasoningEffort = Union[Literal["none", "minimal", "low", "medium", "high", "xhigh", "max"], str]，即在 responses.py 中会被映射到请求体reasoning.effort字段，最终由 OpenAI 服务端生效。str兜底意味着未来新增档位也能直接透传，无需升级 agno。
实践建议：对延迟敏感的应用从low起步，对正确性敏感的任务（代码生成、数学推理）使用high及以上，并按响应质量与成本折衷调优。
五、reasoning_model：独立指定"思考模型"与"回答模型"
reasoning_model_gpt_4_1.py 展示了 agno 推理链路中最灵活的能力——把"思考"和"回答"拆给两个不同的模型：
from agno.agent import Agent from agno.models.openai.responses import OpenAIResponses agent = Agent( model=OpenAIResponses(id="gpt-5.6-luna"), reasoning_model=OpenAIResponses(id="gpt-4.1"), ) agent.print_response( "Solve the trolley problem. Evaluate multiple ethical frameworks. " "Include an ASCII diagram of your solution.", stream=True, )设计意图：
model负责产出最终答案，reasoning_model负责先行的推理过程；- 例如可以"用一个推理能力强的模型想清楚、用一个输出风格更好的模型作答"，在成本与质量之间取得平衡；
- 源码层面，
OpenAIResponses._using_reasoning_model()（见 responses.py）会判断是否配置了独立推理模型，并在请求构造时把推理模型与主模型分别下发；同时当启用独立推理模型且未显式关闭时，会结合store参数管理会话上下文（responses.py）。
注意：示例中
gpt-5.6-luna、gpt-4.1为仓库编写时使用的模型 ID，实际运行时请替换为你账户可用的模型名。
六、推理流式输出：用 RunEvent 捕捉"思考过程"
reasoning_stream.py 是理解 agno 推理链路的关键示例。它默认使用print_response(stream=True, stream_events=True)一键打印全部事件，同时注释了手动事件循环的完整写法：
from agno.agent import Agent from agno.models.openai import OpenAIResponses from agno.run.agent import RunEvent # noqa agent = Agent( reasoning_model=OpenAIResponses( id="o3-mini", reasoning_effort="low", ), instructions="Think step by step about the problem.", ) prompt = "Analyze the key factors that led to the signing of the Treaty of Versailles in 1919 ..." agent.print_response(prompt, stream=True, stream_events=True)手动事件循环可以精确感知推理全过程的每个阶段：
for run_output_event in agent.run(prompt, stream=True, stream_events=True): if run_output_event.event == RunEvent.run_started: print(f"\nEVENT: {run_output_event.event}") elif run_output_event.event == RunEvent.reasoning_started: print("Reasoning started...\n") elif run_output_event.event == RunEvent.reasoning_content_delta: # 推理内容的增量流式事件 print(run_output_event.reasoning_content, end="", flush=True) elif run_output_event.event == RunEvent.reasoning_step: print(f"\nEVENT: {run_output_event.event}") elif run_output_event.event == RunEvent.reasoning_completed: print(f"\n\nEVENT: {run_output_event.event}") elif run_output_event.event == RunEvent.run_content: if run_output_event.content: print(run_output_event.content, end="", flush=True) elif run_output_event.event == RunEvent.run_completed: print(f"\n\nEVENT: {run_output_event.event}")这些事件的枚举定义与事件模型位于 libs/agno/agno/run/agent.py：
| 事件 | 触发时机 | 负载字段 |
|---|---|---|
reasoning_started | 推理阶段开始 | — |
reasoning_step | 完成一个推理步骤 | — |
reasoning_content_delta | 推理内容增量到达（流式） | reasoning_content |
reasoning_completed | 推理阶段结束、即将输出正式回答 | — |
run_content/run_completed | 正式回答的增量与完成 | content |
实战价值：在 Web UI 中，你可以用reasoning_started显示"正在思考…"的动画，用reasoning_content_delta实时滚动思考过程，用reasoning_completed切换回正式回答流，让用户完整感知 Agent 的思考路径。
七、reasoning_summary：只输出推理摘要，节省 tokens
reasoning_summary.py 演示了 Responses API 的推理摘要能力：
from agno.agent import Agent from agno.models.openai import OpenAIResponses from agno.tools.websearch import WebSearchTools agent = Agent( model=OpenAIResponses( id="o4-mini", reasoning_summary="auto", # 请求推理摘要 ), tools=[WebSearchTools(enable_news=False)], instructions="Use tables to display the analysis", markdown=True, ) agent.print_response("Write a brief report comparing NVDA to TSLA", stream=True)- 解决什么问题：推理模型输出的完整思考链可能很长，若终端用户不需要看全部过程，
reasoning_summary可让服务端只返回一份简洁的推理摘要，显著降低输出 tokens 与延迟； - 可选项：
ReasoningSummary = Union[Literal["auto", "concise", "detailed"], str]（见 libs/agno/agno/models/openai/types.py）——auto让模型自行决定，concise尽量精简，detailed保留较多推理细节； - 源码对应：在 responses.py 中，该参数被写入请求体
reasoning.summary；返回时，推理摘要会通过response.reasoning_summary_text.delta流式事件送达，并被归并到model_response.reasoning_content（responses.py），因此与上一节的reasoning_content_delta事件无缝衔接，前端渲染逻辑完全复用。
八、OpenAIChat 与 OpenAIResponses 的选择建议
两个示例文件分别使用了agno.models.openai.OpenAIChat与agno.models.openai.responses.OpenAIResponses，二者可从以下维度区分：
| 维度 | OpenAIChat（Chat Completions） | OpenAIResponses（Responses API） |
|---|---|---|
| 底层协议 | /chat/completions | /responses |
| 推理参数 | 支持reasoning_effort | 支持reasoning_effort、reasoning_summary、独立reasoning_model |
| 推理流式事件 | 基础增量 | 完整的reasoning_content_delta/reasoning_summary_text.delta等 |
| 适用场景 | 常规 Agent、兼容性优先 | 深度使用推理能力、需要精细控制思考链路 |
从源码看，OpenAIResponses的请求构造将reasoning_effort与reasoning_summary统一收敛到reasoning对象（responses.py），是当前推理能力最完整的入口。若你的应用需要"推理摘要 + 独立推理模型 + 精细流式事件"，优先选OpenAIResponses。
九、运行环境与快速验证
- 安装依赖：确保已安装 agno（本仓库位于 libs/agno/），并设置
OPENAI_API_KEY环境变量； - 运行示例（以本目录为例）：
export OPENAI_API_KEY=sk-... python cookbook/10_reasoning/models/openai/o3_mini.py python cookbook/10_reasoning/models/openai/reasoning_summary.py- 模型可用性：
o3-mini、o4-mini等推理模型 ID 需在你的 OpenAI 账户下可用；reasoning_model_gpt_4_1.py中的gpt-5.6-luna为示例编写时的 ID，请按实际可用模型替换； - 流式验证：运行
reasoning_stream.py时，先观察"思考过程"逐字打印，再看到正式回答，即可确认推理链路完整生效。
十、小结：三条能力线如何组合
本目录虽只含 6 个示例，却覆盖了推理模型接入的全部核心维度，可以自由组合：
- 力度控制：
reasoning_effort决定"想多深"——low到max七档可选，兼顾延迟与质量； - 链路拆分：
reasoning_model允许"思考"与"回答"分属不同模型，优化成本结构； - 过程可视化：
RunEvent推理事件流让思考过程可被 UI 完整呈现； - 输出裁剪：
reasoning_summary在不需要全量思考链时压缩输出，节省 tokens。
三者叠加即可构建"低延迟、可解释、成本可控"的生产级推理 Agent。更多推理相关示例（覆盖 Anthropic、Gemini、DeepSeek、xAI 等模型）可参阅 cookbook/10_reasoning/ 顶层目录，源码级实现细节可继续阅读 libs/agno/agno/models/openai/responses.py 与 libs/agno/agno/run/agent.py。
【免费下载链接】agnoBuild, run, and manage agent platforms.项目地址: https://gitcode.com/GitHub_Trending/ag/agno
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
