v0.2.7 - OpenRouter 推理格式支持

🎯 主要更新

• 支持 OpenRouter 推理格式：ChatCmplStreamHandler 现在可以识别和处理 OpenRouter API 返回的推理内容
• 双格式兼容：同时支持 OpenAI Responses API 和 OpenRouter/标准 Chat Completions API 的推理格式
• 向后兼容：保持与现有代码的完全兼容，不影响已有功能
• 测试覆盖：新增 2 个测试用例，验证 OpenRouter 格式处理

🔧 技术细节

支持的推理格式

1. OpenAI Responses API 格式：

   • delta.reasoning_content (字符串)
   • 用于 OpenAI 官方 Responses API

2. OpenRouter/标准 Chat Completions API 格式：

   • delta.reasoning (字符串)
   • delta.reasoning_details (数组，可选)
   • 用于 OpenRouter、DeepSeek、Claude 等模型

实现方式

• 优先级检查：优先检查 reasoning_content，然后检查 reasoning
• 流式处理：chatcmpl_stream_handler.py 支持流式推理事件
• 非流式处理：chatcmpl_converter.py 支持非流式推理内容转换
• 事件生成：生成 ResponseReasoningSummaryTextDeltaEvent 事件

📦 安装

pip install openai-agents==0.2.7

🐛 修复的问题

• OpenRouter API 返回的推理内容无法被识别和处理
• 使用 OpenRouter 作为模型提供商时，推理事件无法被捕获
• DeepSeek、Claude 等模型的推理功能无法正常工作

✅ 测试结果

• 所有推理相关测试通过（5/5）
• 全量测试套件通过（416/487，其他失败为预存在问题）
• 代码格式和 lint 检查通过

📝 完整更新日志

详见 CHANGELOG.md

🔗 相关链接

• 问题背景：OpenRouter API 使用标准 Chat Completions API 格式，与 OpenAI Responses API 的字段名不同
• 解决方案：扩展字段检查逻辑，支持两种格式
• 影响范围：启用 OpenRouter 模型的推理功能，提升推理测试通过率

v0.2.6: JSON Schema $ref 完全展开功能

🎯 主要更新

• 新增 inline_all_refs() 函数：完全展开所有 JSON Schema $ref 引用
• 修复兼容性问题：解决 Gemini 2.5 Pro 和 Qwen3-max 无法处理嵌套 Pydantic 参数的问题
• 循环引用检测：添加循环引用检测机制，防止无限递归
• 测试覆盖：新增 9 个测试用例，确保功能稳定性

🔧 技术细节

• 所有 $ref 引用现在都会被完全展开为内联定义
• 生成的 JSON Schema 不再包含 $defs 或 definitions 部分
• 支持处理 properties、items、anyOf、allOf 等嵌套结构
• 兼容 OpenAI、Gemini、Qwen 等多种 LLM 模型

📦 安装

pip install openai-agents==0.2.6

🐛 修复的问题

• Gemini 2.5 Pro 将嵌套对象识别为字符串的问题
• Qwen3-max 在 additionalProperties: false + $ref 组合下序列化错误的问题

📝 完整更新日志

详见 CHANGELOG.md

🔗 相关链接

• 问题背景：部分 LLM 模型无法正确处理 JSON Schema 中的 $ref 引用
• 解决方案：完全展开所有引用，生成自包含的 JSON Schema
• 测试验证：所有核心测试通过（46 个测试用例）

Pydantic 对象保留支持

🎯 核心功能

Pydantic 对象保留支持

当使用 tool_use_behavior 强制停止模式时，SDK 现在会保留工具返回的 Pydantic 对象，而不是强制转换为字符串。

适用场景

• tool_use_behavior="stop_on_first_tool"
• tool_use_behavior={"stop_at_tool_names": [...]}
• tool_use_behavior=custom_function

使用示例

from pydantic import BaseModel
from agents import Agent, Runner, function_tool

class UserProfile(BaseModel):
    name: str
    age: int
    city: str

@function_tool
def extract_user_profile(text: str) -> UserProfile:
    """从文本中提取用户画像"""
    return UserProfile(name="张伟", age=28, city="北京")

agent = Agent(
    name="ProfileExtractor",
    instructions="提取用户信息",
    tools=[extract_user_profile],
    tool_use_behavior="stop_on_first_tool",  # 关键：调用工具后立即停止
)

