在pydantic-ai中构建多消息代理的最佳实践

在构建基于大语言模型（LLM）的应用时，如何有效地构建提示词（prompt）是一个关键问题。pydantic-ai作为一个强大的Python库，提供了类型安全的方式来构建和管理与LLM的交互。本文将深入探讨如何在pydantic-ai中构建包含多消息的代理，特别是如何实现few-shot学习（少量样本学习）的场景。

理解消息结构

pydantic-ai采用了清晰的消息类型层次结构：

1. 系统消息：通过Agent的instructions或system_prompt参数设置，定义代理的基本行为和角色
2. 用户消息：使用ModelRequest类表示，可以包含文本、图片或二进制内容
3. 助手消息：使用ModelResponse类表示，主要是文本响应

这种结构很好地对应了常见的聊天式交互模式，同时保持了类型安全。

实现few-shot学习

few-shot学习是通过提供少量示例来引导模型行为的重要技术。在pydantic-ai中，我们可以通过构建消息历史（message_history）来实现：

from pydantic_ai import Agent, BinaryContent
from pydantic_ai import messages as _messages

# 辅助函数简化消息创建
def user_message(content):
    return _messages.ModelRequest(
        parts=[_messages.UserPromptPart(content=content)]
    )

def model_message(content):
    return _messages.ModelResponse(parts=[_messages.TextPart(content=content)])

# 创建代理
agent = Agent("google-gla:gemini-2.0-flash", 
             instructions="你是一个数学助手")

# 构建few-shot示例
message_history = [
    user_message("1+1"),
    model_message("2"),
    user_message("6/2"),
    model_message("3"),
    user_message(BinaryContent(data=image_data, media_type="image/png")),
    model_message("2"),
    user_message("8*9=?")  # 实际要解决的问题
]

# 执行
response = agent.run_sync(message_history=message_history)

这种结构清晰地展示了few-shot学习的三个关键部分：系统指令、示例对和实际查询。

高级技巧与注意事项

1. 内容类型：pydantic-ai支持多种内容类型，包括文本、图片URL和二进制数据，这使得构建多模态应用成为可能。

2. 时间戳处理：虽然消息类接受自定义时间戳，但在大多数情况下使用默认值即可。时间戳主要用于内部排序和追踪，通常不会影响LLM的输出。

3. 类型安全：pydantic-ai的最大优势在于其类型系统，可以避免许多常见的运行时错误。建议充分利用这一特性，而不是直接使用原始字典结构。

4. 消息组织：对于复杂的应用，可以考虑创建专门的类或函数来管理消息历史，保持代码的模块化和可维护性。

实际应用场景

这种多消息代理结构特别适合以下场景：

• 需要明确示例的教学型应用
• 处理多模态输入（如图片+文本）的任务
• 需要保持对话上下文的聊天应用
• 需要严格类型检查的企业级应用

通过pydantic-ai的类型系统，开发者可以构建更健壮、更易维护的LLM应用，同时充分利用few-shot学习等高级技术来提升模型表现。

总之，pydantic-ai为Python开发者提供了一个强大而灵活的工具，使得与LLM的交互既简单又可靠。掌握其消息系统的设计理念和使用方法，将大大提升开发效率和应用程序质量。