Mastra框架中Agent与Postgres内存交互的顺序问题解析

问题背景

在使用Mastra框架开发AI助手应用时，开发团队遇到了一个关于消息顺序处理的棘手问题。当Agent配置了Postgres内存存储并与Anthropic的Claude模型交互时，特定场景下会出现AI_APICallError错误。这个问题特别出现在涉及工具调用(tool calls)的对话流程中。

问题现象

错误信息显示，Anthropic API拒绝处理请求，原因是工具结果(tool_result)块中发现的tool_use_id没有在前一条消息中找到对应的工具使用(tool_use)块。从错误日志可以清楚地看到，消息序列中工具使用和工具结果的顺序出现了错位。

技术分析

深入分析这个问题，我们可以发现几个关键的技术点：

1. 消息存储机制：Mastra使用Postgres存储对话历史，通过createdAt时间戳对消息进行排序。当多条消息具有相同的时间戳时，排序可能出现不确定性。

2. 工具调用流程：正常的工具调用应该遵循"请求-响应"模式：

   • 助手发送工具使用请求(tool_use)
   • 客户端执行工具并返回结果(tool_result)
   • 这个结果应该紧跟在对应的工具使用请求之后

3. 前端交互：当使用assistant-ui等前端库时，工具可能在客户端执行，这会影响消息的角色(role)分配和顺序。

根本原因

经过技术团队的排查，发现问题主要源于以下几个方面：

1. 时间戳冲突：Postgres存储中多条消息可能共享相同的时间戳，导致排序不稳定。

2. 角色分配不当：前端发送的工具结果被标记为"user"角色而非"assistant"角色，这与API预期不符。

3. 消息重复：前端可能在每次请求中发送完整的对话历史而非增量消息，导致消息重复和顺序混乱。

解决方案

Mastra团队针对此问题提出了以下解决方案：

1. 时间戳偏移：为核心消息添加微秒级的时间偏移，确保每条消息有唯一的时间戳。

2. 角色验证：明确工具结果消息的角色应为"assistant"而非"user"。

3. 增量消息处理：优化前端实现，确保只发送新消息而非完整历史。

4. 存储层优化：增强Postgres存储实现，确保消息检索时的严格顺序。

最佳实践建议

基于这一问题的解决经验，我们建议开发者在实现类似功能时注意以下几点：

1. 严格消息顺序：确保工具调用和结果的严格先后顺序，这是大多数LLM API的基本要求。

2. 唯一时间标识：为每条消息生成唯一的时间标识，避免排序冲突。

3. 角色管理：正确设置消息角色，工具相关消息通常应保持"assistant"角色。

4. 增量更新：前端实现应专注于发送新消息，而非重复整个对话历史。

总结

这个问题展示了在复杂AI应用开发中，消息顺序管理的重要性。Mastra框架通过这次修复，增强了其在工具调用场景下的稳定性，为开发者提供了更可靠的对话管理能力。理解这些底层机制不仅能帮助开发者解决问题，也能更好地设计AI应用的对话流程。