教程4：运行智能体

教程 4：运行智能体

掌握完整的 OpenAI 智能体 SDK 执行系统！本教程涵盖运行智能体的所有方面，包括执行方法、流式处理、智能体循环、异常处理以及基于官方运行智能体文档的高级配置。

您将学到的内容

• 三种执行方法：Runner.run()、Runner.run_sync()、Runner.run_streamed()
• 智能体循环：理解大语言模型调用、工具执行与交接流程
• 流式事件：实时响应处理与详细事件处理
• 异常处理：正确管理所有 SDK 异常
• 高级运行配置：防护措施、追踪与工作流控制

核心概念：智能体循环

当您调用任何 Runner 方法时，SDK 会执行一个复杂的循环，负责处理完整的智能体工作流：

┌─────────────────────────────────────────────────────────────┐
│                    THE AGENT LOOP                           │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  START: Runner.run(agent, input)                            │
│       │                                                     │
│       ▼                                                     │
│  ┌─────────────┐    1. CALL LLM                             │
│  │     LLM     │    ◦ Current agent + input                 │
│  │   CALL      │    ◦ Generate response                     │
│  └─────────────┘                                            │
│       │                                                     │
│       ▼                                                     │
│  ┌─────────────┐    2. PROCESS OUTPUT                       │
│  │   OUTPUT    │    ◦ Final output? → END                   │
│  │  ANALYSIS   │    ◦ Tool calls? → Execute tools           │
│  └─────────────┘    ◦ Handoff? → Switch agent               │
│       │                                                     │
│       ▼                                                     │
│  ┌─────────────┐    3. CONTINUE LOOP                        │
│  │   REPEAT    │    ◦ Append results to input               │ 
│  │   LOOP      │    ◦ Check max_turns limit                 │
│  └─────────────┘    ◦ Loop until final output               │
└─────────────────────────────────────────────────────────────┘
​

教程概览

本教程演示了五个关键运行模式：

1. 执行方法（4_1_execution_methods/)

• Sync, async, and streaming execution comparison
• Performance and use case analysis
• Basic agent loop understanding

2. Conversation Management (4_2_conversation_management/)

• Manual conversation threading with to_input_list()
• Automatic conversation management with Sessions
• Thread ID and group management

3. Run Configuration (4_3_run_configuration/)

• Model overrides and settings
• Tracing configuration and metadata
• Workflow naming and organization

4. Streaming Events (4_4_streaming_events/)

• Detailed streaming event handling
• RunResultStreaming object usage
• Real-time response processing patterns

5. Exception Handling (4_5_exception_handling/)

• All SDK exceptions: MaxTurnsExceeded, ModelBehaviorError 等）
• 正确的错误处理模式
• 恢复与重试策略

项目结构

4_running_agents/
├── README.md                           # This file - comprehensive guide
├── requirements.txt                    # Dependencies
├── 4_1_execution_methods/
│   ├── __init__.py
│   └── agent.py                       # Three execution methods (45 lines)
├── 4_2_conversation_management/
│   ├── __init__.py  
│   └── agent.py                       # Manual vs automatic threading (40 lines)
├── 4_3_run_configuration/
│   ├── __init__.py
│   └── agent.py                       # RunConfig examples (55 lines)
├── 4_4_streaming_events/
│   ├── __init__.py
│   └── agent.py                       # Detailed streaming handling (50 lines)
├── 4_5_exception_handling/
│   ├── __init__.py
│   └── agent.py                       # All exception types (60 lines)
├── agent_runner.py                    # Streamlit demo interface (recommended)
└── env.example                        # Environment variables
​

学习目标

完成本教程后，您将理解：

• ✅ 完整的智能体执行循环及各步骤的触发时机
• ✅ 如何在同步、异步与流式执行之间进行选择
• ✅ 针对实时应用的详细流式事件处理
• ✅ 面向生产环境的应用程序正确异常处理
• ✅ 复杂工作流的高级运行配置

开始使用

