AI Agent / 系统课时
使用 Pydantic 定义协议模型
使用 Pydantic 定义协议模型
本节解决智能体系统中模型输出不稳定、模块之间数据约定不清的问题。通过 Pydantic 2 定义统一协议模型,让消息、工具调用、任务状态和结构化结果都有明确的数据边界,保证 Agent Runtime 能可靠处理模型行为。
学习目标
- 理解为什么智能体系统需要协议模型约束数据流
- 掌握使用 Pydantic 2 定义消息、工具和任务状态 Schema
- 学会验证结构化输出并处理模型结果边界
为什么需要协议模型
智能体系统通常包含模型调用层、工具执行层、状态管理层和客户端交互层。如果每个模块都直接传递 Python 字典,随着功能增加会出现字段缺失、类型错误和状态含义不一致的问题。
协议模型的作用是把模块之间的通信规则固定下来。例如消息必须包含角色和内容,工具调用必须包含工具名称和参数,任务状态必须使用约定好的枚举值。
Pydantic 可以根据类型声明自动完成数据校验、转换和序列化,使 Runtime 不需要到处编写重复判断逻辑。
使用 Pydantic 2 定义核心 Schema
在 Pydantic 2 中,推荐使用 BaseModel 作为协议模型基础,通过类型注解描述字段,通过配置控制序列化行为。
from enum import Enum
from pydantic import BaseModel, Field
class TaskStatus(str, Enum):
# 状态值用于跨模块传递,避免使用随意字符串
RUNNING = "running"
SUCCESS = "success"
FAILED = "failed"
class Message(BaseModel):
role: str
content: str
class ToolCall(BaseModel):
name: str
arguments: dict[str, object] = Field(default_factory=dict)
class AgentTask(BaseModel):
task_id: str
status: TaskStatus
messages: list[Message]
tool_calls: list[ToolCall] = Field(default_factory=list)
request = AgentTask(
task_id="<ID>",
status="running",
messages=[Message(role="user", content="查询天气")]
)
print(request.model_dump())预期输出
{'task_id': '<ID>', 'status': 'running', 'messages': [{'role': 'user', 'content': '查询天气'}], 'tool_calls': []}这里使用枚举约束任务状态,避免模型或工具返回 doing、complete 等无法识别的值。Field(default_factory=...) 用于创建独立默认对象,避免多个任务共享同一个列表。
设计结构化模型输出
智能体调用大语言模型时,经常需要模型返回 JSON 结构,例如工具选择结果或任务计划。协议模型可以作为模型输出后的校验层。
典型流程如下:模型生成结果 → Pydantic 校验 → Runtime 执行业务逻辑。校验失败时,系统可以重新请求模型修正,而不是直接执行错误数据。
from pydantic import BaseModel
class Plan(BaseModel):
goal: str
steps: list[str]
raw_result = {
"goal": "整理文件",
"steps": ["扫描目录", "分类文件"]
}
plan = Plan.model_validate(raw_result)
print(plan.steps[0])预期结果
扫描目录协议模型的边界设计
协议模型不应该直接等同数据库模型或业务对象。数据库关注存储结构,业务对象关注领域逻辑,而协议模型关注模块通信。
在智能体工程中,建议分别设计:
- 输入模型:描述客户端或上游模块发送的数据
- 输出模型:描述 Agent 返回的数据结构
- 事件模型:描述流式过程中的状态变化
- 工具模型:描述工具调用参数和结果
这样可以降低模块耦合,让模型升级或工具替换时影响范围更小。
常见错误
一个常见问题是把大模型输出直接当可信数据使用。模型生成的 JSON 即使格式正确,也可能语义错误,因此协议校验只能保证结构正确,业务规则仍需要额外验证。
另一个问题是协议字段设计过于宽松,例如大量使用 dict[str, object]。灵活字段适合扩展,但核心流程字段应该保持明确类型。
本课总结
- Pydantic 协议模型为智能体模块提供稳定的数据契约。
- Schema 应覆盖消息、工具调用、任务状态和结构化输出等核心交互。
- 数据校验解决格式问题,业务验证负责解决语义问题。
下一课预告
下一课将继续设计智能体工程架构中的异步与流式通信,让模型输出、工具事件和客户端状态可以实时传递。