次の方法で共有

Microsoft Agent 365 SDK を使用してエージェントをテストする

重要

Microsoft Agent 365 の早期アクセスを利用するには、フロンティア プレビュープログラムに参加する必要があります。 フロンティアは、Microsoft の最新の AI イノベーションと直接接続します。 Frontier のプレビューは、お客様の契約書に記載されている既存のプレビュー利用規約に従います。 これらの機能は現在開発中であるため、提供状況や機能は今後変更される可能性があります。

展開前にエージェント プレイグラウンドを使用してエージェントをローカルでテストします。 このガイドでは、エージェント プレイグラウンド テスト ツールを使用して、開発環境の設定、認証の構成、エージェントの機能の検証について説明します。

エージェントがローカルで動作したら、Teams などの Microsoft 365 アプリケーションでテストするために、展開して発行 することができます。

前提条件

エージェントのテストを始める前に、次の前提条件がインストールされていることを確認してください:

一般的な前提条件

言語固有の前提条件

  • Python 3.11+: Microsoft Store または python.org からダウンロード します
  • uv パッケージ マネージャー: を使用して pip install uv
  • インストールを検証する: python --version

エージェントのテスト環境を構成する

このセクションでは、環境変数の設定、開発環境の認証、およびテスト用の Agent 365 を活用したエージェントの準備について説明します。

エージェント テスト環境の設定は、シーケンシャル ワークフローに従います:

  1. 環境を構成する - 環境構成ファイルを作成または更新する

  2. LLM 構成 - API キーを取得し、OpenAI または Azure OpenAI 設定を構成する

  3. 認証を構成する - エージェンティック認証を設定する

  4. 環境変数の参照 - 必要な環境変数を構成します:

    1. 認証変数
    2. MCP エンドポイント構成
    3. 監視変数
    4. エージェント アプリケーション サーバーの構成

これらの手順を完了すると、エージェント プレイグラウンドでエージェントのテストを開始できます。

手順 1: 環境を構成する

構成ファイルを設定します:

cp .env.template .env

注意

Microsoft Agent 365 SDK サンプル を参照して、必要なフィールドを示す構成テンプレートを見つけます。

手順 2: LLM 構成

ローカル テスト用に OpenAI または Azure OpenAI の設定を構成します。 前提条件から取得した API キーとサービス エンドポイントを、モデル パラメーターと共に構成ファイルに追加します。

.env ファイルを追加します:

# Replace with your actual OpenAI API key
OPENAI_API_KEY=

# Azure OpenAI Configuration
AZURE_OPENAI_API_KEY=
AZURE_OPENAI_ENDPOINT=
AZURE_OPENAI_DEPLOYMENT=
AZURE_OPENAI_API_VERSION=

Python LLM 環境変数

変数 プロパティ 必須 例
OPENAI_API_KEY OpenAI サービスの API キー OpenAI の場合 sk-proj-...
AZURE_OPENAI_API_KEY Azure OpenAI Service の API キー Azure OpenAI の場合 a1b2c3d4e5f6...
AZURE_OPENAI_ENDPOINT Azure OpenAI Service エンドポイント URL Azure OpenAI の場合 https://your-resource.openai.azure.com/
AZURE_OPENAI_DEPLOYMENT Azure OpenAI の展開名 Azure OpenAI の場合 gpt-4
AZURE_OPENAI_API_VERSION Azure OpenAI の API バージョン Azure OpenAI の場合 2024-02-15-preview

ステップ3:エージェントの認証を設定する

エージェントのために、以下の認証方法のいずれかを選択してください:

  • エージェント認証 - 本番環境やエージェントユーザーがいる場合に推奨されます。
  • ベアラートークン認証 - エージェントユーザーが利用可能になる前の初期開発およびテストシナリオにのみ使用されます。

エージェント認証

A365 CLI a365 config display コマンドを使用して、エージェント ブループリントの認証情報を取得します。

a365 config display -g

このコマンドは、エージェントのブループリント構成を表示します。 次の値をコピーします。

価値 プロパティ
agentBlueprintId エージェントのクライアント ID
agentBlueprintClientSecret エージェントのクライアント シークレット
tenantId 独自の Microsoft Entra のテナント ID

エージェントでエージェンティック認証を構成するには、次の値を使用します:

