OpenAI Agents SDK是一个轻量级但功能强大的框架，用于构建多智能体工作流。它通过智能体、交接、护栏和跟踪等核心机制实现复杂工作流管理。智能体是配置了指令、工具和护栏功能的大语言模型，支持交接控制权给其他智能体，并通过护栏确保安全性。框架还提供跟踪功能便于调试和优化。开发者可配置不同智能体和工具构建复杂工作流，代码流程清晰，易于实现多智能体系统。

---

项目概述

OpenAI Agents SDK 是一个轻量级但功能强大的框架，用于构建多智能体工作流。它主要利用大语言模型（LLM），通过配置智能体、交接、护栏和跟踪等功能，实现复杂的工作流管理。以下是对其各个部分运行过程和代码流程的详细介绍。

项目链接：OpenAI Agent SDK项目地址

核心架构

项目整体架构图

根据提供的代码库信息，OpenAI Agents SDK 项目的整体架构可以分为以下几个主要模块：

Output

Tracing

Models

Agents

Application

调用

交接

检查

RunResult

Trace

Model

Agent

Tool

Handoff

Guardrail

Runner

用户输入

架构图说明：

1. 应用层（Application）：用户通过输入触发 Runner 开始执行代理流程。
2. 代理层（Agents）：
   • Agent 是核心组件，包含指令、工具、交接和护栏等配置。
   • Tool 是代理可以调用的工具，用于执行特定任务。
   • Handoff 允许代理将控制权转移给其他代理。
   • Guardrail 用于输入和输出的验证，确保代理的安全性。
3. 模型层（Models）：Agent 调用 Model 来生成响应。
4. 跟踪层（Tracing）：Runner 在执行过程中会生成跟踪信息，方便调试和优化。
5. 输出层（Output）：最终生成 RunResult 作为执行结果。

项目整体流程图

是

否

是

否

是

否

是

否

是

否

用户输入

Runner初始化

选择起始Agent

运行输入护栏检查

是否通过护栏检查?

调用Model生成响应

抛出InputGuardrailTripwireTriggered异常

是否有最终输出?

运行输出护栏检查

是否有交接?

切换到新的Agent

是否有工具调用?

执行工具调用

是否通过输出护栏检查?

返回RunResult

抛出OutputGuardrailTripwireTriggered异常

流程图说明：

1. 用户输入触发 Runner 初始化，并选择起始 Agent。
2. 对输入进行护栏检查，如果未通过则抛出异常。
3. 调用 Model 生成响应。
4. 判断是否有最终输出，如果有则进行输出护栏检查。
5. 如果没有最终输出，判断是否有交接或工具调用，根据情况进行相应处理。
6. 输出护栏检查通过后，返回 RunResult；否则抛出异常。

核心概念

1. 智能体（Agents）

智能体是配置了指令、工具、护栏和交接功能的大语言模型。在代码中，Agent 类是核心，它包含了智能体的基本信息。

from agents import Agent

agent = Agent(name="Assistant", instructions="You are a helpful assistant")

• 运行过程：当调用 Runner.run() 或 Runner.run_sync() 时，会启动一个循环，不断与 LLM 交互，直到得到最终输出。
• 代码流程：
  • Runner.run() 或 Runner.run_sync() 调用 RunImpl.execute_tools_and_side_effects() 方法。
  • 在 execute_tools_and_side_effects() 中，首先处理模型响应，包括解析工具调用、交接等信息。
  • 然后根据响应结果，决定是继续运行、进行交接还是返回最终输出。

2. 交接（Handoffs）

交接允许智能体将特定任务的控制权转移给其他智能体。

spanish_agent = Agent(name="Spanish agent", instructions="You only speak Spanish.")
english_agent = Agent(name="English agent", instructions="You only speak English")
triage_agent = Agent(
    name="Triage agent",
    instructions="Handoff to the appropriate agent based on the language of the request.",
    handoffs=[spanish_agent, english_agent])

• 运行过程：当 triage_agent 收到请求时，根据请求的语言将任务交接给 spanish_agent 或 english_agent。
• 代码流程：
  • 在 RunImpl.execute_tools_and_side_effects() 中，处理模型响应时，如果发现有交接信息，调用 execute_handoffs() 方法。
  • execute_handoffs() 方法会将控制权转移到新的智能体，并重新开始循环。

3. 护栏（Guardrails）

护栏是可配置的安全检查，用于输入和输出验证。

from agents import InputGuardrail, GuardrailFunctionOutput
from pydantic import BaseModel

