ヘッドウォータース
🔼

Copilot Studio で作成したエージェントを Microsoft Agent Framework で呼び出す

kodani takushi
に公開
Azure
Python
Entra ID
Copilot Studio
Microsoft Agent Framework
tech

執筆日

2025/12/22

概要

今回は表題の通り「Copilot Studioで作成したエージェントをMicrosoft Agent Frameworkで呼び出す」ことが出来たのでその方法についてまとめようと思います。
公式のGithubに簡単にできそうな感じで書いてあるしいけるやろと思ったらエラーが出てよくわからなかった（作成したエージェントのアプリ登録の設定が権限の都合でできないのが原因？）ので、認証トークン取得周りを自分で実装してみました。アプリに組み込むのにもそっちの方が都合が良さそうなのもあり。

前提

前提の後半、ライセンスや管理センター設定の辺りは今回は省略しています。テナントのグローバル管理者だとスムーズですが、社内の1ユーザーが設定を完遂するには情シスとの連携が大変です。

実行環境

  • CLI: Windows Powershell 7.5.4
  • テスト時のpythonバージョン: 3.11.9
    • 認証はMSALを利用
    • 検証時のMicrosoft Agent Frameworkのバージョン: 1.0.0b251218
      • ※ 執筆時点ではパブリックプレビュー段階のためかなりハイペースで更新されておりコードが変わっている可能性があります

Microsoft関連

pythonの必要ライブラリ

pip install agent-framework==1.0.0b251218
pip install msal

補足知識

  • Microsoft Agent Framework は Copilot Studio のエージェント呼び出しの際に Power Platform API を利用しています
  • Power Platform API の呼び出しのためには、利用者によるログイン認証情報が必要です(セキュリティのためか、共通APIキーのようなものでは呼び出せないようになっています)

セットアップ

以下を実行することでアプリの登録を行った EntraID 認証によって取得したログイン情報で Copilot Studio をAPIから呼び出すことが出来るようになります

1. アプリ登録の設定

  1. Azure Portalでアプリの登録を作成
  2. アプリの登録の認証設定
    • 3のpythonを使ってCLIでデバイスコードを使った認証によるテストを実行する場合
      • 管理→Authentication→設定でパブリッククライアントフローを許可するのトグルを有効化
    • Webアプリで認証を実装する場合(今回省略)
      • 管理→Authentication→リダイレクトURIの構成で必要な設定を行う
  3. Azure Portalで 作成したアプリの登録から管理→APIのアクセス許可→+アクセス許可の追加でサイドバーを開く
  4. Power Platform APIを選択し、委任されたアクセス許可→Copilot StudioでCopilotStudio.Copilots.Invokeにチェックを入れてアクセス許可の追加ボタンを押す
  5. 概要からアプリケーション（クライアント）IDとディレクトリ（テナント）IDを確認

※ 2でPower Platform APIが表示されない場合は、テナントのグローバル管理者に以下のコマンドを実行してもらうなどして、テナントにサービスプリンシパルを追加する必要があります

# Power Platform APIのサービスプリンシパルをテナントに追加するAzure CLIコマンド
az ad sp create --id 8578e004-a5c6-46e7-913e-12f58912df43

この設定が完了すると、MSALのログイン認証実装でスコープにhttps://api.powerplatform.com/.defaultを指定すれば、ログイン情報にPower Platform APIの利用の許可が付与されます

2. Copilot Studio

エージェントの公開

  • Copilot Studioで作成したエージェントを公開する
  • ※ 公開にはCopilot Studio 作成者のロールが必要
    • Power Plattform 管理センター の テナント設定 で Copilot Studio 作成者 にユーザーが登録されていること
    • ユーザー登録にはPower Platformのグローバル管理者権限が必要
    • 1人ずつPower Platformで追加するのではなく、Azureで作成したセキュリティグループを紐づけるため、そこに追加されているアカウントが対象ユーザーになる