プレースホルダー値を実際の認証情報に置き換えて、.env ファイルに次の設定を追加します:

USE_AGENTIC_AUTH=true
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTID=<agentBlueprintId>
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTSECRET=<agentBlueprintClientSecret>
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__TENANTID=<your-tenant-id>
変数 プロパティ 必須 例
USE_AGENTIC_AUTH エージェンティック認証モードを有効にする はい true
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTID a365 config display -g からのエージェント ブループリント クライアント ID はい 12345678-1234-1234-1234-123456789abc
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTSECRET a365 config display -g からのエージェント ブループリント クライアント シークレット はい abc~123...
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__TENANTID a365 config display -gからの Microsoft Entra テナント ID はい adfa4542-3e1e-46f5-9c70-3df0b15b3f6c

ベアラー トークン認証

エージェントユーザーが利用できない場合の初期の開発やテストシナリオでは、ベアラートークン認証を使ってエージェントをテストできます。

まず、 a365 develop add-permissions を使ってアプリケーションに必要なMCPサーバー権限を追加します:

a365 develop add-permissions

次に、 a365 develop get-token を使ってベアラートークンを取得し設定します:

a365 develop get-token

get-tokenコマンドは自動的に次のようになります:

  • ToolingManifest.jsonファイルに設定されているすべてのMCPサーバーのベアラートークンを取得します
  • BEARER_TOKEN環境変数でプロジェクト設定ファイルを更新します

注意

ベアラートークンは約1時間後に期限切れとなります。 a365 develop get-tokenを使って期限切れのトークンを更新してください。

手順 4: 環境変数の参照

次の必須環境変数を構成して、環境設定を完了します:

認証変数

エージェンティック認証が正常に機能するために必要な認証ハンドラー設定を構成します。

.env ファイルを追加します:

# Agentic Authentication Settings
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__AGENTIC__SETTINGS__TYPE=AgenticUserAuthorization
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__AGENTIC__SETTINGS__SCOPES=https://graph.microsoft.com/.default
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__AGENTIC__SETTINGS__ALTERNATEBLUEPRINTCONNECTIONNAME=service_connection

# Connection Mapping
CONNECTIONSMAP_0_SERVICEURL=*
CONNECTIONSMAP_0_CONNECTION=SERVICE_CONNECTION
変数 プロパティ 必須
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__AGENTIC__SETTINGS__TYPE 認証ハンドラーの種類 はい
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__AGENTIC__SETTINGS__SCOPES Microsoft Graph の認証スコープ はい
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__AGENTIC__SETTINGS__ALTERNATEBLUEPRINTCONNECTIONNAME 代替ブループリント接続名 はい
CONNECTIONSMAP_0_SERVICEURL 接続マッピングのサービス URL パターン はい
CONNECTIONSMAP_0_CONNECTION マッピングの接続名 はい

MCP エンドポイント構成

MCP (モデル コンテキスト プロトコル) エンドポイント構成は、エージェントが接続する必要がある Agent 365 プラットフォーム エンドポイントを指定するために必要です。 エージェントの ツーリング サーバー を定義するツーリング マニフェストを生成する場合は、MCP プラットフォーム エンドポイントを指定する必要があります。 このエンドポイントは、Microsoft 365 統合機能のために MCP ツール サーバーが接続する環境 (preprod、テスト、または運用) を決定します。

.env ファイルを追加します:

# MCP Server Configuration
MCP_PLATFORM_ENDPOINT=<MCP endpoint>
変数 プロパティ 必須 デフォルト 例
MCP_PLATFORM_ENDPOINT MCP プラットフォーム エンドポイント URL (preprod、テスト、または prod) いいえ 運用エンドポイント

重要: MCP_PLATFORM_ENDPOINT を指定しない場合は、既定で運用エンドポイントに設定されます。

監視変数

エージェントのログと分散トレースを有効にするには、これらの必須変数を構成します。 監視機能とベスト プラクティスの詳細を確認する

注意

監視の構成は、すべての言語で同じです。

変数 プロパティ デフォルト 例
ENABLE_A365_OBSERVABILITY 監視の有効化/無効化 false true
ENABLE_A365_OBSERVABILITY_EXPORTER 監視サービスにトレースをエクスポートする false true
OBSERVABILITY_SERVICE_NAME トレースのサービス名 エージェント名 my-agent-service
OBSERVABILITY_SERVICE_NAMESPACE サービス名前空間 agent365-samples my-company-agents