classHomeworkOutput(BaseModel):
    is_homework:bool
    reasoning:str

guardrail_agent = Agent(
    name="Guardrail check",
    instructions="Check if the user is asking about homework.",
    output_type=HomeworkOutput
)

• 运行过程：在智能体运行过程中，护栏会对输入和输出进行验证，如果不符合条件，可能会中断流程。
• 代码流程：
  • 在 RunImpl.execute_tools_and_side_effects() 中，处理最终输出时，会根据输出类型进行验证。
  • 如果输出类型是结构化的，会调用 output_schema.validate_json() 方法进行验证。

4. 跟踪（Tracing）

跟踪是内置的智能体运行跟踪功能，可用于查看、调试和优化工作流。

from agents.tracing.setup import TraceProvider

trace_provider = TraceProvider()

• 运行过程：在智能体运行过程中，会创建跟踪信息并发送到指定的后端。
• 代码流程：
  • TraceProvider 类负责管理跟踪处理器。
  • 在创建跟踪或跨度时，会调用相应的处理器进行处理。
  • 处理器会在跟踪开始、结束，跨度开始、结束等事件发生时进行相应的操作。

项目使用步骤

1. 环境搭建

python -m venv envsource env/bin/activate

• 运行过程：创建一个虚拟环境并激活它，确保项目的依赖与系统环境隔离。
• 代码流程：这是 Python 标准的虚拟环境创建和激活步骤，由 Python 解释器和操作系统完成。

2. 安装 SDK

pip install openai-agents

• 运行过程：使用 pip 工具从 Python Package Index（PyPI）下载并安装 openai-agents 包。
• 代码流程：pip 会解析依赖关系，下载所需的包，并将其安装到虚拟环境中。

3. 示例代码

Hello world 示例

from agents import Agent, Runner

agent = Agent(name="Assistant", instructions="You are a helpful assistant")

result = Runner.run_sync(agent,"Write a haiku about recursion in programming.")print(result.final_output)

• 运行过程：创建一个简单的智能体，调用 Runner.run_sync() 方法与 LLM 交互，获取最终输出并打印。
• 代码流程：
  • 创建 Agent 对象，设置名称和指令。
  • 调用 Runner.run_sync() 方法，该方法会调用 RunImpl.execute_tools_and_side_effects() 方法进行处理。
  • 在 execute_tools_and_side_effects() 中，与 LLM 交互，处理响应，直到得到最终输出。
  • 返回最终输出并打印。

交接示例

from agents import Agent, Runner
import asyncio

spanish_agent = Agent(
    name="Spanish agent",
    instructions="You only speak Spanish.",)

english_agent = Agent(
    name="English agent",
    instructions="You only speak English",)

triage_agent = Agent(
    name="Triage agent",
    instructions="Handoff to the appropriate agent based on the language of the request.",
    handoffs=[spanish_agent, english_agent],)asyncdefmain():
    result =await Runner.run(triage_agent,input="Hola, ¿cómo estás?")print(result.final_output)if __name__ =="__main__":
    asyncio.run(main())

• 运行过程：创建三个智能体，其中 triage_agent 负责根据请求语言进行交接，调用 Runner.run() 方法处理请求，最终输出结果。
• 代码流程：
  • 创建三个 Agent 对象，设置名称、指令和交接信息。
  • 调用 Runner.run() 方法，该方法会调用 RunImpl.execute_tools_and_side_effects() 方法进行处理。
  • 在 execute_tools_and_side_effects() 中，处理模型响应时发现交接信息，调用 execute_handoffs() 方法将控制权转移到 spanish_agent。
  • spanish_agent 处理请求并返回最终输出。
  • 返回最终输出并打印。

函数示例

import asyncio

from agents import Agent, Runner, function_tool


@function_tooldefget_weather(city:str)->str:returnf"The weather in {city} is sunny."


agent = Agent(
    name="Hello world",
    instructions="You are a helpful agent.",
    tools=[get_weather],)asyncdefmain():
    result =await Runner.run(agent,input="What's the weather in Tokyo?")print(result.final_output)if __name__ =="__main__":
    asyncio.run(main())

• 运行过程：创建一个带有工具的智能体，调用 Runner.run() 方法处理请求，智能体调用工具获取天气信息并返回最终输出。
• 代码流程：
  • 使用 @function_tool 装饰器将 get_weather 函数转换为工具。
  • 创建 Agent 对象，设置名称、指令和工具。
  • 调用 Runner.run() 方法，该方法会调用 RunImpl.execute_tools_and_side_effects() 方法进行处理。
  • 在 execute_tools_and_side_effects() 中，处理模型响应时发现工具调用，调用 execute_function_tool_calls() 方法执行工具。
  • 工具执行后返回结果，继续与 LLM 交互，直到得到最终输出。
  • 返回最终输出并打印。

