openai-agents-sdk

OpenAI Agents SDK for Python

此技能适用于 openai-agents / agents，不适用于 TypeScript SDK。 实现 API 前，先确认已安装的软件包及其提供方集成。当前的 SDK 文档 和匹配的源码标签优先于静态示例。

从当前的 OpenAI 模型目录 和模型选择指南中选择模型。 检查所选模型支持的工具、推理设置和提供方可用性； SDK 回退选项或演示 ID 并非长期建议。

wheel 不包含文档。离线时，请阅读已安装的源码：使用 importlib.metadata.version("openai-agents") 获取版本，在 agents/__init__.py 查看公共导出，并检查软件包目录中的文档字符串和类型 （python -c "import agents; print(agents.__file__)"）。文档 源码位于仓库标签 v<version> 下的 docs/ 目录中。

核心形式

Runner.run_sync 在事件循环运行时会引发异常（异步处理程序和 Notebook 中均如此）；应使用 await Runner.run(...)。Runner.run_streamed(...) 本身不使用 await；应完整消费其 stream_events() 异步迭代器。

已使用 openai-agents 0.22.3 验证；对于其他版本，请在已安装的源码中确认名称：

import asyncio
from pydantic import BaseModel
from agents import Agent, ModelSettings, Runner, SQLiteSession, function_tool
from openai.types.shared import Reasoning

class OrderAnswer(BaseModel):
    order_id: str
    status: str
    reply: str

@function_tool
def get_order_status(order_id: str) -> str:
    """Return an order's shipping status.

    Args:
        order_id: Order ID given by the customer.
    """
    return f"{order_id}: shipped"  # authorize and read the app's data here

support = Agent(
    name="Support",
    instructions="Answer order questions. Use get_order_status for order data.",
    model="gpt-6.1-sol",  # example API ID; use the project's configured model
    model_settings=ModelSettings(reasoning=Reasoning(effort="medium")),
    tools=[get_order_status],
    output_type=OrderAnswer,
)
# A manager keeps control with tools=[order_tool]; handoffs=[support] transfers it.
order_tool = support.as_tool("order_support", "Answer an order question.")

async def main() -> None:
    session = SQLiteSession("user-123", "conversations.db")  # ID owned by the signed-in user
    result = await Runner.run(support, "Where is order A-17?", session=session)
    answer: OrderAnswer = result.final_output  # validated OrderAnswer instance
    print(answer.status, answer.reply)

asyncio.run(main())

此示例使用 Responses（SDK 的默认 API）。GPT-6.1 Sol 在进行工具调用时需要使用 Responses，且不支持 none 或 minimal 推理强度。

集成决策

• 除非任务要求更改，否则保留项目的提供方、模型和存储方式。在提供方配置或实时文档中验证模型 ID 和能力。 SDK 的模型和设置默认值可能会变化；对于产品关键选项，应显式配置。
• 适用时优先使用原生提供方/客户端支持。LiteLLM/Any-LLM 是可选集成，具有各自的兼容性和设置行为。
• 专家接手时使用交接；如果管理 Agent 应在委派工作后继续，则使用 agent.as_tool()。固定流水线无需仅为实现常规控制流而添加额外 Agent。
• 在工具中授权副作用。Agent 指令、输出架构和防护措施不能替代授权或幂等性。
• 在向不可信客户端开放多轮 Agent 前，先确定历史记录归属、审批/恢复方式和追踪数据策略。

阅读相关功能文档

• Agents/提供方：模型默认值、Azure 和适配器。
• 工具：本地/托管执行、委派和审批/恢复。
• 结构化输出：架构和能力限制。
• 流式处理：事件类型、故障和防护措施。
• 交接：控制权转移和过滤。
• 防护措施：执行时机和覆盖范围。
• 会话：历史记录归属和持久化。
• 编排/追踪：运行限制和可观测性。
• 沙盒：工作区执行和恢复状态。

如果可用，请使用 OpenAI Developer Docs MCP（https://developers.openai.com/mcp）了解最新的 OpenAI API/提供方行为，或查阅其纯文本索引 https://developers.openai.com/api/docs/llms.txt；SDK 签名请以 Python SDK 自身的参考文档为准。从兼容的标签中阅读所选的 官方示例，不要使用复制来的演示目录。

验证

验证工具变更、多轮历史记录、批准／拒绝和故障恢复。 使用已安装的 agents.testing（已在 0.22.3 中验证）进行离线编排： ScriptedModel、ModelStep、assistant_message、function_call 和 model.assert_complete()，并使用 RunConfig(tracing_disabled=True)；将 agent.model = ScriptedModel([...]) 赋值后，即可离线运行核心流程。运行 项目的检查；将缺少提供商访问权限的情况与已验证的 SDK 行为分开报告。