エージェント アプリケーション サーバーの構成

エージェント アプリケーション サーバーが実行されるポートを構成します。 この設定は任意で、PythonおよびJavaScriptエージェントに適用されます。

.env ファイルを追加します:

# Server Configuration
PORT=3978
変数 プロパティ 必須 デフォルト 例
PORT エージェント サーバーが実行されているポート番号 いいえ 3978 3978

依存関係をインストールしてエージェント アプリケーション サーバーを起動する

環境が構成されたら、必要な依存関係をインストールし、テストのためにエージェント アプリケーション サーバーをローカルで起動する必要があります。

依存関係のインストール

uv pip install -e .

このコマンドは、pyproject.toml で定義されているパッケージの依存関係を読み取り、PyPI からインストールします。 エージェント アプリケーションを最初から作成するときは、依存関係を定義する pyproject.toml ファイルを作成する必要があります。 サンプル リポジトリ のサンプル エージェントでは、これらのパッケージが既に定義されています。 必要に応じて、追加または更新できます。

エージェント アプリケーション サーバーを起動する

python <main.py>

<main.py> をエージェント アプリケーションのエントリ ポイントを含むメイン Python ファイルの名前に置き換えます (例: start_with_generic_host.py、app.py、または main.py)。

または、uv を使用して:

uv run python <main.py>

エージェント サーバーが実行され、エージェント プレイグラウンドまたは Microsoft 365 アプリケーションから要求を受信する準備が整いました。

エージェント プレイグラウンドでエージェントをテストする

エージェント プレイグラウンドは、テナントの完全な設定を必要とせず、Microsoft 365 環境をシミュレートするローカル テスト ツールです。 エージェントのロジックとツールの呼び出しを検証する最も速い方法です。 詳細については、エージェント プレイグラウンドでテストする を参照してください。

注意

エージェント認証を使用する場合、Agents Playgroundでのダイレクトメッセージングは現在サポートされていません。 代わりにカスタムアクティビティでテストする必要があります。 詳細は 通知活動のあるテスト を参照してください。

新しいターミナル (Windows 上の PowerShell) を開き、エージェント プレイグラウンドを起動します:

agentsplayground

このコマンドは、エージェント・プレイグラウンドのインターフェースを持つウェブブラウザを開きます。 ツールには、エージェントにメッセージを送信できるチャット インターフェイスが表示されます。

Basic テスト

まず、エージェントが正しく構成されていることを確認します。 エージェントにメッセージを送信します:

What can you do?

エージェントは、エージェントのシステムプロンプトや機能に基づいて設定された指示を返信します。 この返信は以下のことを確認しています:

  • エージェントが正しく実行されている
  • エージェントはメッセージを処理して応答できる
  • エージェント プレイグラウンドとエージェントの間の通信が機能している

テスト ツールの呼び出し

toolingManifest.json で MCP ツール サーバーを構成した後 (設定手順については ツーリング を参照)、次のような例でツールの呼び出しをテストします:

まず、使用できるツールを確認します:

List all tools I have access to

次に、特定のツール呼び出しをテストします:

メール ツール

Send email to your-email@example.com with subject "Test" and message "Hello from my agent"

想定される応答: エージェントは、メール MCP サーバーを使用してメールを送信し、メッセージが送信されたことを確認します。

カレンダー ツール

List my calendar events for today

予想される回答:エージェントが当日のカレンダーイベントを取得し表示します。

SharePoint ツール

List all SharePoint sites I have access to

想定される応答: エージェントは SharePoint を照会し、アクセスできるサイトの一覧を返します。

ツールの呼び出しは、次の方法で表示できます:

  • チャット ウィンドウ - エージェントの応答とツールの呼び出しを確認します
  • ログ パネル - ツールのパラメーターと応答を含む詳細な活動情報を表示します

通知アクティビティでテストする

ローカル開発中に、エージェント プレイグラウンドでカスタム活動をシミュレートすることで、通知シナリオをテストできます。 このシミュレーションにより、エージェントの通知処理を本番環境に展開する前に検証できます。

通知アクティビティをテストする前に、次のことを確認します:

通知が正しく機能するには、適切なツール構成と通知設定の両方が必要です。 カスタム活動機能を使用して、メール通知や Word コメントなどのシナリオをテストできます。

カスタム活動を送信するには:

  1. エージェントとエージェント プレイグラウンドを開始する
  2. エージェント プレイグラウンドで、活動のモック>カスタム活動 に移動します
  3. 活動から conversationId をコピーします (エージェント プレイグラウンドが再起動されるたびに会話 ID が変更されます)
  4. カスタム活動 JSON を貼り付け、personal-chat-id フィールドをコピーした会話 ID で更新します。 メール通知の例を参照する
  5. 送信の活動 を選択する
  6. チャット会話とログ パネルの両方で結果を表示する

メール通知

この構成はエージェントに送信されたメールをシミュレートします。 プレースホルダーの値を実際のエージェントの詳細に置き換えます:

{
  "type": "message",
  "id": "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
  "timestamp": "2025-09-24T17:40:19+00:00",
  "serviceUrl": "http://localhost:56150/_connector",
  "channelId": "agents",
  "name": "emailNotification",
  "from": {
    "id": "manager@contoso.com",
    "name": "Agent Manager",
    "role": "user"
  },
  "recipient": {
    "id": "agent@contoso.com",
    "name": "Agent",
    "agenticUserId": "<your-agentic-user-id>",
    "agenticAppId": "<your-agent-app-id>",
    "tenantId": "<your-tenant-id>"
  },
  "conversation": {
    "conversationType": "personal",
    "tenantId": "aaaabbbb-0000-cccc-1111-dddd2222eeee",
    "id": "personal-chat-id"
  },
  "membersAdded": [],
  "membersRemoved": [],
  "reactionsAdded": [],
  "reactionsRemoved": [],
  "locale": "en-US",
  "attachments": [],
  "entities": [
    {
      "id": "email",
      "type": "productInfo"
    },
    {
      "type": "clientInfo",
      "locale": "en-US",
      "timezone": null
    },
    {
      "type": "emailNotification",
      "id": "bbbbbbbb-1111-2222-3333-cccccccccccc",
      "conversationId": "personal-chat-id",
      "htmlBody": "<body dir=\"ltr\">\n<div class=\"elementToProof\" style=\"font-family: Aptos, Aptos_EmbeddedFont, Aptos_MSFontService, Calibri, Helvetica, sans-serif; font-size: 12pt; color: rgb(0, 0, 0);\">\nYour email message content here</div>\n\n\n</body>"
    }
  ],
  "channelData": {
    "tenant": {
      "id": "aaaabbbb-0000-cccc-1111-dddd2222eeee"
    }
  },
  "listenFor": [],
  "textHighlights": []
}

監視ログを表示する

ローカル開発中に監視ログを表示するには、監視コード (コード例については、監視 を参照) を使用してエージェントをインストルメント化し、監視変数 で説明されているように環境変数を構成します。 構成すると、リアルタイム トレースがコンソールに次のように表示されます:

  • エージェント呼び出しトレース
  • ツール実行の詳細
  • LLM 推論呼び出し
  • 入出力メッセージ
  • トークンの使用法
  • 応答時間
  • エラー情報

これらのログは、問題のデバッグ、エージェントの動作の理解、パフォーマンスの最適化に役立ちます。

トラブルシューティング​​

このセクションでは、エージェントをローカルでテストするときに発生する可能性がある一般的な問題の解決策について説明します。

接続と環境の問題

これらの問題は、ネットワーク接続、ポートの競合、および環境設定の問題に関連しており、エージェントが正しく通信できない可能性があります。

エージェント プレイグラウンドの接続に関する問題

症状: エージェント プレイグラウンドがエージェントに接続できない

ソリューション:

  • エージェント サーバーが実行されていることを確認する
  • エージェントとエージェント プレイグラウンドの間でポート番号が一致していることを確認する
  • ローカル接続をブロックするファイアウォール規則がないことを確認する
  • エージェントとエージェント プレイグラウンドの両方の再起動を試みる

古いエージェント プレイグラウンドのバージョン

症状: エージェント プレイグラウンドで予期しないエラーまたは機能が見つからない

解決策: エージェント プレイグラウンドをアンインストールして再インストールします:

winget uninstall agentsplayground
winget install agentsplayground

