次の方法で共有

ツールの追加と管理

重要

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

ツールモジュールは、開発者がモデルコンテキストプロトコル(MCP)サーバーをAIエージェントのワークフローに発見、設定、統合するのに役立ちます。 MCP サーバーは、AI エージェントが呼び出すことができるツールとして外部機能を公開します。 使用可能なツーリング サーバーの概要については、Agent 365 ツーリング サーバー を参照してください。

要求と応答のフローを示します

概要

Agent 365 ツーリングの統合は、次の 4 つのステップから成るワークフローに従います:

  1. MCP サーバーの構成 - Agent 365 CLI を使用して MCP サーバーを検出して追加する
  2. マニフェストの生成 - CLI はサーバー構成で ToolingManifest.json を作成する
  3. コードへの統合 - マニフェストを読み込み、ツールをオーケストレーターに登録する
  4. ツールの呼び出し - エージェントは実行中にツールを呼び出して操作を実行する

前提条件

MCP サーバーを構成する前に、以下を確認してください:

  • Agent 365 CLI がインストールされ構成済み
  • .NET 8.0 SDK 以降 - ダウンロード
  • Microsoft 365 テナントにおけるグローバル管理者権限

エージェント ID の設定

エージェンティック認証を使用している場合は、MCP サーバーを構成する前に、エージェント登録プロセス を完了して、エージェント ID を作成します。 このプロセスにより、エージェントが認証しMCPツールにアクセスできるエージェント向けアプリIDとエージェントユーザーが作成されます。

サービス プリンシパルを設定する

このワンタイムセットアップスクリプトを実行して、テナント内のAgent 365 Toolsのサービスプリンシパルを作成します。

重要

これは、グローバル管理者権限を必要とするテナントごとの ONE-TIME 操作です。

  1. New-Agent365ToolsServicePrincipalProdPublic.ps1 脚本をダウンロードしてください。

  2. PowerShellを管理者として開いて、スクリプトディレクトリに行きます。

  3. スクリプトを実行します。

    .\New-Agent365ToolsServicePrincipalProdPublic.ps1

  4. 求められたらAzureの認証情報を使ってサインインしてください。

完了すると、テナントはエージェント開発と MCP サーバー構成の準備が整います。

MCP サーバーの構成

Agent 365 CLI を使用して、エージェントの MCP サーバーを検出、追加、および管理します。 使用可能な MCP サーバーとその機能の完全な一覧については、MCP サーバー カタログ を参照してください。

使用可能なサーバーの検出

設定可能なすべてのMCPサーバーをリストアップします:

a365 develop list-available

MCP サーバーの追加

エージェント構成に 1 つ以上の MCP サーバーを追加します:

a365 develop add-mcp-servers mcp_MailTools

構成済みサーバーの一覧表示

現在構成されている MCP サーバーを表示します:

a365 develop list-configured

MCP サーバーの削除

構成から MCP サーバーを削除します:

a365 develop remove-mcp-servers mcp_MailTools

完全な CLI リファレンスについては、a365 開発コマンド を参照してください。

テストにはモックツールサーバーを使います

テストや開発では、実際のMCPサーバーに接続する代わりにAgent 365のCLIモックツールサーバーを使用してください。 モックサーバーはMCPサーバーとの相互作用をシミュレートするため、認証などの外部依存関係なしにローカルでエージェントをテストできます。

モックサーバーはローカル開発およびテストに以下の利点を提供します:

  • オフライン開発:インターネット接続や外部依存なしでエージェントをテストしましょう。
  • 一貫したテスト:エッジケースのテストに対して予測可能な回答を得ること。
  • デバッグ:すべてのリクエストとレスポンスをリアルタイムで閲覧
  • 迅速な反復:外部API呼び出しを待つ必要や複雑なテスト環境の設定をする必要はありません。

a365 develop start-mock-tooling-serverコマンドを使ってモックツールサーバーを起動します。

モックツールサーバーの設定と設定を学びましょう。

注意