1. 安装 OpenAI 智能体 SDK：

   pip install openai-agents
   ​

2. 安装依赖项：

   pip install -r requirements.txt
   ​

3. 设置环境变量：

   cp env.example .env
   # Edit .env and add your OpenAI API key
   ​

4. 测试执行方法：

   python -m 4_1_execution_methods.agent
   ​

5. 尝试对话管理：

   python -m 4_2_conversation_management.agent
   ​

6. 探索运行配置：

   python -m 4_3_run_configuration.agent
   ​

7. 测试流式事件：

   python -m 4_4_streaming_events.agent
   ​

8. 实践异常处理：

   python -m 4_5_exception_handling.agent
   ​

关键运行概念

1. 智能体循环流程

• 大语言模型调用：智能体处理输入并生成响应
• 输出分析：检查最终输出、工具调用或交接情况
• 工具执行：运行所有工具调用并追加结果
• 交接处理：若发生交接则切换到新智能体
• 循环继续：重复执行直至获得最终输出或达到最大轮次

2. 三种执行方法

# 1. Async (non-blocking, returns RunResult)
result = await Runner.run(agent, "message")

# 2. Sync (blocking, wraps async under hood)  
result = Runner.run_sync(agent, "message")

# 3. Streaming (async, returns RunResultStreaming)
async for event in Runner.run_streamed(agent, "message"):
    # Process events in real-time
    pass
​

3. 流式事件类型

根据文档，流式处理会在大语言模型生成响应时提供实时事件，包括部分文本、工具调用和完成事件。

4. 异常层次结构

• AgentsException：基础异常类
• MaxTurnsExceeded：循环迭代次数过多
• ModelBehaviorError：大语言模型输出问题（JSON 格式错误等）
• UserError：SDK 使用错误
• InputGuardrailTripwireTriggered：输入验证失败
• OutputGuardrailTripwireTriggered：输出验证失败

示例用例

执行方法

• 同步：简单脚本、批量处理、快速响应
• 异步：Web 应用、并发用户、非阻塞操作
• 流式：长内容生成、实时聊天、进度更新

对话管理

• 手动：自定义对话逻辑、特殊线程需求
• 会话：标准聊天应用、自动历史管理

异常处理

• 生产应用：优雅的错误恢复、友好的用户提示
• 开发阶段：调试智能体行为、理解失败原因

运行智能体最佳实践

1. 选择合适方法：同步用于脚本，异步用于应用，流式用于长响应
2. 处理异常：始终在 Runner 调用中包裹正确的异常处理
3. 合理配置：使用 RunConfig 进行生产环境设置
4. 监控性能：跟踪执行时间和资源使用情况
5. 管理对话：根据需求选择手动或会话模式

下一步

完成本教程后，您将准备好：

• 教程 5：上下文管理 - 高级状态管理
• 教程 6：防护措施与验证 - 输入输出安全
• 教程 7：会话 - 内存与对话管理

故障排除

• 异步问题：始终使用 await 与 Runner.run() 和 Runner.run_streamed()
• 流式问题：处理部分事件与连接中断
• 异常处理：捕获特定异常类型以实现更好的错误恢复
• 性能：监控 max_turns 设置防止无限循环
• 配置：验证 RunConfig 设置符合您的使用场景要求

专业提示

• 从简单入手：需要并发时先从 run_sync, move to run 开始
• 合理使用流式：仅适用于超过 30 秒的响应
• 异常策略：在生产代码中为每种异常类型做好规划
• 配置一致性：使用 RunConfig 实现可重复的执行模式
• 监控循环：利用追踪功能了解复杂的智能体交互

免责声明：
本文档采用基于机器的 AI 翻译服务进行翻译。尽管我们力求准确，但请注意，自动翻译可能存在错误或不准确之处。应以原文语言版本的文档作为权威依据。如需获取关键信息，建议使用专业的人工翻译。对于因使用本翻译而产生的任何误解或误读，我们概不负责。