教程3：结构化输出代理

教程 3：结构化输出代理

欢迎来到结构化输出！本教程将教你如何创建能够返回类型安全、结构化数据的代理，而不是简单的文本。这对于构建需要可预测数据格式的可靠应用至关重要。

你将学到的内容

• Pydantic 模式：定义带有验证的数据结构
• 类型安全：确保你的代理返回预期的数据格式
• 业务逻辑：可靠地处理结构化数据
• 错误处理：优雅地处理验证错误
• 实际应用：客户支持与邮件生成

核心概念：结构化输出

结构化输出意味着你的代理返回的是经过验证的数据对象，而非原始文本：

• ✅ 类型安全：确切知道你会收到什么数据格式
• ✅ 验证：自动检查必填字段和数据类型
• ✅ 可靠性：不再需要手动解析文本响应
• ✅ 集成：易于在应用和数据库中使用

为什么选择结构化输出？

• 可预测：总是得到相同的数据结构
• 已验证：Pydantic 确保数据正确性
• 带类型：IDE 完全支持并进行类型检查
• 可扩展：轻松修改和扩展模式

教程结构

本教程包含两个完整示例：

示例 1：客户支持工单代理

位置：./3_1_customer_support_ticket_agent/

• 从客户投诉中提取结构化工单信息
• 优先级分类与紧急程度评估
• 联系信息提取
• 部门路由逻辑

示例 2：邮件生成代理

位置：./3_2_email_agent/

• 生成带有元数据的结构化邮件内容
• 主题行优化
• 收件人分类
• 邮件模板格式化

项目结构

3_structured_output_agent/
├── README.md                           # This tutorial overview
├── 3_1_customer_support_ticket_agent/  # Customer support example
└── 3_2_email_agent/                   # Email generation example
​

每个示例目录都遵循标准结构：

• Python 文件：包含代理实现与 Streamlit 应用
• README.md：设置与使用说明文档
• requirements.txt：依赖项列表

学习目标

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

• ✅ 如何为结构化输出定义 Pydantic 模式
• ✅ 如何配置代理以返回结构化数据
• ✅ 如何优雅地处理验证错误
• ✅ 何时使用结构化输出而非纯文本
• ✅ 模式设计的最佳实践

关键模式

基本结构化输出模式

from pydantic import BaseModel
from google.adk.agents import Agent

class TicketInfo(BaseModel):
    title: str
    priority: str
    category: str
    urgency_level: int

agent = Agent(
    name="support_agent",
    model="gemini-3-flash-preview",
    instruction="Extract ticket information...",
    response_format=TicketInfo,  # This ensures structured output!
)
​

高级模式与验证

from pydantic import BaseModel, Field, validator
from typing import List, Optional

class EmailData(BaseModel):
    subject: str = Field(..., min_length=5, max_length=100)
    recipients: List[str] = Field(..., min_items=1)
    priority: str = Field(..., regex="^(low|medium|high)$")
    
    @validator('recipients')
    def validate_emails(cls, v):
        # Custom email validation logic
        return v
​

实际应用场景

结构化输出代理非常适合以下场景：

• 客户支持：从投诉中提取工单信息
• 数据处理：将非结构化文本转换为数据库记录
• 内容生成：创建带有元数据的结构化内容
• 表单处理：从文档中提取信息
• API 集成：为其他系统提供一致的数据格式

专业提示

• 清晰模式：使用描述性的字段名并添加文档字符串
• 验证：根据用例添加合适的验证器
• 可选字段：对可能缺失的字段使用 Optional
• 示例：在模式文档中提供示例数据
• 错误处理：始终优雅地处理验证错误

重要提示

• Pydantic 必需：你需要 Pydantic 来定义模式
• 模型支持：并非所有模型都同样支持结构化输出
• 验证开销：复杂模式可能会降低响应速度
• 模式演进：规划生产系统中的模式变更

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