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 エクスポートは常にサービス間(Service-to-service、S2S)エンドポイントを使用し、アプリ専用のトークンリゾルバが必要です。 委任されたトークンコードをアプリ専用リゾルバに置き換えましょう。
観測性テレメトリー Python、JavaScript、.NET メッセージ属性、属性名、推論検証が変更されました。 以前のフォーマットに依存するコード、クエリ、ダッシュボードを更新してください。

Note

観測可能性パッケージは廃止されています。 SDK 2.0は依然として公開していますが、新しい統合には使用しないでください。 既存のオブザーバビリティ統合をSDK 2.0に更新する代わりに、Microsoft OpenTelemetry Distroへの移行を検討してください。

パッケージを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:削除されたユーザーライフサイクルイベントの値が変更されました

AgentLifecycleEvent.USERDELETED値は現在agenticuserdeletedです。 以前のバージョンでは、その値は 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に5つのライフサイクルイベントとハンドラを追加します。 .NET SDKにはすでに含まれています。 完全なリストについては、 エージェントのライフサイクルイベントを参照してください。

ツール拡張

.NETツール拡張機能を使っている場合は、エージェントがMCPサーバーに対して認証する方法を更新してください。

.NET: authToken パラメーターではもはや MCP サーバーを認証しなくなりました

この変更はSemantic Kernel、Agent Framework、Azure AI Foundryのツール拡張に適用されます。

UserAuthorizationやauthHandlerNameを提供しない場合、拡張機能はツールゲートウェイを通じてMCPサーバーを検出するためにのみauthTokenを使用します。 その後、BEARER_TOKEN_<SERVERNAME> または BEARER_TOKEN 環境変数のトークンのみを使用して各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> を設定するか、すべてのサーバーで1つのトークンを使用するには BEARER_TOKEN を設定してください。 このオプションはローカル開発や試験に適しています。

詳細は「 オーケストレーターにツール登録」をご覧ください。

Runtime

もしPythonエージェントがランタイムパッケージを使って可観測性認証スコープを取得している場合、以下の変更点を確認してください。

Python: Observability 認証の範囲はアプリのみです

get_observability_authentication_scope() は現在、観測可能性リソース /.default スコープ api://9b975845-388f-4429-889e-eab1ef63949c/.default を返します。 以前のバージョンでは、委任された Agent365.Observability.OtelWrite スコープを返していました。

このスコープはエクスポートエージェントインスタンスのアプリ専用トークンを取得するためのみ使用してください。 詳細は「 Observability export uses app-only authentication」をご覧ください。

SDK 2.0における観測可能性の変更

以下の変更点は、3言語すべての非推奨のAgent 365可観測性パッケージに適用されます。

Observability エクスポートはアプリのみの認証を使用します

SDK 2.0は、オブザーバビリティエクスポートのための委任認証を廃止します:

  • エクスポーターは常にテレメトリをS2Sルートに送信します。 use_s2s_endpoint(Python)、useS2SEndpoint(JavaScript)、UseS2SEndpoint(.NET)オプションは、falseに設定されていても無視されます。
  • エクスポーターは、エクスポートエージェントインスタンスに対してアプリ専用トークンを返すトークンリゾルバを必要とします。 S2Sルートは委任トークンを拒否します。
  • ホスティングトークンキャッシュはアプリ専用のトークンを取得します。 委任された登録メソッドは、もはやトークンを取得しません。
  • .NET では、EnvironmentUtils.GetObservabilityAuthenticationScope() は委任された /.default スコープの代わりにアプリ専用の Agent365.Observability.OtelWrite スコープを返します。
Language Remove 代わりに使用する
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の意味論的慣習に従っています。 [{"role": ..., "parts": [...]}]ラッパーではなく、{"version": "0.1.0", "messages": [...]}のような単純なJSON配列としてシリアライズします。

  • Python:A365_MESSAGE_SCHEMA_VERSION定数とOutputMessagesおよびversionのInputMessagesフィールドを除去します。 OutputMessage.finish_reason では、既定値が "stop" に設定されます。
  • JavaScript:InputMessages エクスポートと、A365_MESSAGE_SCHEMA_VERSION および version の OutputMessages プロパティは削除されます。 DEFAULT_FINISH_REASON を代わりに使用します。 単純な文字列から作成した出力メッセージは、デフォルトでは "stop" から finish_reason になります。
  • .NET:MessageConstantsクラスとInputMessages.VersionおよびOutputMessages.Versionプロパティが削除されます。 OutputMessage.FinishReason はnullableでなく、デフォルトは "stop"です。

これらの属性を解析するコード、クエリ、ダッシュボードをJSON配列を想定するように更新してください。

推論の詳細が検証されます

  • Python:InferenceCallDetailsは空白でないmodelまたはresponseModelが必要です。 両方が欠けているか空欄の場合は、構築時に ValueError が発生します。
  • JavaScriptInferenceDetails.providerName が必要です。 model 任意ですが、非空欄の model または非空欄 responseModelを提出する必要があります。 InferenceScope.start() これらの値がない場合は例外をスローします。 また、endpoint.port が 1 から 65535 までの整数でなければ例外がスローされます。

属性名と操作名の変更

  • Python:推論操作名およびスパン名プレフィックスは、標準的な小文字OpenTelemetry値chat、text_completion、generate_contentを使用します。 たとえば、Chat gpt-4 を chat gpt-4 にします。 大文字と小文字を区別するフィルター、ダッシュボード、アラートを更新してください。
  • JavaScript:
    • 推論はポートがserver.portのときレコード443にまたがります。
    • OpenAIの拡張レスポンスは、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を実装する場合は、実装内容を更新して再コンパイルしてください。

関連するコンテンツ

  • 最終更新: