Azure AI Agents SDK 1.0.0b11版本中Hub项目与Foundry项目的兼容性问题解析

背景介绍

Azure AI Agents SDK是微软Azure平台提供的一套用于构建和部署AI代理的开发工具包。在1.0.0b11版本中，开发团队对项目客户端(AIProjectClient)的构造方式进行了重大变更，这直接影响了基于Hub的AI项目的使用方式。

核心变更内容

1.0.0b11版本中，AIProjectClient的构造方式从使用连接字符串(connection string)变更为直接使用项目端点(endpoint)。这一变更导致了许多开发者在使用现有Hub项目时遇到兼容性问题。

问题表现

开发者在使用1.0.0b11版本时，尝试按照文档说明构造AIProjectClient时，会遇到"Project not found"的错误。这主要是因为：

1. Hub项目与Foundry项目使用不同的访问机制
2. 1.0.0b11版本仅支持Foundry项目的新端点格式
3. Hub项目仍然需要使用旧版的连接字符串方式访问

解决方案

针对这一问题，微软开发团队给出了明确的指导：

1. 对于Hub项目：继续使用azure-ai-projects 1.0.0b10版本，通过from_connection_string方法构造客户端
2. 对于新项目：建议创建Foundry项目(非Hub项目)，使用1.0.0b11及以上版本，通过端点方式构造客户端

技术决策背景

从技术演进的角度来看，这一变更反映了Azure AI平台架构的演进方向：

1. Hub项目架构将不会进入GA(General Availability)阶段
2. Foundry项目代表了Azure AI平台的新架构方向
3. 未来版本将仅支持Foundry项目端点方式

迁移建议

对于已经使用Hub项目的开发者，建议采取以下迁移策略：

1. 评估现有项目的重要性，决定是否立即迁移
2. 对于关键项目，可暂时停留在1.0.0b10版本
3. 对于新开发，直接使用Foundry项目架构
4. 关注官方即将发布的迁移工具，以便将Hub项目内容迁移到Foundry项目

开发者注意事项

1. 版本兼容性：仔细检查SDK版本与项目类型的匹配
2. 端点格式：Foundry项目的端点具有特定格式，可在项目概览页面找到
3. 认证方式：两种项目类型都支持DefaultAzureCredential等认证方式
4. 功能差异：虽然核心功能相似，但两种项目类型在某些高级功能上可能存在差异

总结

Azure AI Agents SDK 1.0.0b11版本的这一变更反映了平台架构的演进方向。开发者需要根据项目类型选择合适的SDK版本和访问方式。对于长期维护的项目，建议规划向Foundry项目的迁移路径，以利用平台的最新功能和长期支持。