Foundry でツールボックスを作成および管理する

from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import MCPToolboxTool, ToolSearchToolboxTool, WebSearchToolboxTool

# Create Foundry project client
endpoint = "https://<your-foundry-account>.services.ai.azure.com/api/projects/<your-project>"
project = AIProjectClient(
    endpoint=endpoint,
    credential=DefaultAzureCredential(),
)

# Create toolbox version with web search and MCP tools
toolbox_version = project.toolboxes.create_version(
    name="my-toolbox",
    description="Toolbox with web search and an MCP server",
    tools=[
        WebSearchToolboxTool(),
        MCPToolboxTool(
            server_label="myserver",
            server_url="https://your-mcp-server.example.com",
            require_approval="never",
            project_connection_id="my-key-auth-connection",
        ),
        ToolSearchToolboxTool(),
    ],
)
print(f"Created toolbox: {toolbox_version.name}, version: {toolbox_version.version}")

using Azure.Identity;
using Azure.AI.Projects;

// Create Foundry project client
var projectEndpoint = "https://<your-foundry-account>.services.ai.azure.com/api/projects/<your-project>";
AIProjectClient projectClient = new(new Uri(projectEndpoint), new DefaultAzureCredential());
AgentToolboxes toolboxClient = projectClient.AgentAdministrationClient.GetAgentToolboxes();

WebSearchToolboxTool webTool = new();
MCPToolboxTool mcpTool = new(serverLabel: "myserver")
{
  ServerUri = new Uri("https://your-mcp-server.example.com"),
  ToolCallApprovalPolicy = new McpToolCallApprovalPolicy(
    GlobalMcpToolCallApprovalPolicy.NeverRequireApproval),
};

ToolSearchToolboxTool searchTool = new() { Name = "ToolBoxSearch" };

ToolboxVersion toolboxVersion = await toolboxClient.CreateVersionAsync(
  name: "my-toolbox",
    tools: [webTool, mcpTool, searchTool],
    description: "Toolbox with web search, MCP, and tool search"
);
Console.WriteLine($"Created toolbox: {toolboxVersion.Name}, version: {toolboxVersion.Version}");

POST {project_endpoint}/toolboxes/my-toolbox/versions?api-version=v1
Authorization: Bearer {token}
Content-Type: application/json

{
  "description": "Toolbox with web search, MCP, and tool search",
  "tools": [
    {
      "type": "web_search",
      "description": "Search the web for current information"
    },
    {
      "type": "mcp",
      "server_label": "myserver",
      "server_url": "https://your-mcp-server.example.com",
      "require_approval": "never",
      "project_connection_id": "my-key-auth-connection"
    },
    {
      "type": "toolbox_search"
    }
  ]
}

import { DefaultAzureCredential } from "@azure/identity";
import { AIProjectClient } from "@azure/ai-projects";

// Create Foundry project client
const projectEndpoint = "https://<your-foundry-account>.services.ai.azure.com/api/projects/<your-project>";

const project = new AIProjectClient(projectEndpoint, new DefaultAzureCredential());

const toolboxVersion = await project.toolboxes.createVersion(
  "my-toolbox",
  [
    {
      type: "web_search",
      description: "Search the web for current information",
    },
    {
      type: "mcp",
      server_label: "myserver",
      server_url: "https://your-mcp-server.example.com",
      require_approval: "never",
      project_connection_id: "my-key-auth-connection",
    },
    { type: "toolbox_search" },
  ],
  {
    description: "Toolbox with web search, MCP, and tool search",
  },
);
console.log(`Created toolbox: ${toolboxVersion.name}, version: ${toolboxVersion.version}`);

Microsoft Foundry Toolkit for Visual Studio Code 拡張機能を使用して、Tools ビューからツールボックスを作成して発行します。

1. アクティビティ バーで Foundry Toolkit を選択します。
2. [ マイ リソース] で、[ プロジェクト名>Tools] を展開します。
3. [+ ツールボックスの追加] アイコンを選択します。
4. [ カスタム ツールボックスのビルド ] タブで、ツールボックスの名前と説明を入力し、目的のツールを追加します。
5. 意図ベースのツール ルーティングを有効にするには、[ ツール検索] を選択します。
6. 公開を選択します。

新しいツールボックスを発行すると、最初のバージョンが作成されます。 そのバージョンは自動的に既定のバージョンになります。

統合 microsoft.foundry 拡張機能バンドル ( 前提条件を参照) を使用して、次の 2 つの手順でツールボックスを作成します。

1. azd ai connection createを使用して、ツールボックスが参照する各プロジェクト接続を登録します (資格情報レコードごとに 1 回の呼び出し)。
2. azd ai toolbox create --from-file <toolbox.yaml>を使用してツールボックスを作成します。 YAML は名前で接続を参照し、資格情報を埋め込むことはありません。

このパターンは、接続の種類と認証の種類ごとに同じです。

1. シェルごとにアクティブなプロジェクトを 1 回設定します。

   azd ai project set $PROJECT_ENDPOINT
   