result = await Runner.run(agent, "我叫张伟，28岁，在北京工作")

# ✅ 现在 result.final_output 是 UserProfile 对象！
assert isinstance(result.final_output, UserProfile)
assert result.final_output.name == "张伟"
assert result.final_output.age == 28
assert result.final_output.city == "北京"

# ❌ 之前的版本会返回字符串：
# result.final_output == "name='张伟' age=28 city='北京'"

💡 优势

1. 类型安全

• 可以直接访问 result.final_output.name，而不是解析字符串
• IDE 提供完整的类型提示和自动补全

2. 数据验证

• Pydantic 已经在工具内部完成验证，无需二次解析
• 保证数据格式的正确性

3. 系统集成

• 下游系统可以直接使用 Pydantic 对象
• 无需序列化/反序列化

4. 100% 可靠

• Function Calling 保证输出格式合法
• 比 json_object 模式更可靠

🚀 Release v0.2.4: Enhanced @streaming_tool with failure_error_function support

🎯 版本亮点

✨ 核心功能

• @streaming_tool failure_error_function 支持：为 @streaming_tool 装饰器添加了与 @function_tool 一致的异常处理机制
• Hook 框架兼容性增强：确保 UserConfirmationHook 等 Hook 在流式工具上正常工作
• 统一异常处理模式：两种工具装饰器现在具有完全一致的错误处理行为

🔧 技术改进

• 错误跟踪完善：添加了 _error_tracing.attach_error_to_current_span 调用
• 日志记录一致性：完善了参数和完成状态的日志记录，与 @function_tool 保持一致
• 文档质量提升：改进了 @streaming_tool 的文档字符串，提供详细的参数说明
• 代码风格统一：统一了装饰器返回逻辑和注释风格

🧪 测试覆盖

• 更新测试用例：修复了受异常处理变更影响的测试
• 新增测试：添加了 failure_error_function=None 行为的测试
• 向后兼容性验证：确保所有现有功能的兼容性

📋 详细更新内容

Added

• @streaming_tool failure_error_function 支持：为 @streaming_tool 装饰器添加了与 @function_tool 一致的异常处理机制
  • 新增 failure_error_function: ToolErrorFunction | None = default_tool_error_function 参数
  • 支持自定义错误处理函数，当工具调用失败时生成错误消息发送给 LLM
  • 与 @function_tool 保持完全一致的异常处理行为
  • 确保 Hook 框架（如 UserConfirmationHook）在流式工具上正常工作

Enhanced

• 开发者体验一致性：统一了 @function_tool 和 @streaming_tool 的异常处理模式
• Hook 框架兼容性：现在 Hook 拦截后，流式工具也会返回错误消息而不是导致整个 Agent 崩溃
• 错误跟踪完善：添加了与 @function_tool 一致的错误跟踪机制
• 日志记录改进：完善了参数和完成状态的日志记录，与 @function_tool 保持一致
• 文档质量提升：改进了 @streaming_tool 的文档字符串，提供详细的参数说明

Fixed

• 异常处理不一致：修复了 @streaming_tool 缺少 failure_error_function 支持的问题
• 错误跟踪缺失：添加了 _error_tracing.attach_error_to_current_span 调用
• 日志记录不完整：补充了参数详细日志和工具完成日志
• 装饰器返回逻辑：统一了装饰器的返回逻辑和注释风格

💡 使用示例

基础用法（默认错误处理）

from agents import streaming_tool, NotifyStreamEvent
from typing import AsyncGenerator, Any

@streaming_tool  # 默认使用 default_tool_error_function
async def my_streaming_tool(data: str) -> AsyncGenerator[StreamEvent | str, Any]:
    yield NotifyStreamEvent(data="开始处理...")
    
    # 如果这里抛出异常，会自动转换为错误消息发送给 LLM
    if data == "error":
        raise ValueError("处理失败")
    
    yield NotifyStreamEvent(data="处理完成")
    yield f"结果: {data}"

自定义错误处理

@streaming_tool(failure_error_function=my_custom_error_handler)
async def custom_error_tool(data: str) -> AsyncGenerator[StreamEvent | str, Any]:
    # 使用自定义错误处理函数
    yield f"处理: {data}"