公開したエージェントの情報を取得

  • 作成したエージェントで設定→上級→メタデータを開き、環境IDとスキーマ名を取得する

サンプルコード

  • テナントID, クライアントIDは1. アプリ登録の設定で取得したもの
  • この認証はCLIでテスト実行するためのもので本番アプリ向けではありません
authentication
import msal
import os, json

CLIENT_ID = "クライアントID"
TENANT_ID = "テナントID"
AUTHORITY = f"https://login.microsoftonline.com/{TENANT_ID}"
SCOPE = ["https://api.powerplatform.com/.default"] # Power Platform APIを利用するためのトークン取得スコープ
def get_user_token():
    app = msal.PublicClientApplication(
        CLIENT_ID,
        authority=AUTHORITY,
    )
    
    # デバイスコードフローを開始
    flow = app.initiate_device_flow(scopes=SCOPE)
    if "user_code" not in flow:
        raise Exception("デバイスコードの取得に失敗しました")
    print(flow["message"])
    
    # ユーザーがブラウザで認証するまで待機
    result = app.acquire_token_by_device_flow(flow)
    
    # 認証情報詳細を確認
    if result:
        print(json.dumps(result, indent=2, ensure_ascii=False))
    else:
        print("認証失敗")
        return None
    
    # アクセストークンの取得    
    if "access_token" not in result:
        print(json.dumps(result, indent=2, ensure_ascii=False))
        return None
    user_token = result["access_token"]
    return user_token
  • 環境ID, スキーマ名は2. Copilot Studioで取得したもの
invoke_copilot_agent
from agent_framework.microsoft import CopilotStudioAgent
async def main():
    user_token = get_user_token()

    agent = CopilotStudioAgent(
        environment_id="環境ID",
        agent_identifier="スキーマ名",
        token=user_token  # EntraIDでログインしたユーザーのトークン
    )
    
    query = input("\n質問 >> ")
    result = await agent.run(query)

    # 出力詳細確認
    print("\nCopilot Studio Agent result:", json.dumps(result.to_dict(), ensure_ascii=False, indent=2))
    print("\n回答:", result.text)

if __name__ == "__main__":
    asyncio.run(main())
テスト実行結果

表示されたURLを開いてコードを入力すると質問 >>が表示されます。
実際はAzure AI Searchを接続して検索エージェントを実行してみたのですが、検索結果の詳細を取得する方法は見つかりませんでした。参照先・リンク先とかを取得したい場合はプロンプトで制御して出力させるしかないかも？

$ python test.py

To sign in, use a web browser to open the page https://microsoft.com/devicelogin and enter the code XXXXXXXX to authenticate.

質問 >> こんにちは

Copilot Studio Agent result: {
  "type": "agent_run_response",
  "messages": [
    {
      "type": "chat_message",
      "role": {
        "type": "role",
        "value": "assistant"
      },
      "contents": [
        {
          "type": "text",
          "text": "Hello, how can I help you today?"
        }
      ],
      "author_name": "スキーマ名",
      "message_id": "XXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXX",
      "additional_properties": {}
    }
  ],
  "response_id": "XXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXX",
  "additional_properties": {}
}

回答: Hello, how can I help you today?

おわり

Copilot Studioで作成したエージェントをMicrosoft Agent Frameworkで呼び出す方法を紹介しました。エージェント作ってID入れて終わりだろうなと思ったら思いがけずAzureのEntraID・アプリ登録やサービスプリンシパル周りの勉強の機会になりました。
この通りにやったけど上手くいかなかった、設定方法・項目が変わっていました、その他もっと良い実装があるというご意見などありましたら是非コメントください。

ヘッドウォータース
ヘッドウォータース

株式会社ヘッドウォータースのテックブログです。 AIエージェント、生成AI、Azure、GitHub Copilot、IoT、XR系などData&AIとApp modernizeに関して幅広く投稿します！

Discussion