智能体循环

当调用 Runner.run() 时，会运行一个循环，直到得到最终输出。

# 伪代码表示循环过程whileTrue:# 1. 调用 LLM
    response = call_llm(agent, message_history)# 2. 处理响应
    processed_response = process_response(response)# 3. 检查是否有最终输出if processed_response.has_final_output():return processed_response.final_output
    # 4. 检查是否有交接if processed_response.has_handoff():
        agent = processed_response.handoff_agent
        continue# 5. 处理工具调用
    process_tool_calls(processed_response.tool_calls)# 6. 更新消息历史
    update_message_history(processed_response)

• 运行过程：
  1. 使用智能体的模型和设置以及消息历史调用 LLM。
  2. 处理 LLM 返回的响应，包括解析工具调用、交接等信息。
  3. 如果响应有最终输出，返回并结束循环。
  4. 如果响应有交接，切换到新的智能体并回到步骤 1。
  5. 处理工具调用（如果有）并追加工具响应消息，然后回到步骤 1。
• 代码流程：
  • 在 Runner.run() 方法中，调用 RunImpl.execute_tools_and_side_effects() 方法，该方法内部实现了循环逻辑。
  • 在 execute_tools_and_side_effects() 中，使用 ModelResponse 对象表示 LLM 的响应，使用 ProcessedResponse 对象表示处理后的响应。
  • 根据 ProcessedResponse 对象的属性，判断是否有最终输出、交接或工具调用，并进行相应的处理。

最终输出

最终输出是智能体在循环中产生的最后结果。

# 判断最终输出的伪代码if agent.output_type:# 有输出类型，检查是否为结构化输出if response.has_structured_output(agent.output_type):
        final_output = response.structured_output
else:# 无输出类型，检查是否无工具调用或交接ifnot response.has_tool_calls()andnot response.has_handoff():
        final_output = response.message

• 运行过程：
  1. 如果智能体设置了 output_type，最终输出是当 LLM 返回符合该类型的结构化输出时。
  2. 如果没有 output_type（即纯文本响应），则第一个没有任何工具调用或交接的 LLM 响应被视为最终输出。
• 代码流程：
  • 在 RunImpl.execute_tools_and_side_effects() 中，处理最终输出时，根据 output_schema 判断是否有输出类型。
  • 如果有输出类型，调用 output_schema.validate_json() 方法验证是否为结构化输出。
  • 如果没有输出类型，检查是否有工具调用或交接，如果没有则将消息作为最终输出。

开发流程

1. 安装 uv

uv --version

• 运行过程：检查 uv 工具是否安装。
• 代码流程：由操作系统执行命令，检查 uv 工具的版本信息。

2. 安装依赖

makesync

• 运行过程：使用 make 工具执行 sync 目标，安装项目的依赖。
• 代码流程：make 工具会读取 Makefile 文件，执行相应的命令，安装依赖。

3. 代码检查和测试

make tests  # run testsmake mypy   # run typecheckermake lint   # run linter

• 运行过程：
  • make tests：运行项目的测试代码，确保功能的正确性。
  • make mypy：运行类型检查器，检查代码中的类型错误。
  • make lint：运行代码检查工具，检查代码的风格和规范。
• 代码流程：
  • make tests 会执行 pytest 命令，运行 tests 目录下的测试代码。
  • make mypy 会执行 mypy 命令，对项目代码进行类型检查。
  • make lint 会执行 ruff 命令，对项目代码进行风格和规范检查。

总结

OpenAI Agents SDK 通过智能体、交接、护栏和跟踪等机制，构建了一个灵活、可扩展的多智能体工作流框架。其代码流程清晰，通过 Runner 和 RunImpl 类实现了智能体的运行和管理，通过 TraceProvider 类实现了跟踪功能，通过 Agent 类实现了智能体的配置和管理。开发者可以根据自己的需求，配置不同的智能体和工具，构建复杂的工作流。

零基础如何高效学习大模型？

你是否懂 AI，是否具备利用大模型去开发应用能力，是否能够对大模型进行调优，将会是决定自己职业前景的重要参数。