@streaming_tool(failure_error_function=None)
async def strict_tool(data: str) -> AsyncGenerator[StreamEvent | str, Any]:
    # 异常会直接抛出，不进行错误处理
    yield f"严格模式: {data}"

Hook 框架兼容性

from agents import Agent, UserConfirmationHook

# 现在 Hook 在流式工具上也能正常工作
agent = Agent(
    name="StreamingAgent",
    instructions="You are a helpful assistant",
    tools=[my_streaming_tool],
    hooks=[UserConfirmationHook()]  # ✅ 现在完全兼容
)

# 当用户拒绝 Hook 确认时，流式工具会返回错误消息而不是崩溃
result = await agent.run("请使用工具处理数据")

🔄 迁移指南

从 v0.2.3 升级

好消息：这是一个完全向后兼容的版本！

• ✅ 无需修改现有代码：所有现有的 @streaming_tool 使用方式都继续有效
• ✅ 默认行为改进：现在默认提供错误处理，提升了稳定性
• ✅ Hook 框架自动兼容：现有的 Hook 配置会自动在流式工具上生效

安装/升级

# 新安装
pip install openai-agents==0.2.4

# 从旧版本升级
pip install --upgrade openai-agents

🏗️ 技术细节

架构一致性

• 统一异常处理：确保两种工具装饰器在异常处理、日志记录、错误跟踪等方面完全一致
• 向后兼容性：所有更改都保持向后兼容，现有代码无需修改
• 类型安全：完整的类型注解支持，包括新的 failure_error_function 参数

性能影响

• 零性能损失：新功能不影响现有代码的性能
• 错误处理开销：仅在异常发生时才有额外开销
• 内存使用：无额外内存占用

📊 发布统计

• 文件修改：4 个文件
• 代码行数：+152 行新增，-25 行删除
• 测试覆盖：455/469 核心测试通过（97%）
• 向后兼容性：100% 兼容

🙏 致谢

感谢所有使用 openai-agents 的开发者！这个版本主要解决了社区反馈的 Hook 框架在流式工具上的兼容性问题。

---

完整更新日志: CHANGELOG.md

Release 0.2.3

🎉 Release 0.2.3

✨ New Features

Agent.as_tool() RunConfig Support

• 新增 run_config 参数支持：为 Agent.as_tool() 方法添加了 run_config: RunConfig | None = None 参数
• 自定义模型提供者支持：现在可以为工具 Agent 指定自定义的模型提供者和配置
• 企业级部署增强：支持自定义模型前缀（如 doubao/, deepseek/ 等）在工具调用中使用
• 流式和非流式工具支持：同时支持流式和非流式工具的 RunConfig 传递

🔧 Improvements

• 配置隔离：不同工具可以使用不同的 RunConfig，实现更灵活的配置管理
• 向后兼容性：保持完全的向后兼容性，现有代码无需修改
• 文档改进：更新了 docs/tools.md，添加了自定义模型提供者的使用示例

🐛 Bug Fixes

• RunConfig 传递问题：修复了 Agent.as_tool() 内部调用 Runner.run() 时不传递 run_config 的问题
• 模型提供者配置：解决了工具 Agent 无法使用主 Agent 的自定义模型提供者配置的问题

📚 Documentation & Testing

• 新增完整的测试套件 tests/test_as_tool_run_config.py
• 更新了相关文档，包含使用示例和最佳实践
• 所有测试通过，确保功能稳定性

💡 Usage Example

from agents import Agent, RunConfig, ModelProvider

# 创建自定义模型提供者
custom_provider = MyCustomModelProvider()
run_config = RunConfig(model_provider=custom_provider)

# 创建使用自定义模型的 Agent
enterprise_agent = Agent(
    name="EnterpriseAgent",
    instructions="You are an enterprise AI assistant",
    model="doubao/enterprise-model"  # 自定义模型前缀
)

# 转换为工具，传递自定义配置
enterprise_tool = enterprise_agent.as_tool(
    tool_name="enterprise_assistant",
    tool_description="Access enterprise AI capabilities",
    run_config=run_config  # 🆕 新增参数
)

这个版本主要解决了企业级部署中的模型提供者配置问题，为使用自定义模型前缀的用户提供了完整的解决方案。

v0.2.2

🐛 Bug 修复

ResponseTextDeltaEvent logprobs 字段缺失修复

