Agent Service Toolkit 中 ChatMessage 架构的演进与设计思考

在构建基于 LangChain 的 Agent Service Toolkit 项目时，开发团队面临了一个关于消息处理架构的重要决策。本文将深入分析 ChatMessage 类的设计演变过程，探讨不同技术方案的优劣，并最终呈现团队采纳的解决方案。

初始设计困境

项目初期实现了一个 ChatMessage 类作为 LangChain BaseMessage 的轻量级封装。随着功能迭代，这个包装层开始引入比其价值更多的复杂性，特别是在处理以下场景时：

1. 需要支持 Anthropic 等不同模型的消息格式
2. 要处理包含工具调用的 AIMessage
3. 需要维护 run_id 等元数据信息
4. 支持后台任务等扩展功能

三种设计方案对比

团队提出了三种可能的改进方向：

方案一：保持现状，继续使用 ChatMessage 抽象层。优势在于提供了统一的接口，但会增加维护成本。

方案二：完全移除 ChatMessage，直接使用 LangChain 的 BaseMessage。简化了架构但将格式处理的责任转移给了客户端。

方案三：折中方案，基于 BaseMessage 但提供标准化的简单类型处理，确保 content 始终为字符串类型。

深入技术考量

在讨论过程中，几个关键技术点被反复权衡：

1. 序列化格式：LangChain 提供了 message_to_dict/messages_from_dict 方法，但其序列化格式较为冗长。作为替代，可以考虑直接使用 Pydantic 的 model_dump()。

2. run_id 处理：当前实现中将 run_id 添加到 ChatMessage，如果改用 BaseMessage 需要找到合适的存储位置，如 additional_kwargs。

3. 消息类型处理：需要特别处理包含工具调用的 AIMessage，确保其内容展示的一致性。

最终架构决策

经过充分讨论，团队决定采用扩展方案一，并引入以下改进：

1. 新增 "custom" 消息类型，支持任意自定义数据
2. 添加 send_custom_message() 工具函数，简化自定义消息发送
3. 保留 ChatMessage.from_langchain() 转换逻辑
4. 通过 custom_data 字段支持扩展功能

这种设计既保持了现有接口的简洁性，又为以下场景提供了良好的扩展性：

• 后台任务处理
• 多媒体内容传输
• 自定义业务逻辑集成

实现细节与最佳实践

在实际实现中，开发者应注意：

1. 自定义数据应实现合理的序列化/反序列化逻辑
2. 对于复杂场景，建议使用 Pydantic 模型处理 custom_data
3. 不同类型的功能应通过消息内容区分，而非创建多个消息类型

这种架构演进体现了在保持核心功能稳定的同时，如何通过精心设计的扩展点来适应未来需求变化，是构建可持续演进的 AI 服务架构的优秀实践。