ポートの競合

症状: ポートが既に使用されていることを示すエラー

解決策:

  • エージェントの他のインスタンスを停止する
  • 構成のポートを変更する
  • ポートを使用してプロセスを強制終了します:
# Windows PowerShell
Get-Process -Id (Get-NetTCPConnection -LocalPort <port>).OwningProcess | Stop-Process

DeveloperMCPServer を追加できません

症状: VS Code で DeveloperMCPServer を追加しようとするとエラーが発生する

解決策: Visual Studio Code を閉じてから再度開き、サーバーをもう一度追加してみてください。

認証の問題

これらの問題は、エージェントが Microsoft 365 サービスで正しく認証できない場合、または認証情報の有効期限が切れているか、正しく構成されていない場合に発生します。

ベアラー トークンの有効期限が切れました

症状: 認証エラーまたは 401 未承認の応答

解決策: ベアラー トークンは約 1 時間後に期限切れになります。 新しいトークンを取得し、構成を更新します。

Python でのエージェンティック認証エラー

症状: エージェント インスタンス トークンの取得中にエラーが発生しました

解決策: ALT_BLUEPRINT_NAME の設定を .env で確認します:

# Change from:
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__AGENTIC__SETTINGS__ALT_BLUEPRINT_NAME=ServiceConnection

# To:
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__AGENTIC__SETTINGS__ALT_BLUEPRINT_NAME=SERVICE_CONNECTION

ツールと通知に関する問題

これらの問題には、ツールの呼び出し、MCP サーバーの対話、通知配信に関する問題が含まれます。

メールが届かない

症状: エージェントはメールが送られたと表示しているが、届かない

ソリューション:

  • 迷惑/スパム フォルダーを確認する
  • メールの配信は数分遅れる場合があります - 最大 5 分待ちます
  • 受信者のメール アドレスが正しいことを確認します
  • メール送信中にエージェント ログにエラーがないか確認する

Word コメントの応答が機能しない

既知の問題: 通知サービスは現在、Word のコメントに直接応答できません。 この機能は開発中です。

エージェントに届かないメッセージ

症状:Teamsでエージェントに送信されたメッセージがエージェントアプリケーションに届きません

考えられる原因:

  • Developer Portalでエージェントブループリントが設定されていない
  • Azure Web Appの問題(デプロイ失敗、アプリが実行されていない、設定エラー)
  • Teamsでエージェントインスタンスが正しく作成されていない

ソリューション:

  1. 開発者ポータルの設定を確認する:

    Developer Portalでエージェントのブループリント設定を完了していることを確認してください。 詳細な手順は開発者 ポータルのエージェントブループリントの設定 をご覧ください。

  2. Azure Web アプリの健康状態を確認してください:

    エージェントがAzureに展開されている場合、Webアプリが正しく動作しているか確認してください:

    1. Azure Portalへナビゲーション
    2. Webアプリのリソースにアクセスしてください
    3. Overview>Statusを確認してください(「Running」と表示されるはずです)
    4. ランタイムエラーの監視欄でログストリームを確認してください
    5. 展開センターのログを確認し、展開が成功したか確認してください
    6. 設定>アプリケーションの設定には必要な環境変数がすべて含まれています

  3. エージェントインスタンス作成の検証:

    Microsoft Teamsでエージェントインスタンスを正しく作成していることを確認してください:

    1. Open Microsoft Teams
    2. アプリに行って代理店を検索してください
    3. エージェントが検索結果に表示されるか確認してください
    4. 見つからなければ、Microsoft 365管理センター - エージェントで公開されているか確認してください
    5. エージェント を追加 して新しいインスタンスを作成します
    6. 詳細な指示については、オンボードエージェントを参照してください

ヘルプの表示

このトラブルシューティング セクションで説明されていない問題が発生した場合は、次のリソースを確認してください:

Microsoft Agent 365 SDK リポジトリ

その他のサポート

次の手順

ローカルでエージェントのテストに成功したら、Azureにデプロイし、Microsoft 365に公開する準備が整います。

  • エージェントの展開と公開:エージェントをAzure Web Appにデプロイし、Microsoft Admin Centerに公開する方法を学びましょう。これにより、組織がMicrosoft 365でエージェントインスタンスを発見・作成できるようになります。
  • Last updated on