AI Agent / 系统课时

使用 Pydantic 定义协议模型

使用 Pydantic 定义协议模型

本节解决智能体系统中模型输出不稳定、模块之间数据约定不清的问题。通过 Pydantic 2 定义统一协议模型,让消息、工具调用、任务状态和结构化结果都有明确的数据边界,保证 Agent Runtime 能可靠处理模型行为。

学习目标

  • 理解为什么智能体系统需要协议模型约束数据流
  • 掌握使用 Pydantic 2 定义消息、工具和任务状态 Schema
  • 学会验证结构化输出并处理模型结果边界

为什么需要协议模型

智能体系统通常包含模型调用层、工具执行层、状态管理层和客户端交互层。如果每个模块都直接传递 Python 字典,随着功能增加会出现字段缺失、类型错误和状态含义不一致的问题。

协议模型的作用是把模块之间的通信规则固定下来。例如消息必须包含角色和内容,工具调用必须包含工具名称和参数,任务状态必须使用约定好的枚举值。

Pydantic 可以根据类型声明自动完成数据校验、转换和序列化,使 Runtime 不需要到处编写重复判断逻辑。

使用 Pydantic 2 定义核心 Schema

在 Pydantic 2 中,推荐使用 BaseModel 作为协议模型基础,通过类型注解描述字段,通过配置控制序列化行为。

python
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())

预期输出

text
{'task_id': '<ID>', 'status': 'running', 'messages': [{'role': 'user', 'content': '查询天气'}], 'tool_calls': []}

这里使用枚举约束任务状态,避免模型或工具返回 doing、complete 等无法识别的值。Field(default_factory=...) 用于创建独立默认对象,避免多个任务共享同一个列表。

设计结构化模型输出

智能体调用大语言模型时,经常需要模型返回 JSON 结构,例如工具选择结果或任务计划。协议模型可以作为模型输出后的校验层。

典型流程如下:模型生成结果 → Pydantic 校验 → Runtime 执行业务逻辑。校验失败时,系统可以重新请求模型修正,而不是直接执行错误数据。

python
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])

预期结果

text
扫描目录

协议模型的边界设计

协议模型不应该直接等同数据库模型或业务对象。数据库关注存储结构,业务对象关注领域逻辑,而协议模型关注模块通信。

在智能体工程中,建议分别设计:

  • 输入模型:描述客户端或上游模块发送的数据
  • 输出模型:描述 Agent 返回的数据结构
  • 事件模型:描述流式过程中的状态变化
  • 工具模型:描述工具调用参数和结果

这样可以降低模块耦合,让模型升级或工具替换时影响范围更小。

常见错误

一个常见问题是把大模型输出直接当可信数据使用。模型生成的 JSON 即使格式正确,也可能语义错误,因此协议校验只能保证结构正确,业务规则仍需要额外验证。

另一个问题是协议字段设计过于宽松,例如大量使用 dict[str, object]。灵活字段适合扩展,但核心流程字段应该保持明确类型。

本课总结

  • Pydantic 协议模型为智能体模块提供稳定的数据契约。
  • Schema 应覆盖消息、工具调用、任务状态和结构化输出等核心交互。
  • 数据校验解决格式问题,业务验证负责解决语义问题。

下一课预告

下一课将继续设计智能体工程架构中的异步与流式通信,让模型输出、工具事件和客户端状态可以实时传递。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

使用 Pydantic 定义协议模型

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通