スクリプトでエージェント ID を作成して Graph API を呼び出す at SE の雑記

Microsoft Agent 365 では、エージェントにエージェント ID を付与し、各種リソースへのアクセスを行うことができます。

エージェント ID は手動で作成することができるのですが、エージェント ID の基本的な使用方法を理解するための一助になるかと思い、エージェント ID の作成から Graph API の呼び出しまでスクリプトで実施してみましたというお話です。

Contents

参考となるドキュメント

エージェント ID を手動で作成して利用する際には次のドキュメントが参考となります。

今回は PowerShell で操作をしていますが、現時点では、エージェント ID 関連のコマンドレットは用意されていないため、REST API を呼び出して作業を行う必要があります。

OAuth については次のドキュメントが参考となります。

これらのドキュメントを確認して、スクリプトでエージェント ID の作成を実施していきます。

実際に検証で使用したスクリプトは こちら で公開しています。

実施しているのは次の内容となります。

エージェントブループリントを作成
開発用として、シークレットでアクセスできるように設定
- 今回は開発目的でエージェント ID を使用しているため、エージェント ID ブループリントのトークン取得には、シークレットを使用しています。
識別子 URI とスコープを構成
エージェントブループリントの主要部分を作成
エージェント ID ブループリントを使ってトークンを取得
エージェント ID を作成
エージェント ID にアクセス権を付与
- エージェント ID にアクセス権を付与していますが、ブループリントに対してアクセス権を付与するという考えもあるかもしれませんね。
エージェント ID ブループリントのトークンを要求
エージェント ID トークンを要求
- サンプルスクリプトでは Graph API を使用しているが、他の Azure リソースにアクセスする場合のスコープ指定はマネージド ID を使用してバックエンドサービスで認証するの resource の指定を参照。
Graph API を呼び出し

上記のステップは、次のドキュメントの内容をスクリプト化したものとなります。

シナリオとしては、自律エージェントのエージェントトークンを要求する / エージェント自律アプリの OAuth フロー – アプリ専用プロトコルとなり、エージェントを使用するユーザーではなく、エージェントに割り当てられた個別の ID を使用して処理を実行するという方式となります。

今回、エージェント ID に対しての操作は、REST API を直接呼んでいますが、エージェント ID 向けの API のドキュメントは公開されていますので、不明な点があったらこのドキュメントを参照するとよいかと。

今回、スクリプトでトークンを取得しながら処理を進めていますが、トークンの内容をデコードして確認したい場合は jwt.ms を使用するとよいのではないでしょうか。

これらの作業を実施することで、エージェント ID を使用して必要なリソースへのアクセスが可能となります。

上記のログは Entra ID のサインインログの「サービスプリンシパルのサインイン」となります。
エージェント ID のサインインログはサービスプリンシパルのサインインとして記録されますが、「エージェント ID から Microsoft Graph へのサインイン」としてログが記録されています。

このようなサインインについては、エージェント ID の条件付きアクセスポリシーで制御できるようになるのが Microsoft Agent 365 の特徴の一つとなります。

エージェント ID を使用したリソースのアクセスがどのような挙動を意図するのかは、一度手動で実装してみると分かりやすいのかもしれませんね。

基本的なシナリオについての理解がまだ低いので次の記事も参考にさせていただき、理解度を徐々に深めていきたいと思います。

EntraIDAccessToken PowerShell Module の実装を確認してみるのも勉強になりそうです。