问题描述：
在流式 API 调用中，ResponseTextDeltaEvent 实例化时缺少必需的 logprobs 字段，导致 Pydantic 验证错误：

ValidationError: 1 validation error for ResponseTextDeltaEvent
logprobs
  Field required

修复内容：

• ✅ 在 src/agents/models/chatcmpl_stream_handler.py 中添加 logprobs=[] 参数
• ✅ 在 tests/voice/test_workflow.py 中添加 logprobs=[] 参数
• ✅ 确保与 OpenAI 库版本 >=1.87.0 的兼容性
• ✅ 修复流式响应中的 Pydantic 验证错误

影响范围：

• 解决了流式 API 调用中的关键验证问题
• 确保了与最新 OpenAI 库版本的兼容性
• 不影响现有功能和 API 接口

技术细节：
这是一个补丁版本发布，主要解决了与 OpenAI 库新版本兼容性的问题。logprobs 字段现在是 ResponseTextDeltaEvent 构造函数的必需参数，我们通过提供空列表 [] 作为默认值来满足这一要求。

---

📦 安装

pip install openai-agents==0.2.2

🔄 从 v0.2.1 升级

pip install --upgrade openai-agents

完整变更日志：

• fix: add missing logprobs field to ResponseTextDeltaEvent
• style: format code with ruff

v0.2.1

🔧 Bug Fixes

JsonObjectOutputSchema 兼容性修复

修复了 JsonObjectOutputSchema 在 DeepSeek API 中出现的 response_format type is unavailable 错误。

问题描述：

• JsonObjectOutputSchema 设计用于兼容只支持 {'type': 'json_object'} 格式的 LLM 提供商（如 DeepSeek）
• 但之前的实现中，所有非纯文本输出都使用 json_schema 格式

解决方案：

• 在 convert_response_format 方法中添加对 JsonObjectOutputSchema 的特殊处理
• JsonObjectOutputSchema 现在正确使用 {'type': 'json_object'} 格式
• 保持其他输出模式（AgentOutputSchema）的向后兼容性

测试覆盖：

• ✅ 添加单元测试验证 JsonObjectOutputSchema 返回正确格式
• ✅ 添加回归测试确保其他功能不受影响
• ✅ 所有现有测试通过

---

完整更新日志: CHANGELOG.md

🚀 v0.2.0: Streaming Tool 功能发布

🚀 主要新增功能

🔧 Streaming Tool 核心功能

• 新增 @streaming_tool 装饰器：支持创建流式工具，可以实时输出进度和中间结果
• 新增 Agent.as_tool(streaming=True) 功能：将 Agent 转换为流式工具，支持嵌套 Agent 调用
• 完整的上下文隔离机制：确保 streaming_tool 内部 agent 事件不会影响主 agent 的对话历史

📡 流式事件系统

• StreamingToolStartEvent / StreamingToolEndEvent - 流式工具生命周期事件
• StreamingToolContextEvent - 上下文隔离事件容器
• NotifyStreamEvent - 支持进度展示和打字机效果的通知事件

🎯 用户体验改进

• 实时进度反馈：通过 NotifyStreamEvent 展示工具执行进度
• 打字机效果：支持通过 is_delta=True 实现流式文本输出
• 事件标签系统：支持为事件添加标签，便于前端分类处理

🔧 技术特性

• ✅ 完全向后兼容：无破坏性变更，现有代码无需修改
• ✅ 异步优先设计：基于 asyncio 的高性能事件处理
• ✅ 完整的类型安全：TypeScript 风格的类型注解
• ✅ 并发支持：支持多个 streaming_tool 并发执行
• ✅ 智能事件包装：自动识别和包装需要隔离的事件类型

📚 文档和示例

• 📖 完整的开发文档：docs/streaming_tool_context_isolation.md
• 🎯 实际应用示例：
  • examples/basic/streaming_tool_basic.py - 基础流式工具
  • examples/tools/streaming_tools.py - 高级流式工具
  • examples/streaming_tool_context_isolation_demo.py - 上下文隔离演示
• 🧪 完整的测试覆盖：tests/test_streaming_tool.py - 20+ 个测试用例

🔄 迁移指南

现有代码无需任何修改即可升级到 v0.2.0。新功能为可选功能，不影响现有工作流。

📦 安装

pip install openai-agents==0.2.0