Microsoft Agent 365 SDK 2.0 可用于 Python、JavaScript 和 .NET。 本次发布包含破坏性变更,但大多数只影响已弃用的可观测性包,且每个变更都有直接的迁移路径。 请使用本文查找适用于您的代理的变更并更新您的代码。
破坏性变更摘要
| Area | Languages | 找零 | Action |
|---|---|---|---|
| 通知 | Python |
AgentLifecycleEvent.USERDELETED 值发生了变化。 |
更新用于与原始字符串值进行比较的代码。 |
| 工具扩展 | .NET |
authToken 不再对 MCP 服务器进行身份验证。 |
传递 UserAuthorization 和 authHandlerName,或者设置 BEARER_TOKEN 环境变量。 |
| 运行时 | Python |
get_observability_authentication_scope() 返回仅应用的 /.default 作用域。 |
使用该作用域并配合仅限应用的令牌解析器。 |
| 可观察性导出 | Python,JavaScript,.NET | 导出始终使用服务对服务(S2S)端点,并需要仅应用的令牌解析器。 | 用仅应用的解析程序替换委托的令牌代码。 |
| 可观测性遥测 | Python,JavaScript,.NET | 消息属性、属性名称和推理验证发生了变化。 | 更新依赖于早期格式的代码、查询和仪表盘。 |
Note
可观测性包已被弃用。 SDK 2.0 仍然发布这些数据,但不要将其用于新的集成。 与其将现有的可观测性集成更新到 SDK 2.0,不如考虑迁移到 Microsoft OpenTelemetry 发行版。
将你的包更新为 Agent 365 SDK 2.0
同时将项目中的每个 Agent 365 SDK 包更新为 2.0 版本。 完整包列表请参见 Agent 365 SDK 包。
pip install --upgrade microsoft-agents-a365-notifications microsoft-agents-a365-tooling microsoft-agents-a365-runtime
将您的代理所使用的其他 Agent 365 包(例如工具扩展)添加到同一个命令中。
Notifications
请审查更新后的生命周期事件值以及SDK 2.0中可用的新事件。
Python:删除的用户生命周期事件值已更改
现在 agenticuserdeleted 值为 AgentLifecycleEvent.USERDELETED。 在早期版本中,值为 agenticuseridentitydeleted。
如果你的代码将生命周期事件与原始字符串进行比较,请将小写事件类型与 AgentLifecycleEvent 成员值进行比较:
from microsoft_agents_a365.notifications import AgentLifecycleEvent, AgentNotification
agent_notification = AgentNotification(app)
@agent_notification.on_agent_lifecycle_notification("*")
async def handle_lifecycle(context, state, notification):
event_type = (notification.activity.value_type or "").lower()
if event_type == AgentLifecycleEvent.USERDELETED.value:
await context.send_activity("User identity deleted")
新的生命周期事件
SDK 2.0 为 Python 和 JavaScript 增加了五个生命周期事件和处理程序。 .NET SDK 已经包含了这些。 完整列表请参见 代理生命周期事件。
工具扩展
如果你使用 .NET 工具扩展,请更新代理对 MCP 服务器进行身份验证的方式。
.NET:authToken 参数不再用于认证 MCP 服务器
此变更适用于 语义内核、Agent Framework 和 Azure AI Foundry 工具扩展。
当你不提供 UserAuthorization 和 authHandlerName 时,扩展仅使用 authToken 通过工具网关发现 MCP 服务器。 然后它仅使用来自 BEARER_TOKEN 或 BEARER_TOKEN_<SERVERNAME> 环境变量的令牌对每个 MCP 服务器进行认证。 该扩展会跳过并记录没有令牌的服务器,因此仅依赖 authToken 的代理可以在不报错的情况下返回没有任何 MCP 工具。
此变更还影响以下始终使用此路径的 Azure AI Foundry 方法:
-
AddToolServersToAgent(同步) GetMcpToolDefinitionsAndResourcesAsync(agentInstanceId, authToken, turnContext)
迁移时,请使用以下选项之一:
智能体身份验证(推荐): 传递
UserAuthorization和authHandlerName,以便扩展通过智能体代表用户 (OBO) 流获取令牌。// Semantic Kernel await toolService.AddToolServersToAgentAsync(kernel, userAuthorization, authHandlerName, turnContext); // Azure AI Foundry: use the async method instead of AddToolServersToAgent await toolService.AddToolServersToAgentAsync(agentClient, userAuthorization, authHandlerName, turnContext);环境变量: 为每个 MCP 服务器设置
BEARER_TOKEN_<SERVERNAME>,或设置BEARER_TOKEN以便对所有服务器使用同一个令牌。 该选项适合本地开发和测试。
更多信息请参见 “向你的编排器注册工具”。
Runtime
如果你的 Python 智能体使用运行时包获取可观测认证范围,请查看以下更改。
Python:可观测身份验证范围仅限应用
get_observability_authentication_scope() 现在返回 observability resource /.default scopeapi://9b975845-388f-4429-889e-eab1ef63949c/.default。 在早期版本中,它返回了委派 Agent365.Observability.OtelWrite 范围。
仅使用该范围来获取导出代理实例的应用专用令牌。 详情请参见“可观测性导出使用仅应用认证”。
SDK 2.0中的可观测性变更
以下变更适用于在全部三种语言中已弃用的 Agent 365 可观测性包。
可观测性导出使用仅应用认证
SDK 2.0 取消了可观察性导出的委托认证:
- 导出器总是将遥测数据发送到S2S路由。
use_s2s_endpoint(Python)、useS2SEndpoint(JavaScript)和UseS2SEndpoint(.NET)选项被忽略,即使设置为false。 - 导出器需要一个令牌解析器,为导出代理实例返回一个仅限应用的令牌。 S2S 路由拒绝委派令牌。
- 托管令牌缓存获取仅应用令牌。 委派注册方式不再获取令牌。
- 在 .NET 中,
EnvironmentUtils.GetObservabilityAuthenticationScope()返回仅应用的/.default范围,而不是委派的Agent365.Observability.OtelWrite范围。
| 语言 | 移动 | 请改用 |
|---|---|---|
| Python |
AgenticTokenCache.register_observability(...),现在是一个记录错误的 no-op |
AgenticTokenCache.refresh_observability_token(agent_id, tenant_id, token_resolver) |
| JavaScript |
RefreshObservabilityToken,包含 TurnContext 和 Authorization,以及用于导出器令牌的 runWithExportToken |
RefreshObservabilityToken(agentId, tenantId, tokenResolver)使用withTokenResolver(...)或exporterOptions.tokenResolver |
| .NET |
AgenticTokenCache.RegisterObservability(...) 使用 AgenticTokenStruct,现已过时并导致编译器错误 |
在导出器选项中使用 ObservabilityTokenResolver 以及 AgenticTokenCache.RefreshObservabilityToken(...)、TokenResolver 或 ContextualTokenResolver |
MCP 服务器、Microsoft Graph 和 OBO 流的工作负载身份验证不变。
关于每种语言中的解析器需求和代码示例,请参见 令牌解析器。
可观测遥测格式变更
更新创建遥测以及依赖本节描述的消息格式、验证规则或属性名称的任何查询或仪表盘的代码。
消息属性是 JSON 数组
gen_ai.input.messages 和 gen_ai.output.messages 属性现已遵循 OpenTelemetry 生成式 AI 语义规范。 它们会被序列化为普通 JSON 数组,例如 [{"role": ..., "parts": [...]}],而不是 {"version": "0.1.0", "messages": [...]} 包装器。
-
Python:
A365_MESSAGE_SCHEMA_VERSION常数以及InputMessages和OutputMessages上的version字段被移除。OutputMessage.finish_reason默认为"stop"。 -
JavaScript:
A365_MESSAGE_SCHEMA_VERSION导出和在InputMessages和OutputMessages上的version属性已被移除。 改用DEFAULT_FINISH_REASON。 你用普通字符串生成的输出消息默认从finish_reason到"stop"。 -
.NET:已删除
MessageConstants类以及InputMessages.Version和OutputMessages.Version属性。OutputMessage.FinishReason不可空,默认为"stop"。
更新任何解析这些属性的代码、查询或仪表盘,使其期望得到JSON数组。
推理细节已验证
-
Python:
InferenceCallDetails需要非空白model或responseModel。 如果两者都缺失或为空,则构造会引发ValueError。 -
JavaScript:
InferenceDetails.providerName是必需的。model是可选的,但你必须提供非空白model或responseModel。InferenceScope.start()如果这些值缺失,则会抛出异常。 如果endpoint.port不是 1 到 65535 之间的整数,它也会引发异常。
属性和操作名称的变更
-
Python:推理操作名称和 span 名称前缀使用规范的小写 OpenTelemetry 值
chat、text_completion和generate_content。 例如,Chat gpt-4将变为chat gpt-4。 更新区分大小写的筛选器、仪表板和提醒。 -
JavaScript:
- 当端口为
server.port时,推断跨记录443。 - OpenAI 扩展响应 span 会在
gen_ai.response.model中报告所提供的模型,而不是在gen_ai.request.model中。 - LangChain 扩展不再将所服务模型作为
gen_ai.request.model的回退。 它仅在gen_ai.response.model中报告所服务的模型。
- 当端口为
-
.NET:
gen_ai.tool.arguments属性已重命名为gen_ai.tool.call.arguments。
.NET:IA365EtwLogger 接口变更
该IA365EtwLogger接口为每个现有Exception? error方法添加了一个Log*方法和一个可选LogApplyGuardrail(...)参数。 如果你实现 IA365EtwLogger了,就更新实现并重新编译。