迁移到 Microsoft Agent 365 SDK 2.0

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了,就更新实现并重新编译。