为了帮助大家打破壁垒，快速了解大模型核心技术原理，学习相关大模型技术。从原理出发真正入局大模型。在这里我和鲁为民博士系统梳理大模型学习脉络，这份 LLM大模型资料 分享出来：包括LLM大模型书籍、640套大模型行业报告、LLM大模型学习视频、LLM大模型学习路线、开源大模型学习教程等, 😝有需要的小伙伴，可以 扫描下方二维码免费领取🆓**⬇️⬇️⬇️

【大模型全套视频教程】

教程从当下的市场现状和趋势出发，分析各个岗位人才需求，带你充分了解自身情况，get 到适合自己的 AI 大模型入门学习路线。

从基础的 prompt 工程入手，逐步深入到 Agents，其中更是详细介绍了 LLM 最重要的编程框架 LangChain。最后把微调与预训练进行了对比介绍与分析。

同时课程详细介绍了AI大模型技能图谱知识树，规划属于你自己的大模型学习路线，并且专门提前收集了大家对大模型常见的疑问，集中解答所有疑惑！

深耕 AI 领域技术专家带你快速入门大模型

跟着行业技术专家免费学习的机会非常难得，相信跟着学习下来能够对大模型有更加深刻的认知和理解，也能真正利用起大模型，从而“弯道超车”，实现职业跃迁！

【精选AI大模型权威PDF书籍/教程】

精心筛选的经典与前沿并重的电子书和教程合集，包含《深度学习》等一百多本书籍和讲义精要等材料。绝对是深入理解理论、夯实基础的不二之选。

【AI 大模型面试题 】

除了 AI 入门课程，我还给大家准备了非常全面的**「AI 大模型面试题」，**包括字节、腾讯等一线大厂的 AI 岗面经分享、LLMs、Transformer、RAG 面试真题等，帮你在面试大模型工作中更快一步。

【大厂 AI 岗位面经分享（92份）】

【AI 大模型面试真题（102 道）】

【LLMs 面试真题（97 道）】

【640套 AI 大模型行业研究报告】

【AI大模型完整版学习路线图（2025版）】

明确学习方向，2025年 AI 要学什么，这一张图就够了！

👇👇点击下方卡片链接免费领取全部内容👇👇

抓住AI浪潮，重塑职业未来！

科技行业正处于深刻变革之中。英特尔等巨头近期进行结构性调整，缩减部分传统岗位，同时AI相关技术岗位（尤其是大模型方向）需求激增，已成为不争的事实。具备相关技能的人才在就业市场上正变得炙手可热。

行业趋势洞察：

• 转型加速： 传统IT岗位面临转型压力，拥抱AI技术成为关键。
• 人才争夺战： 拥有3-5年经验、扎实AI技术功底和真实项目经验的工程师，在头部大厂及明星AI企业中的薪资竞争力显著提升（部分核心岗位可达较高水平）。
• 门槛提高： “具备AI项目实操经验”正迅速成为简历筛选的重要标准，预计未来1-2年将成为普遍门槛。

与其观望，不如行动！

面对变革，主动学习、提升技能才是应对之道。掌握AI大模型核心原理、主流应用技术与项目实战经验，是抓住时代机遇、实现职业跃迁的关键一步。

01 为什么分享这份学习资料？

当前，我国在AI大模型领域的高质量人才供给仍显不足，行业亟需更多有志于此的专业力量加入。

因此，我们决定将这份精心整理的AI大模型学习资料，无偿分享给每一位真心渴望进入这个领域、愿意投入学习的伙伴！

我们希望能为你的学习之路提供一份助力。如果在学习过程中遇到技术问题，也欢迎交流探讨，我们乐于分享所知。

*02 这份资料的价值在哪里？*

专业背书，系统构建：

• 本资料由我与鲁为民博士共同整理。鲁博士拥有清华大学学士和美国加州理工学院博士学位，在人工智能领域造诣深厚：

• • 在IEEE Transactions等顶级学术期刊及国际会议发表论文超过50篇。
  • 拥有多项中美发明专利。
  • 荣获吴文俊人工智能科学技术奖（中国人工智能领域重要奖项）。

• 目前，我有幸与鲁博士共同进行人工智能相关研究。

内容实用，循序渐进：

• 资料体系化覆盖了从基础概念入门到核心技术进阶的知识点。

• 包含丰富的视频教程与实战项目案例，强调动手实践能力。

• 无论你是初探AI领域的新手，还是已有一定技术基础希望深入大模型的学习者，这份资料都能为你提供系统性的学习路径和宝贵的实践参考，助力你提升技术能力，向大模型相关岗位转型发展。

  

抓住机遇，开启你的AI学习之旅！