2. azd ai connection createを使用して接続を作成します。 フラグは認証の種類ごとに異なりますが、コマンドの形状は常に次のようになります。

   azd ai connection create <name> \
     --kind <remote-tool|remote-a2a|cognitive-search|GroundingWithCustomSearch> \
     --target <endpoint-url> \
     --auth-type <none|custom-keys|api-key|oauth2|user-entra-token|project-managed-identity|agentic-identity> \
     [--custom-key "Header=Value" | --key <key> | --client-id ... --client-secret ... --authorization-url ... --token-url ... | --audience <aad-resource-uri>]
   

   azd ai connection listとazd ai connection show <name>を使用して接続を検査し、azd ai connection delete <name> --forceして削除します。

3. 1 つ以上の既存の接続を名前で参照するツールボックス YAML を作成します。 YAML は資格情報を埋め込むことはありません。

   # my-toolbox.yaml
   description: <human-readable description>
   connections:
     - name: <project-connection-name>   # must already exist in the project
   # Optional: add connectionless built-in tools and policies.
   tools:
     - type: web_search
       name: web
     - type: code_interpreter
       container: { type: auto }
       name: code
     # Tool search is connectionless.
     - type: toolbox_search
     # For Azure AI Search, set the index in the tool entry:
     # - type: azure_ai_search
     #   name: search
     #   azure_ai_search:
     #     indexes:
     #       - project_connection_id: <azure-ai-search-connection-name>
     #         index_name: <search-index-name>
     # For Bing Custom Search, set the instance in the tool entry:
     # - type: web_search
     #   name: bing
     #   custom_search_configuration:
     #     project_connection_id: <bing-connection-name>
     #     instance_name: <bing-instance-name>
   # Optional: attach existing project skills as MCP resources.
   skills:
     - name: <skill-name>          # uses the skill's default version
     - name: <other-skill>
       version: "2"               # pin to a specific skill version (string)
   policies:
     rai_config:
       rai_policy_name: <policy-name>    # must already exist on the project
   

   少なくとも 1 つの connections、 skills、または tools が空でない必要があります。 スキル参照は、同じ Foundry プロジェクトに既に存在するスキルを指している必要があります。「 Foundry のスキルを使用して 、 azd ai skill createでスキルを作成する」を参照してください。 エンド ツー エンドのツール検索のセットアップの詳細については、「 ツール検索を使用する」を参照してください。

4. そのファイルからツールボックスを作成します。

   azd ai toolbox create <toolbox-name> --from-file ./my-toolbox.yaml
   

   最初のバージョンが自動的に既定値になります。 ツールボックスを管理するには、 azd ai toolbox list、 azd ai toolbox show <name>、 azd ai toolbox version list <name>、および azd ai toolbox delete <name> --force を使用します。

例: キーベースの認証を使用する MCP サーバー

# 1. Create the connection
azd ai connection create my-gh-conn \
  --kind remote-tool \
  --target https://api.githubcopilot.com/mcp/ \
  --auth-type custom-keys \
  --custom-key "Authorization=Bearer $GITHUB_PAT"

# 2. Create the toolbox
azd ai toolbox create my-toolbox \
  --from-file ./my-toolbox.yaml \
  --no-prompt

# my-toolbox.yaml
description: GitHub MCP toolbox
connections:
  - name: my-gh-conn

Microsoft Foundry Toolkit for Visual Studio Code拡張機能で、ツールボックス コンシューマー エンドポイントを Toolboxes ビューからコピーします。

1. アクティビティ バーで Foundry Toolkit を選択します。
2. [ マイ リソース] で、[ プロジェクト名>Tools] を展開します。
3. [ツールボックス] タブ で 、ツールボックスを見つけます。
4. [ エンドポイント URL ] 列で、エンドポイントをコピーします。

エンドポイント URL 値はツールボックス コンシューマー エンドポイントです。 バージョン固有のエンドポイントを構築するには、前の表に示した開発者パターンを使用します。

MCP クライアント SDK をインストールします。

pip install mcp

ツールボックスとリスト ツールに接続する

import asyncio
from azure.identity import DefaultAzureCredential
from mcp.client.streamable_http import streamablehttp_client
from mcp import ClientSession

url = "https://<account>.services.ai.azure.com/api/projects/<proj>/toolboxes/<name>/versions/<version>/mcp?api-version=v1"

token = DefaultAzureCredential().get_token("https://ai.azure.com/.default").token
headers = {
    "Authorization": f"Bearer {token}",
}

async def verify_toolbox():
    async with streamablehttp_client(url, headers=headers) as (read, write, _):
        async with ClientSession(read, write) as session:
            await session.initialize()

            # List available tools
            tools_result = await session.list_tools()
            print(f"Tools found: {len(tools_result.tools)}")
            for tool in tools_result.tools:
                print(f"  - {tool.name}: {(tool.description or '')[:80]}")

            # Call a tool (replace with actual tool name and arguments)
            result = await session.call_tool("<tool_name>", arguments={})
            print(result)

asyncio.run(verify_toolbox())

バージョン固有のエンドポイント (/versions/{version}/mcp) を使用して、昇格する前にバージョンを検証します。

1. MCP セッションを初期化します。

POST {project_endpoint}/toolboxes/{toolbox_name}/versions/{version}/mcp?api-version=v1
Authorization: Bearer {token}
Content-Type: application/json

{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}

2. 初期化された通知を送信します。

POST {project_endpoint}/toolboxes/{toolbox_name}/versions/{version}/mcp?api-version=v1
Authorization: Bearer {token}
Content-Type: application/json

{"jsonrpc":"2.0","method":"notifications/initialized"}

3. 使用可能なツールを一覧表示します。

POST {project_endpoint}/toolboxes/{toolbox_name}/versions/{version}/mcp?api-version=v1
Authorization: Bearer {token}
Content-Type: application/json

{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}

4. ツールを呼び出す:

POST {project_endpoint}/toolboxes/{toolbox_name}/versions/{version}/mcp?api-version=v1
Authorization: Bearer {token}
Content-Type: application/json

{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"<TOOL_NAME>","arguments":{}}}

MCP クライアント SDK をインストールします。

npm install @modelcontextprotocol/sdk

ツールボックスとリスト ツールに接続する

import { DefaultAzureCredential } from "@azure/identity";
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
import { Client } from "@modelcontextprotocol/sdk/client/index.js";

const url = "https://<account>.services.ai.azure.com/api/projects/<proj>/toolboxes/<name>/versions/<version>/mcp?api-version=v1";

const credential = new DefaultAzureCredential();
const token = await credential.getToken("https://ai.azure.com/.default");

const transport = new StreamableHTTPClientTransport(
  new URL(url),
  {
    requestInit: {
      headers: {
        Authorization: `Bearer ${token.token}`,
      },
    },
  },
);

const client = new Client({ name: "test", version: "1.0" });
await client.connect(transport);

// List available tools
const toolsResult = await client.listTools();
console.log(`Tools found: ${toolsResult.tools.length}`);
for (const tool of toolsResult.tools) {
  console.log(`  - ${tool.name}: ${(tool.description || "").slice(0, 80)}`);
}

// Call a tool (replace with actual tool name and arguments)
const result = await client.callTool({ name: "<tool_name>", arguments: {} });
console.log(result);

await client.close();

スキャフォールディングされたホステッド エージェント サンプルと共に ツールボックス MCP エンドポイント を使用して、VS Code でのツールボックスの読み込みを検証します。

1. Foundry Toolkit の [マイ リソース>プロジェクト名>Tools で、テストするツールボックスを見つけます。
2. スキャフォールディング コード テンプレートを選択します。
3. メッセージが表示されたら、プロジェクト フォルダーを選択します。
4. 生成された README.md に従って依存関係をインストールし、環境変数を構成し、サンプルをローカルで実行します。
5. Agent Inspector を使用するか、python main.pyを実行してツールボックス ツールの読み込みと応答を確認します。

新しいツールボックス バージョンを昇格させる前にバージョン固有の検証を行うには、この手順の [Pythonまたは REST API] タブを使用します。

LangGraph

ホストされた統合フラグメントの要件:langchain-azure-ai[tools]>1.2.3をインストールします。 フラグメントでは、 AzureAIProjectToolboxを使用します。エージェント、パッケージ セット、およびデプロイ ファイル全体については、 保守されている LangGraph サンプル を使用します。

.env ファイル:

FOUNDRY_PROJECT_ENDPOINT=https://<account>.services.ai.azure.com/api/projects/<project>
TOOLBOX_ENDPOINT=https://<account>.services.ai.azure.com/api/projects/<project>/toolboxes/<toolbox-name>/versions/<version>/mcp?api-version=v1
TOOLBOX_NAME=agent-tools
AZURE_AI_MODEL_DEPLOYMENT_NAME=gpt-4o

main.py (キー パターン):

from langchain_azure_ai.tools import AzureAIProjectToolbox

toolbox = AzureAIProjectToolbox(toolbox_name=TOOLBOX_NAME)
tools = await toolbox.get_tools()

Microsoft Agent Framework

前提条件Azure ID パッケージに加えて、agent-framework-foundryをインストールします。 完全な実装については、 管理されているエージェント フレームワークのサンプルを参照してください。

Agent Framework SDK の FoundryToolbox を使用してツールボックス エンドポイントに接続します。 クラスはツールボックス認証を処理し、hosted-agent 呼び出しコンテキストを転送します。

.env ファイル:

FOUNDRY_PROJECT_ENDPOINT=https://<account>.services.ai.azure.com/api/projects/<project>
TOOLBOX_ENDPOINT=https://<account>.services.ai.azure.com/api/projects/<project>/toolboxes/<toolbox-name>/versions/<version>/mcp?api-version=v1
AZURE_AI_MODEL_DEPLOYMENT_NAME=gpt-4o

main.py (キー パターン):

from agent_framework.foundry import FoundryToolbox
from azure.identity import DefaultAzureCredential

credential = DefaultAzureCredential()

# Toolbox MCP endpoint (platform-injected at runtime via TOOLBOX_ENDPOINT)
TOOLBOX_ENDPOINT = "https://<account>.services.ai.azure.com/api/projects/<project>/toolboxes/<toolbox-name>/versions/<version>/mcp?api-version=v1"

toolbox = FoundryToolbox(
    credential,
    url=TOOLBOX_ENDPOINT,
)

agent = chat_client.as_agent(
    name="my-toolbox-agent",
    instructions="You are a helpful assistant with access to Foundry toolbox tools.",
    tools=[toolbox],
)
ResponsesAgentServerHost().run()

Copilot SDK

ホストされた統合フラグメントの要件:ランタイムの GitHub Copilot SDK をインストールします。 アウトラインは、ここでは実装されていないアプリケーション所有の McpBridge および _get_toolbox_token ヘルパーに依存します。 既存のツールボックス エンドポイントと認証コントラクトとホステッド エージェント統合パターンに従います。 メンテナンスされている完全なサンプルは、まだ提供されていません。

GitHub Copilot SDK を使用して、Copilotのツール呼び出しを Foundry ツールボックス MCP エンドポイントにブリッジするツールボックスを利用したエージェントを構築します。

.env ファイル:

GITHUB_TOKEN=<your-github-token>
TOOLBOX_ENDPOINT=https://<account>.services.ai.azure.com/api/projects/<project>/toolboxes/<toolbox-name>/versions/<version>/mcp?api-version=v1

agent.py (キー パターン — MCP ブリッジ):

# 1. Open an MCP session to the toolbox endpoint
bridge = McpBridge(endpoint=TOOLBOX_ENDPOINT, token=_get_toolbox_token())
await bridge.initialize()
mcp_tools = await bridge.list_tools()

# 2. Map MCP tool list to Copilot SDK tool definitions
#    Dots in tool names are replaced with underscores (Copilot SDK requirement)
copilot_tools = [
    {
        "name": t["name"].replace(".", "_"),
        "description": t.get("description", ""),
        "parameters": t.get("inputSchema", {}),
    }
    for t in mcp_tools
]

# 3. Wire tool calls back to the MCP session
async def tool_handler(name: str, arguments: dict) -> str:
    return await bridge.call_tool(name.replace("_", ".", 1), arguments)

# 4. Run the Copilot SDK agent
agent = Agent(
    tools=copilot_tools,
    tool_handler=tool_handler,
    token=os.environ["GITHUB_TOKEN"],
)

Microsoft Agent Framework

Microsoft.Agents.AI.Foundry.HostingとAzure.Identityをインストールします。 完全なプロジェクトについては、パブリック Agent Framework hosted-toolbox サンプルを参照してください。

AddFoundryToolboxesを使用して、ホストされるエージェントに 1 つ以上のツールボックスを登録します。 この統合により、マネージド MCP のエンドポイントが解決され、要求の認証が行われ、準備プローブにツールボックスの正常性が含まれるようになります。

環境変数:

AZURE_AI_PROJECT_ENDPOINT=https://<account>.services.ai.azure.com/api/projects/<project>
AZURE_AI_MODEL_DEPLOYMENT_NAME=gpt-4o
TOOLBOX_NAME=<toolbox-name>

Program.cs (キー パターン):

using Azure.AI.Projects;
using Azure.Identity;
using Microsoft.Agents.AI;
using Microsoft.Agents.AI.Foundry.Hosting;

string projectEndpoint = Environment.GetEnvironmentVariable("AZURE_AI_PROJECT_ENDPOINT")
    ?? throw new InvalidOperationException("AZURE_AI_PROJECT_ENDPOINT is not set.");
string deploymentName = Environment.GetEnvironmentVariable(
    "AZURE_AI_MODEL_DEPLOYMENT_NAME") ?? "gpt-4o";
string toolboxName = Environment.GetEnvironmentVariable("TOOLBOX_NAME")
    ?? throw new InvalidOperationException("TOOLBOX_NAME is not set.");

var credential = new DefaultAzureCredential();
AIAgent agent = new AIProjectClient(new Uri(projectEndpoint), credential)
    .AsAIAgent(
        model: deploymentName,
        instructions: "You are a helpful assistant with access to toolbox tools.",
        name: "hosted-toolbox-agent");

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddFoundryResponses(agent);
builder.Services.AddFoundryToolboxes(credential, toolboxName);

var app = builder.Build();
app.MapFoundryResponses();
app.Run();

Microsoft Foundry Toolkit for Visual Studio Code 拡張機能を使用して、ツールボックスに既にワイヤードされているホスト型エージェント サンプルをスキャフォールディングします。

1. アクティビティ バーで Foundry Toolkit を選択します。
2. [ マイ リソース] で、[ プロジェクト名>Tools] を展開します。
3. [ ツールボックス ] タブで、使用するツールボックスを見つけて、[ スキャフォールディング コード テンプレート] を選択します。
4. コマンド パレットで、メッセージが表示されたらプロジェクト フォルダーを選択します。
5. 生成された README.md を開き、スキャフォールディングのセットアップ、ローカル実行、デプロイの手順に従います。

生成されたプロジェクトには、ホストされたエージェントのエントリ ポイント、デプロイ ファイル、および正確なセットアップ、実行、デプロイの手順を含む README.md が含まれます。

新しいサンプルを生成するのではなく、ツールボックスを既存のホステッド エージェント プロジェクトに統合する場合は、このセクションのPythonまたは.NET パターンでツールボックス MCP エンドポイントを使用します。

ツールボックス エンドポイントをエージェントに渡す

ツールボックスを作成したら、azd ai toolbox showを使用して MCP エンドポイントを取得し、そのエンドポイントを環境変数としてエージェント コードに渡します。 エージェントは起動時に変数を読み取り、それを使用してツールボックスに接続します。

1. ツールボックス エンドポイントを取得します。

   azd ai toolbox show <toolbox-name> --output json
   

   応答の endpoint フィールドは、選択したバージョンを識別します。 これを使用して、昇格の前にそのバージョンをテストします。 default_versionに従う必要があるエージェントの場合は、「ツールボックス MCP エンドポイントの取得」に示されているバージョン管理されていないコンシューマー エンドポイントを構築します。

2. 起動時にエージェントが読み取る環境変数としてエンドポイントを設定します。

   # .env (or however your runtime loads environment variables)
   TOOLBOX_ENDPOINT=https://<account>.services.ai.azure.com/api/projects/<project>/toolboxes/<toolbox-name>/mcp?api-version=v1
   

3. エージェント コードで、 TOOLBOX_ENDPOINT を読み取り、MCP クライアントで接続します。 このセクションで前述したPythonまたは.NET統合パターンを、クライアントセットアップのリファレンスとして使用し、Entra トークン (https://ai.azure.com/.default スコープ) として使用します。

from azure.ai.projects.models import MCPToolboxTool

# Set require_approval on an MCP tool
toolbox_version = project.toolboxes.create_version(
    name="my-toolbox",
    tools=[
        MCPToolboxTool(
            server_label="myserver",
            server_url="https://your-mcp-server.example.com",
            require_approval="always",  # "always" | "never"
            project_connection_id="my-connection",
        )
    ],
)

{
  "tools": [
    {
      "type": "mcp",
      "server_label": "myserver",
      "server_url": "https://your-mcp-server.example.com",
      "require_approval": "always",
      "project_connection_id": "my-connection"
    }
  ]
}

MCPToolboxTool mcpTool = new(serverLabel: "myserver")
{
  ServerUri = new Uri("https://your-mcp-server.example.com"),
  ToolCallApprovalPolicy = new McpToolCallApprovalPolicy(
    GlobalMcpToolCallApprovalPolicy.AlwaysRequireApproval),
};

const tools = [
  {
    type: "mcp",
    server_label: "myserver",
    server_url: "https://your-mcp-server.example.com",
    require_approval: "always",
    project_connection_id: "my-connection",
  },
];

Python、.NET、JavaScript、REST API、または Azure Developer CLI タブを使用して、ツールボックス定義でrequire_approvalを構成します。 この記事の Microsoft Foundry Toolkit for Visual Studio Code 拡張機能ワークフローでは、Visual Studio Codeでのツールボックスの作成と使用に重点を置いています。

resources:
  - kind: toolbox
    name: my-toolbox
    tools:
      - type: mcp
        server_label: myserver
        server_url: https://your-mcp-server.example.com
        require_approval: always
        project_connection_id: my-connection

# Create a new toolbox version
toolbox_version = project.toolboxes.create_version(
    name="my-toolbox",
    description="Updated tools v2",
    tools=[...],
)
print(f"Created version: {toolbox_version.version}")

ToolboxVersion toolboxVersion = await toolboxClient.CreateVersionAsync(
  name: "<toolbox-name>",
    tools: [tool],
    description: "Updated tools v2"
);
Console.WriteLine($"Created version: {toolboxVersion.Version}");

POST {project_endpoint}/toolboxes/<toolbox-name>/versions?api-version=v1
Authorization: Bearer {token}
Content-Type: application/json

{
  "description": "Updated tools v2",
  "tools": [...]
}

const toolboxVersion = await project.toolboxes.createVersion(
  "<toolbox-name>",
  [/* tools array */],
  { description: "Updated tools v2" },
);
console.log(`Created version: ${toolboxVersion.version}`);

Python、.NET、JavaScript、または REST API タブを使用して、新しいツールボックス バージョンを作成します。 この記事の Microsoft Foundry Toolkit for Visual Studio Code 拡張機能ワークフローでは、ツールボックスを作成し、それを使用するホスト型エージェントをスキャフォールディングすることに重点を置いています。

この操作は、Azure Developer CLI ではサポートされていません。 ツールボックスバージョンを作成するには、Python、.NET、REST API、または JavaScript タブを使用します。

# List all toolbox versions
versions = list(project.toolboxes.list_toolbox_versions(name="<toolbox-name>"))
for v in versions:
    print(f"{v.version} — created {v.created_at}")

List<ToolboxVersion> versions = await toolboxClient
    .GetToolboxVersionsAsync("<toolbox-name>")
    .ToListAsync();
Console.WriteLine($"Found {versions.Count} toolbox version(s).");
foreach (ToolboxVersion v in versions)
{
    Console.WriteLine($"  - {v.Name} ({v.Version})");
}

GET {project_endpoint}/toolboxes/<toolbox-name>/versions?api-version=v1
Authorization: Bearer {token}

const versions = project.toolboxes.listVersions("<toolbox-name>");
for await (const v of versions) {
  console.log(`${v.version} — created ${v.created_at}`);
}

Python、.NET、JavaScript、または REST API タブを使用して、ツールボックスのバージョンを一覧表示します。

# The current default version is marked with *
azd ai toolbox version list <toolbox-name>

# Get a specific toolbox version
version_obj = project.toolboxes.get_toolbox_version(
    toolbox_name="<toolbox-name>",
    version="<version_id>",
)

ToolboxVersion versionObj = await toolboxClient.GetToolboxVersionAsync(
    "<toolbox-name>",
    "<version_id>"
);
Console.WriteLine($"Retrieved toolbox: {versionObj.Name} ({versionObj.Id})");

GET {project_endpoint}/toolboxes/<toolbox-name>/versions/{version}?api-version=v1
Authorization: Bearer {token}

const versionObj = await project.toolboxes.getVersion(
  "<toolbox-name>",
  "<version_id>",
);
console.log(`Retrieved version: ${versionObj.version}`);

Python、.NET、JavaScript、または REST API タブを使用して、特定のツールボックス バージョンを取得します。

azd ai toolbox version get <toolbox-name> <version_id>

# Promote a version to default
toolbox = project.toolboxes.update(
    toolbox_name="<toolbox-name>",
    default_version="<version_id>",
)
print(f"Active version: {toolbox.default_version}")

ToolboxRecord record = await toolboxClient.UpdateToolboxAsync(
    "<toolbox-name>",
    "<version_id>"
);
Console.WriteLine($"Active version: {record.DefaultVersion}");

PATCH {project_endpoint}/toolboxes/<toolbox-name>?api-version=v1
Authorization: Bearer {token}
Content-Type: application/json

{
  "default_version": "<version_id>"
}

default_version を空にすることはできません。 新しいバージョンに置き換えます。

const toolbox = await project.toolboxes.update(
  "<toolbox-name>",
  "<version_id>",
);
console.log(`Active version: ${toolbox.default_version}`);

ツールボックスのバージョンを既定に昇格するには、Python、.NET、JavaScript、または REST API タブを使用します。

ツールボックスのバージョンは変更できません。 publishを使用して、既存のバージョンを新しい既定値にします。

# Roll back or forward to a specific version
azd ai toolbox publish <toolbox-name> <version_id> --no-prompt

publish は、CLI から default_version を変更する唯一の方法です。変更を伴う動詞 (connection add/remove、skill add/remove) は、常に新しいバージョンを作成しますが、それを昇格させません。

# Delete a toolbox version
project.toolboxes.delete_toolbox_version(
    toolbox_name="<toolbox-name>",
    version="<version_id>",
)

await toolboxClient.DeleteToolboxVersionAsync(
    "<toolbox-name>",
    "<version_id>"
);

DELETE {project_endpoint}/toolboxes/<toolbox-name>/versions/{version}?api-version=v1
Authorization: Bearer {token}

await project.toolboxes.deleteVersion(
  "<toolbox-name>",
  "<version_id>",
);

ツールボックスのバージョンを削除するには、Python、.NET、JavaScript、または REST API タブを使用します。

この操作は、Azure Developer CLI ではサポートされていません。 ツールボックスのバージョンを削除するには、Python、.NET、REST API、または JavaScript タブを使用します。

from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import WebSearchToolboxTool

endpoint = "https://<your-foundry-account>.services.ai.azure.com/api/projects/<your-project>"
project = AIProjectClient(endpoint=endpoint, credential=DefaultAzureCredential())

toolbox_version = project.toolboxes.create_version(
    name="my-toolbox",
    description="Toolbox with guardrail",
    tools=[WebSearchToolboxTool()],
    policies={
        "rai_config": {
            "rai_policy_name": "/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.CognitiveServices/accounts/<account-name>/raiPolicies/<policy-name>"
        }
    },
)
print(f"Created version: {toolbox_version.version}")

POST {endpoint}/toolboxes/{toolbox_name}/versions?api-version=v1
Authorization: Bearer {token}
Content-Type: application/json

{
  "description": "Toolbox with guardrail",
  "tools": [{ "type": "web_search" }],
  "policies": {
    "rai_config": {
      "rai_policy_name": "/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.CognitiveServices/accounts/<account-name>/raiPolicies/<policy-name>"
    }
  }
}

#pragma warning disable AAIP001
using Azure.AI.Projects;
using Azure.AI.Projects.Agents;
using Azure.Identity;

var projectEndpoint = Environment.GetEnvironmentVariable("FOUNDRY_PROJECT_ENDPOINT");
DefaultAzureCredential credential = new();
AIProjectClient projectClient = new(endpoint: new Uri(projectEndpoint), tokenProvider: credential);
AgentToolboxes toolboxClient = projectClient.AgentAdministrationClient.GetAgentToolboxes();

var toolboxVersion = toolboxClient.CreateVersion(
  name: "my-toolbox",
    description: "Toolbox with guardrail",
    tools: [new WebSearchToolboxTool()],
    policies: new ToolboxPolicies
    {
        RaiConfig = new RaiConfig { RaiPolicyName = "/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.CognitiveServices/accounts/<account-name>/raiPolicies/<policy-name>" }
    });
Console.WriteLine($"Created version: {toolboxVersion.Version}");

const toolboxVersion = await project.toolboxes.createVersion(
  "my-toolbox",
  [{ type: "web_search" }],
  {
    description: "Toolbox with guardrail",
    policies: {
      rai_config: {
        rai_policy_name: "/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.CognitiveServices/accounts/<account-name>/raiPolicies/<policy-name>",
      },
    },
  },
);
console.log(`Created version: ${toolboxVersion.version}`);

name: my-toolbox
description: Toolbox with guardrail
policies:
  rai_config:
    rai_policy_name: /subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.CognitiveServices/accounts/<account-name>/raiPolicies/<policy-name>
tools:
  - type: web_search

VS Code 拡張機能では、Guardrail の構成はまだ使用できません。 REST API、SDK、または Azure Developer CLI を使用してガードレールを構成します。

POST {endpoint}/toolboxes/{toolbox_name}/versions?api-version=v1
Authorization: Bearer {token}
Content-Type: application/json
Accept: application/json
Foundry-Features: Skills=V1Preview

{
  "description": "Toolbox with a skill reference",
  "tools": [],
  "skills": [
    {
      "type": "skill_reference",
      "name": "greeting"
    }
  ]
}

特定のバージョンをピン留めするには:

{
  "skills": [
    {
      "type": "skill_reference",
      "name": "greeting",
      "version": "v1"
    }
  ]
}

from azure.ai.projects.models import ToolboxSkillReference

toolbox_version = project.toolboxes.create_version(
    name="my-toolbox",
    description="Toolbox with a skill reference",
    tools=[],
    skills=[
        ToolboxSkillReference(name="greeting"),              # use default version
        # ToolboxSkillReference(name="greeting", version="1"),  # pin to version 1
    ],
)
print(f"Created toolbox version: {toolbox_version.id}")

#pragma warning disable AAIP001
// Reuse the AgentToolboxes client (toolboxClient) from Step 1.
ToolboxSkillReference skillRef = new("greeting");
// To pin a version: new ToolboxSkillReference("greeting") { Version = "1" }

ToolboxVersion toolboxVersion = toolboxClient.CreateVersion(
    name: "my-toolbox",
    tools: [],
    skills: [skillRef],
    description: "Toolbox with a skill reference"
);
Console.WriteLine($"Created toolbox version: {toolboxVersion.Id}");

const toolboxVersion = await project.toolboxes.createVersion(
  "my-toolbox",
  [],
  {
    description: "Toolbox with a skill reference",
    skills: [
      { type: "skill_reference", name: "greeting" },
      // { type: "skill_reference", name: "greeting", version: "v1" },  // pin to v1
    ],
  },
);
console.log(`Created toolbox version: ${toolboxVersion.id}`);

Azure Developer CLI では、skills: YAML の最上位azd ai toolbox create --from-file ブロックとして宣言型と、azd ai toolbox skill add/list/remove 動詞を使用した命令型の 2 つの場所でスキル参照がサポートされています。 各参照は、 name (必須) と省略可能な version (文字列) を受け取ります。 version を省略して、スキルの default_version に従う: バージョン文字列を固定して、ツールボックスを不変のスナップショットにロックします。

ツールボックスの作成時にスキルを宣言する

# my-toolbox.yaml
description: Toolbox with skill references
connections:
  - name: my-gh-conn
skills:
  - name: greeting              # follows the skill's default version
  - name: review-checklist
    version: "2"               # pin to skill version 2

azd ai toolbox create my-toolbox --from-file ./my-toolbox.yaml --no-prompt

既存のツールボックスでスキルを追加、一覧表示、削除する

# Add a skill (follows default version)
azd ai toolbox skill add my-toolbox greeting

# Add a skill pinned to a specific version
azd ai toolbox skill add my-toolbox review-checklist@2

# Add multiple skills from a file (same shape as the create YAML's skills block)
azd ai toolbox skill add my-toolbox --from-file ./skills.yaml

# List skill references on the current default version
azd ai toolbox skill list my-toolbox --output table

# Remove a skill (--force skips the confirmation prompt; multiple names allowed)
azd ai toolbox skill remove my-toolbox greeting --force

skill list には、既定のバージョンのみが表示されます。 ピン留めされたスキルは自分のバージョンを表示します。ピン留めされていないスキルは (default)を示します。 保留中のバージョンのスキルを検査するには、 azd ai toolbox show <toolbox> --version <n> --output json を実行し、 skills 配列を読み取る必要があります。

スキル名は ^[a-z0-9]([a-z0-9\-]*[a-z0-9])?$ (小文字、数字、ハイフン、最大 64 文字、先頭または末尾のハイフンなし) と一致する必要があります。 @の末尾の<name>@<version> (空のバージョン) は拒否されます。

現在、スキル参照は VS Code 拡張機能を通じて構成できません。 REST API または SDK を使用してスキルを構成します。

スキル検出を検証する

ツールボックス バージョンにスキルをアタッチした後、MCP Python SDK を使用して、ツールボックス MCP エンドポイントを介してスキルを検出できることを確認します。

import asyncio
from azure.identity import DefaultAzureCredential
from mcp import ClientSession
from mcp.client.streamable_http import streamablehttp_client

async def list_skills():
    credential = DefaultAzureCredential()
    token = credential.get_token("https://ai.azure.com/.default").token
    toolbox_url = "{endpoint}/toolboxes/my-toolbox/mcp?api-version=v1"
    headers = {
        "Authorization": f"Bearer {token}",
    }
    async with streamablehttp_client(toolbox_url, headers=headers) as (read, write, _):
        async with ClientSession(read, write) as session:
            await session.initialize()
            resources = await session.list_resources()
            for resource in resources.resources:
                print(f"Skill: {resource.uri} - {resource.name}")

asyncio.run(list_skills())

スキルは、skill://{name} 形式の URI を持つ MCP リソースとして表示されます。

エージェントのスキルを利用する (Microsoft Agent Framework, .NET)

.NETでは、Microsoft Agent Framework SDK の AgentSkillsProviderBuilder().UseMcpSkills(mcpClient) を使用して、ツールボックス エンドポイントから MCP ベースのスキルを検出し、エージェントに AIContextProviders として挿入します。 その後、エージェントは、モデルが関連すると判断したときに、実行時に各スキルの命令を読み込みます。 次の Program.cs は、Responses ホスティング レイヤー (AddFoundryResponses と MapFoundryResponses) を使用してエージェントをホストします。

using System.Net.Http.Headers;
using Azure.AI.Projects;
using Azure.Core;
using Azure.Identity;
using DotNetEnv;
using Microsoft.Agents.AI;
using Microsoft.Agents.AI.Foundry.Hosting;
using Microsoft.Extensions.AI;
using ModelContextProtocol.Client;

// Load .env file if present (for local development).
Env.TraversePath().Load();

string projectEndpoint = Environment.GetEnvironmentVariable("FOUNDRY_PROJECT_ENDPOINT")
    ?? throw new InvalidOperationException("FOUNDRY_PROJECT_ENDPOINT environment variable is not set.");

string deployment = Environment.GetEnvironmentVariable("AZURE_AI_MODEL_DEPLOYMENT_NAME")
    ?? throw new InvalidOperationException("AZURE_AI_MODEL_DEPLOYMENT_NAME environment variable is not set.");

string toolboxName = Environment.GetEnvironmentVariable("TOOLBOX_NAME")
    ?? throw new InvalidOperationException("TOOLBOX_NAME environment variable is not set.");

// Build the Foundry Toolbox MCP URL from the project endpoint and toolbox name.
string toolboxMcpServerUrl = $"{projectEndpoint.TrimEnd('/')}/toolboxes/{toolboxName}/mcp?api-version=v1";

TokenCredential credential = new DefaultAzureCredential();

// HttpClient that attaches a fresh Foundry bearer token to every request.
// CheckCertificateRevocationList = true satisfies CA5399.
using var httpClient = new HttpClient(
    new BearerTokenHandler(credential, "https://ai.azure.com/.default")
    {
        CheckCertificateRevocationList = true,
    });

Console.WriteLine($"Connecting to Foundry Toolbox '{toolboxName}' MCP server...");

// Connect to the Foundry Toolbox MCP endpoint.
await using var mcpClient = await McpClient.CreateAsync(
    new HttpClientTransport(
        new HttpClientTransportOptions
        {
            Endpoint = new Uri(toolboxMcpServerUrl),
            Name = toolboxName,
            TransportMode = HttpTransportMode.StreamableHttp,
        },
        httpClient));

// AgentSkillsProvider implements progressive disclosure over the MCP-discovered skills:
// names and descriptions are advertised in the system prompt, and the full skill body
// (and any supplementary resources) is loaded on demand when the model decides it is
// relevant.
var skillsProvider = new AgentSkillsProviderBuilder()
    .UseMcpSkills(mcpClient)
    .Build();

AIAgent agent = new AIProjectClient(new Uri(projectEndpoint), credential)
    .AsAIAgent(new ChatClientAgentOptions
    {
        Name = "foundry-toolbox-mcp-skills",
        Description = "Agent that discovers MCP-based skills from a Foundry Toolbox and exposes them via AgentSkillsProvider.",
        ChatOptions = new ChatOptions
        {
            ModelId = deployment,
            Instructions = "You are a helpful assistant.",
        },
        AIContextProviders = [skillsProvider],
    });

var builder = AgentHost.CreateBuilder(args);
builder.Services.AddFoundryResponses(agent);
builder.RegisterProtocol("responses", endpoints => endpoints.MapFoundryResponses());

var app = builder.Build();
app.Run();

// HttpClientHandler that attaches a fresh Foundry bearer token to every outgoing request.
internal sealed class BearerTokenHandler(TokenCredential credential, string scope) : HttpClientHandler
{
    private readonly TokenRequestContext _tokenContext = new([scope]);

    protected override async Task<HttpResponseMessage> SendAsync(HttpRequestMessage request, CancellationToken cancellationToken)
    {
        AccessToken token = await credential.GetTokenAsync(this._tokenContext, cancellationToken).ConfigureAwait(false);
        request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", token.Token);
        return await base.SendAsync(request, cancellationToken).ConfigureAwait(false);
    }
}

プロジェクト ファイルや配置手順を含む完全なサンプルについては、 ツールボックスのスキルのサンプルを参照してください。