ツールの追加と管理

重要

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

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

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

概要

Agent 365 Tooling の統合は、次のワークフローに従います。

MCP サーバーの構成 - Agent 365 CLI を使用して MCP サーバーを検出して追加する
マニフェストの生成 - CLI は、サーバー構成を使用してプロジェクトフォルダーに ToolingManifest.json を作成します。
ブループリントにアクセス許可を適用する - グローバル管理者は、 a365 setup all (初回セットアップ) または a365 setup permissions mcp (ブループリントが既に存在する場合) を実行して、OAuth2 アクセス許可をエージェントブループリントに付与します。どちらの方法でも、コマンドは ToolingManifest.json を読み取り、管理者の同意が必要です。この手順は、常にマニフェストにサーバーを追加する手順とは別です。
コードに統合 する - マニフェストを読み込み、ツールをオーケストレーターに登録します。
ツールの呼び出し - エージェントは実行中にツールを呼び出して操作を実行します。

前提条件

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

Agent 365 CLI がインストールされ構成済み
.NET 8.0 SDK 以降 - Download
Microsoft 365 テナントのグローバル管理者特権

エージェント ID の設定

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

OBO認証の設定

エージェント認証の代わりにOn-Behalf-Of(OBO)認証を使う場合、エージェントはエージェントユーザーIDなしで委任されたユーザー権限を使ってMCPツールにアクセスできます。 OBOフローでは、エージェントがユーザーの委任トークンを交換し、ユーザーの代わりにアクションを実行します。

OBOフローの仕組みについての詳細は「認証フロー」をご覧ください。完全な実装例については、Microsoft 365 Agents SDKの OBO 承認サンプルを参照してください。

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

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

重要

このテナントごとの一度限りの操作にはグローバル管理者権限が必要です。

New-Agent365ToolsServicePrincipalProdPublic.ps1 脚本をダウンロードしてください。
PowerShellを管理者として開いて、スクリプトディレクトリに行きます。

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

.\New-Agent365ToolsServicePrincipalProdPublic.ps1

メッセージが表示されたら、Azure資格情報を使用してサインインします。

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

MCP サーバーの構成

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

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

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

a365 develop list-available

MCP サーバーの追加

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

a365 develop add-mcp-servers mcp_MailTools

重要

このコマンドは、プロジェクトフォルダー内の ToolingManifest.json のみを更新します。ブループリントへのアクセス許可は付与 されません 。アクセス許可の適用方法は、セットアッププロセスの場所によって異なります。

初期セットアップの前に:最初に a365 develop add-mcp-servers 実行してから、 a365 setup allに進みます。 setup all コマンドには、ブループリント作成の一環として MCP アクセス許可ステップが含まれています。
ブループリントが既に存在した後:グローバル管理者は、 a365 setup permissions mcp 個別に実行する必要があります。管理者のa365.config.jsonには、更新されたdeploymentProjectPathを含むプロジェクトフォルダーを指すToolingManifest.jsonが必要です。この手順が完了するまで、新しい MCP サーバーのアクセス許可はブループリントに表示されません。

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

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

a365 develop list-configured

MCP サーバーの削除

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

a365 develop remove-mcp-servers mcp_MailTools

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

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

テストや開発では、実際の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

// Use McpToolServerConfigurationService.listToolServers
const { McpToolServerConfigurationService } = require('@microsoft/agents-a365-tooling');

const configService = new McpToolServerConfigurationService();
const toolServers = await configService.listToolServers(agentUserId, authToken);

パラメーター:

パラメーター	タイプ	説明	期待値	必須/任意
`agentInstanceId`	文字列	エージェントインスタンスの一意識別子	有効なエージェントインスタンス ID 文字列	必須
`authToken`	文字列	MCP サーバーゲートウェイを使用して認証するためのベアラートークン	有効な OAuth ベアラートークン	必須

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

// Use IMcpToolServerConfigurationService.ListToolServersAsync
using Microsoft.Agents.A365.Tooling.Services;

var configService = serviceProvider.GetRequiredService<IMcpToolServerConfigurationService>();
var toolServers = await configService.ListToolServersAsync(agentInstanceId, authToken);

パラメーター:

パラメーター	タイプ	説明	期待値	必須/任意
`agentInstanceId`	文字列	エージェントインスタンスの一意識別子	有効なエージェントインスタンス ID 文字列	必須
`authToken`	文字列	MCP サーバーゲートウェイを使用して認証するためのベアラートークン	有効な OAuth ベアラートークン	必須

パッケージ: Microsoft.Agents.A365.Tooling

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

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

AddToolServersToAgentAsync (.NET)
add_tool_servers_to_agent (Python)
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を実行すると、CLI によって MCP サーバーカタログから OAuth スコープと対象ユーザーの値が自動的に取得され、ToolingManifest.jsonに書き込まれます。拡張メソッドでは、これらの値を使用して実行時に認証を設定します。エージェントコードで手動で構成する必要はありません。ただし、グローバル管理者は、エージェントが運用環境で使用する前に、 a365 setup all (初回セットアップ) または a365 setup permissions mcp (ブループリントが既に存在する場合) を使用して、これらのアクセス許可をエージェントブループリントに付与する必要があります。

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

実装の例

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

OpenAI を使用したPython

この例では、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}")

メソッドパラメータ

次の表では、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エージェントに登録します。
マニフェスト設定に基づいて認証を設定します。
代理人が活用できるツールを提供します。

LangChain における JavaScript

この例は、JavaScriptやTypeScriptアプリケーションでMCPツールをLangChainと統合する方法を示しています。

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

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

import { McpToolServerConfigurationService } from '@microsoft/agents-a365-tooling';
import { McpToolRegistrationService } from '@microsoft/agents-a365-tooling-extensions-langchain';

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

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

const toolService = new McpToolRegistrationService();

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

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

// Get MCP Tools
try {
  const agent = await toolService.addToolServersToAgent(
    agent,
    process.env.AGENTIC_USER_ID || '',
    authorization,
    turnContext,
    process.env.MCP_AUTH_TOKEN || "",
  );
} catch (error) {
  console.error('Error adding MCP tool servers:', error);
}

メソッドパラメータ

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

パラメーター	説明
`agent`	ツールを登録する LangChain ReactAgent インスタンス。
`agentUserId`	エージェントユーザーのユニークID。エージェント認証を使っていない場合は、空文字列(`''`)を使いましょう。
`authorization`	ユーザーの認可コンテキスト。
`turnContext`	エージェント SDK の現在の会話ターンのコンテキスト。セキュリティで保護されたツール登録用のユーザー ID、会話メタデータ、および認証コンテキストを提供します。
`authToken`	(オプション) 非エージェンティック認証シナリオのベアラートークン。

4. 初期化中の呼び出し

初期化中に addToolServersToAgent メソッドを呼び出して、MCP ツールをエージェントに登録します。

addToolServersToAgent メソッドは自動的に次を実行します：

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

Semantic Kernelを使用した.NET

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

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

Tooling モジュールとSemantic Kernel拡張機能にアクセスするために必要な名前空間を追加します。

using Microsoft.Agents.A365.Tooling;
using Microsoft.Agents.A365.Tooling.Extensions.SemanticKernel;

2. サービスの依存関係の挿入による登録

ツールサービスを依存性注入コンテナに追加し、クラスに注入できるようにします:

builder.Services.AddSingleton<IMcpToolRegistrationService, McpToolRegistrationService>();
builder.Services.AddSingleton<IMcpToolServerConfigurationService, McpToolServerConfigurationService>();

3. 非公開フィールド宣言の追加

ツール登録サービス参照を保持する非公開フィールドを宣言します:

private readonly IMcpToolRegistrationService _toolsService;

4. MCP ツールを Semantic Kernel に登録する

AddToolServersToAgentAsync 拡張メソッドを使用して、構成されているすべての MCP ツールを Semantic Kernel インスタンスに登録します。この方法では、エージェンティック認証と非エージェンティック認証の両方のシナリオを処理します:

// Simplified call (authentication configured automatically)
await toolService.AddToolServersToAgentAsync(kernel, userAuthorization, turnContext);

// Or with explicit authentication parameters:
if (useAgenticAuth)
{
    await toolService.AddToolServersToAgentAsync(kernel, userAuthorization, authHandlerName, turnContext);
}
else
{
    await toolService.AddToolServersToAgentAsync(kernel, userAuthorization, authHandlerName, turnContext, authToken);
}

注意

複数のメソッドオーバーロードが利用可能です。簡易バージョンでは既定の認証構成を使用しますが、明示バージョンではカスタム認証ハンドラーの仕様を使用できます。

メソッドパラメータ

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

パラメーター	説明
`kernel`	ツールを登録するSemantic Kernel インスタンス。 Kernel は、AI サービス、プラグイン、および関数の実行を調整します。
`userAuthorization`	ユーザーの認可コンテキスト。
`authHandlerName`	ユーザー認証システムで使用する認証ハンドラ名。
`turnContext`	エージェント SDK からの現在の会話ターンコンテキスト (1 つのユーザーメッセージとエージェント応答サイクル)。セキュリティで保護されたツール登録用のユーザー ID、会話メタデータ、および認証コンテキストを提供します。
`authToken`	(オプション) 非エージェンティック認証シナリオのベアラートークン。

AddToolServersToAgentAsync メソッドは自動的に行われます。

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

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

エージェント365 MCPサーバーにアクセスするその他の方法

Agent 365 SDKに加え、他の開発体験を通じてAgent 365 MCPサーバーにもアクセス可能です:

Visual Studio Code - カスタム開発ワークフローのために MCP サーバーに直接接続します。
Microsoft Copilot Studio - 低コードエクスペリエンスを使用して MCP サーバーを会話フローに統合します。
Azure AI Foundry - 完全な SDK サポートと高度なオーケストレーション機能を備えた MCP サーバーを使用します。

これらのプラットフォーム間で利用可能なMCPサーバーおよび統合オプションの完全な概要については、 Agent 365ツールサーバーの概要をご覧ください。

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

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

可観測性を追加

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

トラブルシューティング

このセクションでは、MCPサーバーやツールの設定や使用時によくある問題をリストアップしています。

ヒント

Agent 365トラブルシューティングガイドには、Agent 365 の開発ライフサイクルの各段階に対応した高レベルのトラブルシューティング推奨事項、ベストプラクティス、トラブルシューティングコンテンツへのリンクが含まれています。

MCPサーバーとツールの問題

症状：

ツール呼び出し失敗。
「MCPサーバーが見つかりません」エラー。
ツールを呼び出す際の許可拒否エラー。

根本原因:

MCPサーバーは設定されていません。
権限が不足している
サービスプリンシパルはまだ設定されていません。
モックサーバーと本番サーバーの混乱。

解決策: 問題解決のために以下の解決策を試してみてください。

MCPサーバーの設定を確認してください

設定済みサーバーをリストアップし、欠けているサーバーを追加します。

# List configured servers
a365 develop list-configured

# If empty, add required servers (example: Mail MCP server)
a365 develop add-mcp-servers mcp_MailTools

チェックサービスプリンシパルが存在する

ツール用に必要なサービスプリンシパルが作成されていることを確認してください。
```
# Run the one-time setup script
# https://github.com/microsoft/Agent365-devTools/blob/main/scripts/cli/Auth/New-Agent365ToolsServicePrincipalProdPublic.ps1
```
初期の開発やテストでは、モックサーバーを使いましょう

本番のツールコンポーネントなしでエージェントの他の部分をテストしたい場合は、初期のローカル開発とテストにはモックツールサーバーを使いましょう。
```
# Start mock tooling server
a365 develop start-mock-tooling-server

# Update your .env
MCP_PLATFORM_ENDPOINT=http://localhost:5309
```
モックツールサーバーについて学びましょう。
管理センターで権限を確認する

エージェントが必要なMCP権限を持っているか確認してください。
- Azure ポータルのエージェントブループリント API のアクセス許可に、すべての MCP サーバーのアクセス許可が表示されていることを確認します。
検証:
```
# Test a tool call in Agents Playground
# Should execute without permission errors
```

フィードバック

このページはお役に立ちましたか?

Last updated on 2026-03-09

次の方法で共有

ツールの追加と管理

概要

前提条件

エージェント ID の設定

OBO認証の設定

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

MCP サーバーの構成

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

MCP サーバーの追加

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

MCP サーバーの削除

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

ツールマニフェストを理解する

マニフェスト構造

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

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

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

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

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

実装の例

OpenAI を使用したPython

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

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

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

メソッド パラメータ

4. 初期化中の呼び出し

エージェント365 MCPサーバーにアクセスするその他の方法

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

可観測性を追加

トラブルシューティング

MCPサーバーとツールの問題

フィードバック

その他のリソース

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

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

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

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

メソッドパラメータ