Azure.AI.Projects 客户端库中消息过滤问题的分析与解决

在 Azure.AI.Projects 客户端库的 1.0.0-beta.5 版本中，开发人员发现了一个关于消息过滤功能的重要问题。这个问题涉及到 AgentsClient 类的 GetMessagesAsync 方法的行为与预期不符。

问题背景

GetMessagesAsync 方法设计用于从指定线程中检索消息，并支持通过 runId 参数进行过滤。理论上，当开发者传入 runId 参数时，该方法应该只返回与该特定运行标识符相关联的消息。然而，在实际使用中发现，无论传入什么 runId 值，该方法都会返回线程中的所有消息，完全忽略了过滤条件。

技术分析

经过深入调查，开发团队发现问题的根源在于参数名称的不匹配。服务端 API 期望接收的参数名为 run_id（使用下划线分隔），而客户端库发送的参数名却是 runId（使用驼峰命名法）。这种命名规范的不一致导致服务端无法正确识别过滤参数，从而返回了未经筛选的完整消息列表。

解决方案

开发团队迅速响应，通过以下步骤解决了这个问题：

1. 首先更新了 API 规范（Typespec），确保参数命名与服务端期望的一致
2. 随后在 Python 和 C# 的 SDK 中同步进行了相应的修改
3. 最终在 Azure.AI.Projects 的 1.0.0-beta.8 版本中发布了修复

升级建议

对于遇到此问题的开发者，解决方案非常简单：只需将 Azure.AI.Projects 包升级到 1.0.0-beta.8 或更高版本即可。可以通过以下 NuGet 命令完成升级：

dotnet add package Azure.AI.Projects --version 1.0.0-beta.8

升级后，GetMessagesAsync 方法将能正确地按 runId 过滤消息，行为符合预期。

总结

这个问题展示了在分布式系统开发中，客户端与服务端之间保持严格接口一致性的重要性。即使是像参数命名这样看似微小的差异，也可能导致功能异常。Azure SDK 团队对此类问题的快速响应和修复，体现了他们对开发者体验的重视和对产品质量的承诺。