以下のセクションでは、マニフェストの設定やツールのエージェント統合が、モックツールサーバーでも実際のMCPサーバーでも同じ仕組みです。 MCP_PLATFORM_ENDPOINT環境変数を本番エンドポイントではなくモックサーバー(例:http://localhost:5309)を指すように設定してください。

ツーリング マニフェストの理解

a365 develop add-mcp-servers を実行すると、CLI はすべての MCP サーバーの構成を含む ToolingManifest.json ファイルを生成します。 エージェント ランタイムは、このマニフェストを使用して、使用可能なサーバーとその認証方法を把握します。

マニフェスト構造

例:ToolingManifest.json

{
  "mcpServers": [
    {
      "mcpServerName": "mcp_MailTools",
      "mcpServerUniqueName": "mcp_MailTools",
      "scope": "McpServers.Mail.All",
      "audience": "api://05879165-0320-489e-b644-f72b33f3edf0"
    }
  ]
}

マニフェスト パラメーター

各 MCP サーバー エントリには、次のものが含まれます:

パラメーター 説明
mcpServerName MCP サーバーの表示名
mcpServerUniqueName MCP サーバー インスタンスの一意識別子
スコープ MCP サーバーの機能にアクセスするために必要な OAuth スコープ (例: メール操作用の McpServers.Mail.All)。 add-mcp-serversコマンドはMCPサーバーカタログからこの値を取得します。
対象者 ターゲット API リソースを識別する Microsoft Entra ID URI。 add-mcp-serversコマンドはMCPサーバーカタログからこの値を取得します。

注意

Agent 365のCLIはMCPサーバーを追加すると自動的に scope と audience の値を入力します。 これらの値は、MCP サーバー カタログ から取得され、各 MCP サーバーへのアクセスに必要なアクセス許可を定義します。

エージェントへのツールの統合

ツーリング マニフェストを生成したら、構成済み MCP サーバーをエージェント コードに統合します。 このセクションでは、オプションの検査手順と必要な統合手順について説明します。

リストツールサーバー(オプション)

ヒント

このステップはオプションです。 ツール サーバー構成サービスを使用して、使用可能なツール サーバーをオーケストレーターに追加する前に、ツーリング マニフェストから検査します。

ツール サーバー構成サービスを使用して、ツーリング マニフェストからエージェントが利用可能なツール サーバーを検出します。 この方法により、以下のことが可能になります:

  • すべての設定済みMCPサーバーをその ToolingManifest.json ファイルから照会します。
  • サーバーのメタデータと機能を取得します。
  • 登録前にサーバーの空き状況を確認してください。

ツール サーバーを一覧表示する方法は、コア ツーリング パッケージで使用できます:

# Use McpToolServerConfigurationService.list_tool_servers
from microsoft.agents.a365.tooling import McpToolServerConfigurationService

config_service = McpToolServerConfigurationService()
tool_servers = await config_service.list_tool_servers(agentic_app_id, auth_token)

パラメーター:

パラメーター タイプ プロパティ 変更後の値 必須/任意
agentic_app_id str エージェント アプリケーション インスタンスの一意識別子 有効なエージェント アプリケーション ID 文字列 必須
auth_token str MCP サーバー ゲートウェイで認証するためのベアラー トークン 有効な OAuth ベアラー トークン 必須

パッケージ: microsoft-agents-a365-tooling

オーケストレーターへのツールの登録

フレームワーク固有の拡張機能メソッドを使用して、すべての MCP サーバーをオーケストレーション フレームワークに登録します:

  • AddToolServersToAgentAsync (.NET)
  • add_tool_servers_to_agent (パイソン)
  • addToolServersToAgent (Node.js)

これらのメソッド:

  • 構成済みの MCP サーバーからのすべてのツールをオーケストレーターに登録する
  • 認証と接続の詳細を自動的に設定する
  • エージェントが呼び出すツールをすぐに使用できるようにする

オーケストレーター拡張機能の選択

Agent 365 ツーリング モジュールには、さまざまなオーケストレーション フレームワーク用の専用拡張機能パッケージが用意されています:

  • microsoft-agents-a365-tooling: コア ツーリング機能
  • microsoft-agents-a365-tooling-extensions-agentframework: Agent Framework 統合
  • microsoft-agents-a365-tooling-extensions-azureaifoundry: Azure AI Foundry 統合
  • microsoft-agents-a365-tooling-extensions-openai: OpenAI 統合
  • microsoft-agents-a365-tooling-extensions-semantickernel: Semantic Kernel 統合

注意

a365 develop add-mcp-servers を実行すると、Agent 365 CLI によって認証が自動的に構成されます。 MCPサーバーカタログはOAuthのスコープとオーディエンス値を取得し、それらを ToolingManifest.jsonに含みます。 拡張機能メソッドは、これらの値を自動的に使用して認証を設定します。手動で構成する必要はありません。

詳細な実装例については、Agent 365 サンプル を参照してください。

実装の例

以下の例は、Agent 365ツールをさまざまなオーケストレーションフレームワークと統合する方法を示しています。

Python と OpenAI

この例では、Python アプリケーションで MCP ツールを OpenAI と統合する方法を示します。

1. インポート ステートメントの追加

ツーリング モジュールと OpenAI 拡張機能にアクセスするために必要なインポートを追加します:

from microsoft.agents.a365.tooling import McpToolServerConfigurationService
from microsoft.agents.a365.tooling.extensions.openai import mcp_tool_registration_service

2. ツーリング サービスの初期化

構成およびツール登録サービスのインスタンスを作成します:

# Create configuration service and tool service with dependency injection
self.config_service = McpToolServerConfigurationService()
self.tool_service = mcp_tool_registration_service.McpToolRegistrationService()

3. MCP ツールの OpenAI エージェントへの登録

add_tool_servers_to_agent メソッドを使用して、すべての構成済み MCP ツールを OpenAI エージェントに登録します。 この方法では、エージェンティック認証と非エージェンティック認証の両方のシナリオを処理します:

async def setup_mcp_servers(self, auth: Authorization, context: TurnContext):
    """Set up MCP server connections"""
    try:
        use_agentic_auth = os.getenv("USE_AGENTIC_AUTH", "false").lower() == "true"
        if use_agentic_auth:
            self.agent = await self.tool_service.add_tool_servers_to_agent(
                agent=self.agent,
                agentic_app_id=agentic_app_id,
                auth=auth,
                context=context,
            )
        else:
            self.agent = await self.tool_service.add_tool_servers_to_agent(
                agent=self.agent,
                agentic_app_id=agentic_app_id,
                auth=auth,
                context=context,
                auth_token=self.auth_options.bearer_token,
            )

    except Exception as e:
        logger.error(f"Error setting up MCP servers: {e}")

メソッド parameters

次の表では、add_tool_servers_to_agent で使用するパラメーターについて説明します。

パラメーター 説明
agent ツールを登録する OpenAI エージェント インスタンス。
agentic_app_id エージェントの一意識別子 (エージェンティック アプリ ID)。
auth ユーザーの認可コンテキスト。
context エージェント SDK からの現在の会話ターン コンテキスト。 セキュリティで保護されたツール登録用のユーザー ID、会話メタデータ、および認証コンテキストを提供します。
auth_token (オプション) 非エージェンティック認証シナリオのベアラー トークン。

4. 初期化中の呼び出し

エージェントを実行する前に、初期化中に必ず設定メソッドを呼び出してください:

# Setup MCP servers during initialization
await self.setup_mcp_servers(auth, context)

add_tool_servers_to_agent メソッドは自動的に:

  • ToolingManifest.json ファイルからすべてのMCPサーバーを読み込みます。
  • ツールをOpenAIエージェントに登録します。
  • マニフェスト設定に基づいて認証を設定します。
  • 代理人が活用できるツールを提供します。

完全な作業例については、Agent 365 サンプル リポジトリ を参照してください。

テストと監視

エージェントをテストする

MCPツールをエージェントに統合した後、ツールの呼び出しをテストして正しく動作し、異なるシナリオを扱えるか確認してください。 テストガイドに従って環境を整えましょう。 その後、主に テストツールの呼び出し セクションに注力し、MCPツールが期待通りに動作しているかを検証してください。 また、モ ックツールサーバー をチェックして、認証を扱わずにMCPサーバー接続やツール呼び出しをテストしてみてください。

監視の追加

エージェントに可観測性を追加し、エージェントのMCPツール呼び出しを監視・追跡します。 観測可能性機能を追加することで、パフォーマンスの追跡、問題のデバッグ、ツール使用パターンの理解が可能になります。 追跡とモニタリングの実施について詳しく学びましょう。

  • Last updated on