教程2：结构化输出代理

教程 2：结构化输出代理

学习如何使用 Pydantic 模型创建返回类型安全、结构化数据的代理。本教程将教您如何确保您的代理返回一致且经过验证的 JSON 响应，以便您的应用程序能够可靠地处理这些响应。

您将学到的内容

• 结构化输出：使用 Pydantic 模型定义响应模式
• 类型安全：确保数据类型的统一性和验证
• JSON 模式生成：从 Python 类自动生成模式
• 输出验证：内置验证和错误处理

核心概念：为什么需要结构化输出？

传统的 AI 响应是未结构化的文本，这使得它们难以通过程序进行处理。结构化输出解决了这一问题，具体体现在：

• 一致性：始终返回相同的数据结构
• 验证：自动进行类型检查和数据验证
• 集成：易于与数据库、API 和应用程序集成
• 可靠性：减少解析错误，提高应用稳定性

┌─────────────────────────────────────────────────────────────┐
│                    UNSTRUCTURED vs STRUCTURED               │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  UNSTRUCTURED OUTPUT:                                       │
│  "The customer John Doe submitted a high priority           │
│   billing issue about charges on January 15th..."           │
│                                                             │
│  STRUCTURED OUTPUT:                                         │
│  {                                                          │
│    "customer_name": "John Doe",                             │
│    "issue_type": "billing",                                 │
│    "priority": "high",                                      │
│    "date_submitted": "2024-01-15",                          │
│    "description": "Incorrect charges on account"            │
│  }                                                          │
└─────────────────────────────────────────────────────────────┘
​

教程概述

本教程包含三个聚焦的结构化输出示例：

1. 支持工单代理 (2_1_support_ticket_agent/)

• Basic structured output with enums
• Required and optional fields
• Business validation patterns

2. Product Review Agent (2_2_product_review_agent/)

• Complex sentiment analysis schema
• List fields and nested validation
• Rating classification logic

3. Email Generator Agent (2_3_email_generator_agent/)

• 简单的两字段结构
• 对语气的枚举验证
• 内容格式化模式

项目结构

2_structured_output_agent/
├── README.md                    # This file - concept explanation
├── requirements.txt             # Dependencies
├── 2_1_support_ticket_agent/    # Basic structured output
│   ├── __init__.py
│   └── agent.py                # Support ticket schema (35 lines)
├── 2_2_product_review_agent/    # Complex structured output
│   ├── __init__.py
│   └── agent.py                # Product review analysis (45 lines)
├── 2_3_email_generator_agent/   # Simple structured output
│   ├── __init__.py
│   └── agent.py                # Email content generation (30 lines)
├── app.py                      # Streamlit web interface (optional)
└── env.example                 # Environment variables template
​

学习目标

完成本教程后，您将掌握：

• ✅ 如何为代理输出定义 Pydantic 模型
• ✅ 在代理中使用 output_type 参数
• ✅ 包含嵌套模型的复杂数据结构
• ✅ 对受控词汇表的枚举验证
• ✅ 可选字段和默认值
• ✅ 自定义验证方法

开始使用

1. 安装 OpenAI Agents 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 support_ticket_agent.py
   ​

5. 测试产品评论代理：

   python product_review_agent.py
   ​

6. 运行交互式 Web 界面：

   streamlit run app.py
   ​

示例用例

支持工单代理

尝试以下客户投诉：

• “我的账单显示上个月订阅有重复收费”
• “我无法登录账户，需要立即帮助”
• “当我尝试上传文件时，应用不断崩溃”

产品评论代理

尝试以下产品评论：

• “这款笔记本电脑太棒了！电池续航超长，速度超级快。绝对推荐。五星好评！”
• “手机摄像头质量差，电池耗电快。不值得这个价格。”
• “产品还行，但发货等了很久。不过客服服务很贴心。”

关键 Pydantic 模式

1. 带枚举的基本模型

class Priority(str, Enum):
    LOW = "low"
    MEDIUM = "medium"
    HIGH = "high"
    CRITICAL = "critical"

class SupportTicket(BaseModel):
    priority: Priority
    category: str
​

2. 带默认值的可选字段

class Review(BaseModel):
    rating: int = Field(ge=1, le=5)
    sentiment: str
    recommend: Optional[bool] = None
​

3. 复杂的嵌套结构

class ProductReview(BaseModel):
    product_info: ProductInfo
    review_data: ReviewData
    analysis: ReviewAnalysis
​

下一步

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

• 教程 3：工具使用代理 - 添加自定义工具和函数
• 教程 4：运行器执行方法 - 掌握不同的执行模式
• 教程 5：上下文管理 - 管理跨交互的状态

专业提示

• 先设计模式：在实现前规划好数据结构
• 使用描述性字段：清晰的字段描述能提高代理准确度
• 验证约束条件：使用 Pydantic 验证器实现业务规则
• 处理可选内容：为缺失或不确定的数据做好准备
• 测试边界情况：尝试不完整或模糊的输入

故障排除

• 验证错误：检查您的 Pydantic 模型是否与预期输出匹配
• 字段缺失：确保所有必填字段都包含在模式中
• 类型不匹配：验证字段类型与返回的数据一致
• 枚举错误：确保枚举值完全匹配（区分大小写）

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