Foundry の意図ベースのツールボックスをキュレーションする (プレビュー)

from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import MCPTool, WebSearchTool

# 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.beta.toolboxes.create_toolbox_version(
    toolbox_name="my-toolbox",
    description="Toolbox with web search and an MCP server",
    tools=[
        WebSearchTool(),
        MCPTool(
            server_label="myserver",
            server_url="https://your-mcp-server.example.com",
            require_approval="never",
            project_connection_id="my-key-auth-connection",
        ),
    ],
)
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();

ProjectsAgentTool webTool = ProjectsAgentTool.AsProjectTool(
    ResponseTool.CreateWebSearchTool());

ProjectsAgentTool mcpTool = ProjectsAgentTool.AsProjectTool(ResponseTool.CreateMcpTool(
    serverLabel: "myserver",
    serverUri: new Uri("https://your-mcp-server.example.com"),
    toolCallApprovalPolicy: new McpToolCallApprovalPolicy(
        GlobalMcpToolCallApprovalPolicy.NeverRequireApproval
    )
));

ToolboxVersion toolboxVersion = await toolboxClient.CreateToolboxVersionAsync(
    toolboxName: "my-toolbox",
    tools: [webTool, mcpTool],
    description: "Toolbox with web search and an MCP server"
);
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 and an MCP server",
  "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"
    }
  ]
}

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.beta.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",
    },
  ],
  {
    description: "Toolbox with web search and an MCP server",
  },
);
console.log(`Created toolbox: ${toolboxVersion.name}, version: ${toolboxVersion.version}`);

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

1. アクティビティ バーで Foundry Toolkit を選択します。
2. [ マイ リソース] で、[ プロジェクト名>Tools] を展開します。
3. [+ ツールボックスの追加] アイコンを選択します。
4. [ カスタム ツールボックスのビルド ] タブで、ツールボックスの名前と説明を入力し、目的のツールを追加して、[ 発行] を選択します。

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

ツールボックス名、説明、およびツールのフィールドに加えて[発行]<>

azdを使用すると、SDK を呼び出す代わりに、agent.yaml ファイルでツールボックス リソースを宣言できます。 resources セクションでツールを定義し、azd ai agent initを使用してデプロイします。 各ツールの種類 agent.yaml 例については、「 ツールの構成」を参照してください。 完全なデプロイ ワークフローについては、「 azd を使用したデプロイ」を参照してください。

# 1. Create a manifest directory with your agent.yaml + source files
mkdir my-agent/manifest
# Copy agent.yaml, main.py, Dockerfile, requirements.txt into my-agent/manifest/

# 2. Initialize the azd project (note: -m is REQUIRED)
cd my-agent
$PROJECT_ID = "/subscriptions/<sub>/resourceGroups/<rg>/providers/Microsoft.CognitiveServices/accounts/<account>/projects/<project>"
azd ai agent init -m https://github.com/microsoft/hosted-agents-vnext-private-preview/main/samples/python/toolbox/azd/agent.yaml --project-id $PROJECT_ID -e my-env
# Or equivalently: azd ai agent init -m manifest/ --project-id $PROJECT_ID -e my-env
# ↑ If your agent.yaml declares {{ param }} secrets (e.g., github_pat), you will be prompted to enter
#   them interactively HERE — before init completes. This is the only safe time to supply credentials.
# NOTE: Do NOT use --no-prompt here — it skips the prompt and leaves {{ param }} credentials empty (see Troubleshooting: Credentials Empty with --no-prompt)

# 3. CRITICAL post-init fixes (see "Post-Init Checklist" below)
azd env set enableHostedAgentVNext "true" -e my-env
azd env set AZURE_AI_MODEL_DEPLOYMENT_NAME "gpt-4o" -e my-env  # must match the deployment name in azure.yaml

# 4. Provision infrastructure (creates connections via Bicep)
azd provision -e my-env

# 5. Deploy agent (creates toolboxes, container image, agent version)
azd deploy -e my-env

# 6. Invoke the agent (MUST run from the scaffolded project directory)
azd ai agent invoke --new-session "tell me about the latest news in Microsoft Foundry" --timeout 120

Agent.yaml:

kind: hosted
name: toolbox-azd-test
description: LangGraph agent wired for toolbox MCP.
metadata:
  tags:
    - AI Agent Hosting
    - LangGraph

# template: contains the ContainerAgent definition (kind: hosted).
# These fields are used to generate src/<agent>/agent.yaml during init.
template:
  kind: hosted
  protocols:
    - protocol: responses
      version: 1.0.0
  environment_variables:
    # FOUNDRY_PROJECT_ENDPOINT and FOUNDRY_AGENT_TOOLBOX_* are injected
    # automatically by the platform at runtime — do NOT declare them here.
    - name: AZURE_OPENAI_ENDPOINT
      value: ${AZURE_OPENAI_ENDPOINT}
    - name: AZURE_AI_MODEL_DEPLOYMENT_NAME
      value: ${AZURE_AI_MODEL_DEPLOYMENT_NAME=gpt-4o}
    - name: TOOLBOX_NAME
      value: ${TOOLBOX_NAME=agent-tools}

# parameters: secret values prompted at init time (or set via azd env).
# azd uppercases the param name to find the env var: github_pat → GITHUB_PAT.
parameters:
  github_pat:
    secret: true
    description: GitHub Personal Access Token (classic ghp_... or fine-grained github_pat_...)

# resources: connections and toolboxes scaffolded into azure.yaml by azd ai agent init.
resources:
  - kind: connection
    name: github-mcp-conn
    target: https://api.githubcopilot.com/mcp
    category: remoteTool
    credentials:
      type: CustomKeys
      keys:
        Authorization: "Bearer {{ github_pat }}"

  - kind: toolbox
    name: agent-tools
    tools:
      - type: web_search
      - type: mcp
        server_label: github
        server_url: https://api.githubcopilot.com/mcp
        project_connection_id: github-mcp-conn

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}",
    "Foundry-Features": "Toolboxes=V1Preview",
}

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
Foundry-Features: Toolboxes=V1Preview

{"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
Foundry-Features: Toolboxes=V1Preview

{"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
Foundry-Features: Toolboxes=V1Preview

{"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
Foundry-Features: Toolboxes=V1Preview

{"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}`,
        "Foundry-Features": "Toolboxes=V1Preview",
      },
    },
  },
);

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();

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

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

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

LangGraph

.env ファイル:

FOUNDRY_PROJECT_ENDPOINT=https://<account>.services.ai.azure.com/api/projects/<project>
FOUNDRY_AGENT_TOOLBOX_ENDPOINT=https://<account>.services.ai.azure.com/api/projects/<project>/toolboxes/<toolbox-name>/versions/<version>/mcp?api-version=v1
TOOLBOX_NAME=agent-tools
FOUNDRY_AGENT_TOOLBOX_FEATURES=Toolboxes=V1Preview
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

Agent Framework SDK の MCPStreamableHTTPTool を使用して、ツールボックス MCP エンドポイントに直接接続します。

.env ファイル:

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

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

# Auth: wrap token provider in an httpx.Auth subclass
credential = DefaultAzureCredential()
token_provider = get_bearer_token_provider(credential, "https://ai.azure.com/.default")
http_client = httpx.AsyncClient(
    auth=_ToolboxAuth(token_provider),
    headers={"Foundry-Features": "Toolboxes=V1Preview"},
    timeout=120.0,
)

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

# Connect MCPStreamableHTTPTool to the toolbox endpoint
mcp_tool = MCPStreamableHTTPTool(
    name="toolbox",
    url=TOOLBOX_ENDPOINT,
    http_client=http_client,
    load_prompts=False,
)

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

完全な実装については、 完全なサンプル を参照してください。

Copilot SDK

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

.env ファイル:

GITHUB_TOKEN=<your-github-token>
FOUNDRY_AGENT_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

カスタム ResponsesServerと共に Agent Framework SDK のToolboxMcpClientを使用して、MCP エンドポイントを介してツールボックス ツールを検出して呼び出します。

環境変数:

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

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

using Azure.AI.AgentServer.Responses;
using Azure.AI.AgentServer.Responses.Models;
using Azure.AI.OpenAI;
using Azure.Identity;
using Microsoft.Extensions.DependencyInjection;
using OpenAI.Chat;

// Azure OpenAI endpoint and model deployment
var openAiEndpoint = "https://<account>.services.ai.azure.com";
var deployment = "gpt-4o";  // supports all toolbox tool types

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

// Azure OpenAI client
var credential = new DefaultAzureCredential();
var openAIClient = new AzureOpenAIClient(new Uri(openAiEndpoint), credential);
var chatClient = openAIClient.GetChatClient(deployment);

// Toolbox MCP client — discovers tools via tools/list, calls them via tools/call
var toolboxClient = new ToolboxMcpClient(toolboxEndpoint, credential);

ResponsesServer.Run<ToolboxHandler>(configure: builder =>
{
    builder.Services.AddSingleton(new AgentConfig(chatClient, toolboxClient));
});

ToolboxMcpClient は、MCP エンドポイントへの直接 JSON-RPC 呼び出しをラップします。 ToolboxHandler は、標準のツール呼び出しループを使用して LLM ツールの呼び出しを MCP クライアントに接続します。 両方のクラスの完全な実装については、 完全なサンプルを参照してください。

Foundry Toolkit を使用して、ツールボックスに既にワイヤードされているホストされたエージェント サンプルをスキャフォールディングします。

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

生成されたプロジェクトには、ホストされたエージェント エントリ ポイント、デプロイ ファイル、および正確なセットアップ、実行、およびデプロイの手順を含む README.md が含まれます。 スキャフォールディングされたエージェントが、Foundry-Features: Toolboxes=V1Preview ヘッダーを処理します。

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

azd を使用したデプロイ

Azure Developer CLI (azd) を使用して、ツールボックス リソースを agent.yaml ファイルに直接宣言し、1 つのコマンドでエージェントをデプロイします。 この方法を使用すると、SDK または REST を使用してツールボックスを個別に作成する必要はありません。 azd では、ツールボックス、接続、モデルのデプロイが一緒にプロビジョニングされます。

フォルダー構造:

my-agent/
├── agent.yaml          # Agent, toolbox, and connection declarations
├── main.py             # LangGraph agent
├── requirements.txt    # All dependencies (Azure SDK + PyPI packages)
├── Dockerfile          # Container build

agent.yaml (Web Search + GitHub MCP の例):

name: my-toolbox-agent
description: LangGraph agent with Azure AI Foundry toolbox MCP.
metadata:
  tags:
    - AI Agent Hosting
    - LangGraph
template:
  name: my-toolbox-agent
  kind: hosted
  protocols:
    - protocol: responses
      version: 1.0.0
  environment_variables:
    # FOUNDRY_PROJECT_ENDPOINT and FOUNDRY_AGENT_TOOLBOX_* are injected
    # automatically by the platform at runtime — do NOT declare them here.
    - name: AZURE_AI_MODEL_DEPLOYMENT_NAME
      value: ${AZURE_AI_MODEL_DEPLOYMENT_NAME=gpt-4o}
    - name: TOOLBOX_NAME
      value: ${TOOLBOX_NAME=agent-tools}
parameters:
  github_pat:
    secret: true
    description: GitHub Personal Access Token for MCP connection
resources:
  - kind: connection
    name: github-mcp-conn
    target: https://api.githubcopilot.com/mcp
    category: RemoteTool
    authType: CustomKeys
    credentials:
      keys:
        Authorization: "Bearer {{ github_pat }}"
  - kind: toolbox
    name: agent-tools
    description: Web search and GitHub MCP tools
    tools:
      - type: web_search
      - type: mcp
        server_label: github
        server_url: https://api.githubcopilot.com/mcp
        project_connection_id: github-mcp-conn

main.py は、前に示したのと同じ LangGraph パターンに従います。 azdを使用すると、FOUNDRY_AGENT_TOOLBOX_ENDPOINTとTOOLBOX_{toolbox_name}_MCP_ENDPOINTが自動的に挿入されます。コードに追加のエンドポイント構成は必要ありません。

デプロイ:

# 1. Place agent.yaml and source files in a manifest directory
mkdir my-agent/manifest
# Copy agent.yaml, main.py, Dockerfile, requirements.txt into my-agent/manifest/

# 2. Initialize the azd project (-m is required)
cd my-agent
PROJECT_ID="/subscriptions/<sub>/resourceGroups/<rg>/providers/Microsoft.CognitiveServices/accounts/<account>/projects/<project>"
azd ai agent init -m manifest/ --project-id $PROJECT_ID -e my-env
# If agent.yaml declares {{ param }} secrets (for example, github_pat), you are prompted
# to enter them interactively here. Do NOT use --no-prompt — it leaves credentials empty.

# 3. Set required environment variables
azd env set enableHostedAgentVNext "true" -e my-env
azd env set AZURE_AI_MODEL_DEPLOYMENT_NAME "gpt-4o" -e my-env

# 4. Provision infrastructure (creates connections via Bicep)
azd provision -e my-env

# 5. Deploy agent (creates toolboxes, container image, agent version)
azd deploy -e my-env

# 6. Invoke the agent
azd ai agent invoke --new-session "Hello, what tools do you have?" --timeout 120

from azure.ai.projects.models import MCPTool

# Set require_approval on an MCP tool
toolbox_version = project.beta.toolboxes.create_toolbox_version(
    toolbox_name="my-toolbox",
    tools=[
        MCPTool(
            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"
    }
  ]
}

ProjectsAgentTool mcpTool = ProjectsAgentTool.AsProjectTool(ResponseTool.CreateMcpTool(
    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、または azd タブを使用して、ツールボックス定義で require_approval を構成します。 この記事の Foundry Toolkit ワークフローでは、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.beta.toolboxes.create_toolbox_version(
    toolbox_name="my-toolbox",
    description="Updated tools v2",
    tools=[...],
)
print(f"Created version: {toolbox_version.version}")

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

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

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

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

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

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

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

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

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

const versions = project.beta.toolboxes.listVersions("my-toolbox");
for await (const v of versions) {
  console.log(`${v.version} — created ${v.createdAt}`);
}

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

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

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

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

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

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

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

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

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

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

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

{
  "default_version": "<version_id>"
}

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

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

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

この操作は azd ではサポートされていません。 バージョンを既定に昇格するには、Python、.NET、REST API、または JavaScript タブを使用します。

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

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

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

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

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

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

キーベースの認証:

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

認証なし (パブリック MCP サーバー):

{
  "description": "Public MCP server",
  "tools": [
    {
      "type": "mcp",
      "server_label": "myserver",
      "server_url": "https://your-mcp-server.example.com"
    }
  ]
}

OAuth または ID ベースの認証:

OAuth (マネージド コネクタ、カスタム アプリ登録)、エージェント ID、またはユーザー Entra トークン認証の場合は、まず Foundry プロジェクトに適切な接続を作成してから、 project_connection_idで参照します。

{
  "description": "MCP server with OAuth/identity auth",
  "tools": [
    {
      "type": "mcp",
      "server_label": "myserver",
      "server_url": "https://your-mcp-server.example.com",
      "project_connection_id": "<OAUTH_OR_IDENTITY_CONNECTION_NAME>"
    }
  ]
}

接続の authType によって認証フローが決まります。 MCP でサポートされている接続認証の種類には、 CustomKeys、 OAuth2 (マネージドまたはカスタム)、 AgenticIdentity、および UserEntraTokenが含まれます。 各認証の種類の接続構成例については、 azd タブ を参照してください。

from azure.ai.projects.models import MCPTool

tools = [
    MCPTool(
        server_label="myserver",
        server_url="https://your-mcp-server.example.com",
        project_connection_id="my-mcp-connection",
    )
]

ProjectsAgentTool tool = ProjectsAgentTool.AsProjectTool(ResponseTool.CreateMcpTool(
    serverLabel: "myserver",
    serverUri: new Uri("https://your-mcp-server.example.com")
));

ToolboxVersion toolboxVersion = await toolboxClient.CreateToolboxVersionAsync(
    toolboxName: "my-toolbox",
    tools: [tool],
    description: "my-mcp-toolbox"
);

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

認証なし:

resources:
  - kind: toolbox
    name: mcp-tools
    description: Public MCP server tools
    tools:
      - type: mcp
        server_label: myserver
        server_url: https://your-mcp-server.example.com

キーベースの認証:

parameters:
  mcp_api_key:
    secret: true
    description: API key for the MCP server
resources:
  - kind: connection
    name: mcp-conn
    target: https://your-mcp-server.example.com
    category: RemoteTool
    authType: CustomKeys
    credentials:
      keys:
        Authorization: "Bearer {{ mcp_api_key }}"
  - kind: toolbox
    name: mcp-tools
    description: MCP server tools with key auth
    tools:
      - type: mcp
        server_label: myserver
        server_url: https://your-mcp-server.example.com
        project_connection_id: mcp-conn

OAuth - マネージド コネクタ:

Foundry のマネージド OAuth フローをサポートする MCP サーバーには、このパターンを使用します。 connectorName値は、Foundry Tools カタログで使用できるマネージド コネクタと一致する必要があります。

resources:
  - kind: connection
    name: github-oauth-conn
    category: RemoteTool
    authType: OAuth2
    target: https://api.githubcopilot.com/mcp
    connectorName: foundrygithubmcp
  - kind: toolbox
    name: oauth-tools
    description: GitHub OAuth MCP toolbox
    tools:
      - type: mcp
        server_label: github
        project_connection_id: github-oauth-conn

OAuth - カスタム アプリの登録:

このパターンは、MCP サーバー用に独自の OAuth アプリ登録を行う場合に使用します。

parameters:
  oauth_client_id:
    secret: true
    description: OAuth client ID
  oauth_client_secret:
    secret: true
    description: OAuth client secret
resources:
  - kind: connection
    name: mcp-oauth-custom-conn
    category: RemoteTool
    authType: OAuth2
    target: https://your-mcp-server.example.com
    authorizationUrl: https://auth.example.com/authorize
    tokenUrl: https://auth.example.com/token
    refreshUrl: https://auth.example.com/token
    scopes: []
    credentials:
      clientID: "{{ oauth_client_id }}"
      clientSecret: "{{ oauth_client_secret }}"
  - kind: toolbox
    name: oauth-custom-tools
    description: MCP toolbox with custom OAuth
    tools:
      - type: mcp
        server_label: myserver
        project_connection_id: mcp-oauth-custom-conn

エージェント ID (Entra ID):

このパターンは、Microsoft Entra ID認証をサポートする MCP サーバーに使用します。 Foundry エージェント ID は、ターゲット リソースに対して認証を行います。

resources:
  - kind: connection
    name: language-mcp
    category: RemoteTool
    authType: AgenticIdentity
    audience: <entra-audience>
    target: https://<resource>.cognitiveservices.azure.com/language/mcp?api-version=2025-11-15-preview
  - kind: toolbox
    name: agent-identity-tools
    description: MCP toolbox with agent identity auth
    tools:
      - type: mcp
        server_label: language
        project_connection_id: language-mcp

ユーザー Entra トークン (1P OBO):

このパターンは、オンビーハーフ・オブ (OBO) フローを介してユーザー ID を必要とする MCP サーバーに使用します。 Foundry は、ユーザーの Entra トークンを MCP サーバーにプロキシします。

resources:
  - kind: connection
    name: workiq-mail-conn
    category: RemoteTool
    authType: UserEntraToken
    audience: <entra-app-id>
    target: https://agent365.svc.cloud.microsoft/agents/servers/mcp_MailTools
  - kind: toolbox
    name: workiq-tools
    description: MCP toolbox with user Entra token auth
    tools:
      - type: mcp
        server_label: workiq
        project_connection_id: workiq-mail-conn

{
  "description": "Built-in web search",
  "tools": [
    {
      "type": "web_search",
      "name": "<OPTIONAL_TOOL_NAME>",
      "description": "<Optional description for the model>"
    }
  ]
}

Bing カスタム検索コネクションによるグラウンディングの場合:

{
  "description": "Custom Bing Search instance",
  "tools": [
    {
      "type": "web_search",
      "name": "<OPTIONAL_TOOL_NAME>",
      "description": "<Optional description for the model>",
      "web_search": {
        "custom_search_configuration": {
          "project_connection_id": "<BING_CONNECTION_NAME>",
          "instance_name": "<BING_INSTANCE_NAME>"
        }
      }
    }
  ]
}

from azure.ai.projects.models import WebSearchTool

tools = [
    WebSearchTool()
]

ProjectsAgentTool tool = ProjectsAgentTool.AsProjectTool(
    ResponseTool.CreateWebSearchTool()
);

ToolboxVersion toolboxVersion = await toolboxClient.CreateToolboxVersionAsync(
    toolboxName: "my-toolbox",
    tools: [tool],
    description: "Built-in web search"
);

const tools = [
  {
    type: "web_search",
    name: "<OPTIONAL_TOOL_NAME>",
    description: "<Optional description for the model>",
  },
];

resources:
  - kind: toolbox
    name: websearch-tools
    description: Web search toolbox
    tools:
      - type: web_search

Bing Custom Search を使用したグラウンディングの場合:

parameters:
  bing_api_key:
    secret: true
    description: Bing API key
resources:
  - kind: connection
    name: bing-custom-conn
    category: GroundingWithCustomSearch
    authType: ApiKey
    target: ""
    credentials:
      key: "{{ bing_api_key }}"
    metadata:
      ResourceId: /subscriptions/<sub>/resourceGroups/<rg>/providers/Microsoft.Bing/accounts/<bing-account>
      type: bing_custom_search
  - kind: toolbox
    name: bing-custom-tools
    description: Bing Custom Search toolbox
    tools:
      - type: bing_custom_search
        custom_search_configuration:
          instance_name: your-bing-custom-instance
        project_connection_id: bing-custom-conn

{
  "description": "Azure AI Search over my data",
  "tools": [
    {
      "type": "azure_ai_search",
      "name": "<OPTIONAL_TOOL_NAME>",
      "description": "<Optional description for the model>",
      "azure_ai_search": {
        "indexes": [
          {
            "index_name": "<INDEX_NAME>",
            "project_connection_id": "<CONNECTION_NAME>"
          }
        ]
      }
    }
  ]
}

from azure.ai.projects.models import AzureAISearchTool

tools = [
    AzureAISearchTool(
        index_name="<INDEX_NAME>",
        project_connection_id="<CONNECTION_NAME>",
    )
]

ProjectsAgentTool tool = new AzureAISearchTool(
    new AzureAISearchToolOptions(
        indexes: [
            new AzureAISearchIndexResource(
                indexName: "<INDEX_NAME>",
                projectConnectionId: "<CONNECTION_NAME>"
            )
        ]
    )
);

ToolboxVersion toolboxVersion = await toolboxClient.CreateToolboxVersionAsync(
    toolboxName: "my-toolbox",
    tools: [tool],
    description: "Azure AI Search over my data"
);

const tools = [
  {
    type: "azure_ai_search",
    name: "<OPTIONAL_TOOL_NAME>",
    description: "<Optional description for the model>",
    azure_ai_search: {
      indexes: [
        {
          index_name: "<INDEX_NAME>",
          project_connection_id: "<CONNECTION_NAME>",
        },
      ],
    },
  },
];

parameters:
  ai_search_key:
    secret: true
    description: Azure AI Search admin key
resources:
  - kind: connection
    name: aisearch-conn
    category: CognitiveSearch
    authType: ApiKey
    target: https://your-search-service.search.windows.net/
    credentials:
      key: "{{ ai_search_key }}"
  - kind: toolbox
    name: search-tools
    description: Azure AI Search toolbox
    tools:
      - type: azure_ai_search
        index_name: your-index-name
        project_connection_id: aisearch-conn

{
  "description": "Code interpreter for data analysis",
  "tools": [
    {
      "type": "code_interpreter",
      "name": "<OPTIONAL_TOOL_NAME>",
      "description": "<Optional description for the model>",
      "container": {
            "type": "auto",
            "file_ids": ["<FILE_ID>"]
        }
    }
  ]
}

from azure.ai.projects.models import CodeInterpreterTool

tools = [
    CodeInterpreterTool()
]

ProjectsAgentTool tool = ProjectsAgentTool.AsProjectTool(
    ResponseTool.CreateCodeInterpreterTool(
        new CodeInterpreterToolContainer()
    )
);

ToolboxVersion toolboxVersion = await toolboxClient.CreateToolboxVersionAsync(
    toolboxName: "my-toolbox",
    tools: [tool],
    description: "Code interpreter for data analysis"
);

const tools = [
  {
    type: "code_interpreter",
    name: "<OPTIONAL_TOOL_NAME>",
    description: "<Optional description for the model>",
    container: {
      type: "auto",
      file_ids: ["<FILE_ID>"],
    },
  },
];

resources:
  - kind: toolbox
    name: codeinterp-tools
    description: Code interpreter toolbox
    tools:
      - type: code_interpreter

{
  "description": "Search over uploaded documents",
  "tools": [
    {
      "type": "file_search",
      "name": "<OPTIONAL_TOOL_NAME>",
      "description": "<Optional description for the model>",
      "file_search": {
        "vector_store_ids": ["<VECTOR_STORE_ID>"]
      }
    }
  ]
}

from azure.ai.projects.models import FileSearchTool

tools = [
    FileSearchTool(
        vector_store_ids=["<VECTOR_STORE_ID>"]
    )
]

ProjectsAgentTool tool = ProjectsAgentTool.AsProjectTool(
    ResponseTool.CreateFileSearchTool(
        vectorStoreIds: ["<VECTOR_STORE_ID>"]
    )
);

ToolboxVersion toolboxVersion = await toolboxClient.CreateToolboxVersionAsync(
    toolboxName: "my-toolbox",
    tools: [tool],
    description: "Search over uploaded documents"
);

const tools = [
  {
    type: "file_search",
    name: "<OPTIONAL_TOOL_NAME>",
    description: "<Optional description for the model>",
    file_search: {
      vector_store_ids: ["<VECTOR_STORE_ID>"],
    },
  },
];

resources:
  - kind: toolbox
    name: filesearch-tools
    description: File search toolbox
    tools:
      - type: file_search
        vector_store_ids:
          - ${FILE_SEARCH_VECTOR_STORE_ID}

デプロイする前にベクター ストア ID を設定します。

azd env set FILE_SEARCH_VECTOR_STORE_ID "vs_xxxxxxxxxxxx"

匿名認証:

{
  "description": "REST API via OpenAPI spec",
  "tools": [
    {
      "type": "openapi",
      "openapi": {
        "name": "my-api",
        "spec": { "<paste OpenAPI spec object here>" },
        "auth": {
          "type": "anonymous"
        }
      }
    }
  ]
}

Project接続認証:

このパターンは、API で Foundry プロジェクト接続に格納されているキーまたはトークンが必要な場合に使用します。

{
  "description": "REST API with connection-based auth",
  "tools": [
    {
      "type": "openapi",
      "openapi": {
        "name": "my-api",
        "spec": { "<paste OpenAPI spec object here>" },
        "auth": {
          "type": "connection",
          "security_scheme": {
            "project_connection_id": "<CONNECTION_NAME>"
          }
        }
      }
    }
  ]
}

マネージド ID 認証:

ターゲット API がMicrosoft Entra ID経由で認証する場合は、このパターンを使用します。 Foundry プロジェクトのマネージド ID は、エージェントの代わりに API を呼び出します。 このパターンを使用する前に、マネージド ID にターゲット サービスに必要な RBAC ロールがあることを確認します。

{
  "description": "REST API with managed identity auth",
  "tools": [
    {
      "type": "openapi",
      "openapi": {
        "name": "my-api",
        "spec": { "<paste OpenAPI spec object here>" },
        "auth": {
          "type": "managed_identity",
          "security_scheme": {
            "audience": "<TARGET_SERVICE_AUDIENCE>"
          }
        }
      }
    }
  ]
}

from azure.ai.projects.models import OpenAPITool

tools = [
    OpenAPITool(
        name="my-api",
        spec={"<paste OpenAPI spec object here>"},
        auth={"type": "anonymous"},
    )
]

BinaryData specBytes = BinaryData.FromString("<OpenAPI spec JSON>");
ProjectsAgentTool tool = new OpenAPITool(
    new OpenApiFunctionDefinition(
        name: "my-api",
        spec: specBytes,
        openApiAuthentication: new OpenApiAnonymousAuthDetails()
    )
);

ToolboxVersion toolboxVersion = await toolboxClient.CreateToolboxVersionAsync(
    toolboxName: "my-toolbox",
    tools: [tool],
    description: "REST API via OpenAPI spec"
);

const tools = [
  {
    type: "openapi",
    openapi: {
      name: "my-api",
      spec: { /* paste OpenAPI spec object here */ },
      auth: {
        type: "anonymous",
      },
    },
  },
];

キーベースの認証:

parameters:
  api_key:
    secret: true
    description: API key for the target service
resources:
  - kind: connection
    name: api-conn
    category: CustomKeys
    authType: CustomKeys
    target: https://api.example.com
    credentials:
      keys:
        key: "{{ api_key }}"
  - kind: toolbox
    name: openapi-tools
    description: OpenAPI key-auth toolbox
    tools:
      - type: openapi
        openapi:
          name: my-api
          spec:
            openapi: "3.0.1"
            info:
              title: "My API"
              version: "1.0"
            servers:
              - url: https://api.example.com/v1
            paths:
              /search:
                get:
                  operationId: search
                  parameters:
                    - name: query
                      in: query
                      required: true
                      schema:
                        type: string
                  responses:
                    "200":
                      description: OK
          auth:
            type: connection_auth
            connection_id: api-conn

{
  "description": "Delegate tasks to a specialist agent",
  "tools": [
    {
      "type": "a2a_preview",
      "name": "<AGENT_NAME>",
      "description": "<What this agent does>",
      "base_url": "<AGENT_BASE_URL>",
      "project_connection_id": "<CONNECTION_NAME>"
    }
  ]
}

from azure.ai.projects.models import A2APreviewTool

tools = [
    A2APreviewTool(
        name="<AGENT_NAME>",
        description="<What this agent does>",
        base_url="<AGENT_BASE_URL>",
        project_connection_id="<CONNECTION_NAME>",
    )
]

ProjectsAgentTool tool = new A2APreviewTool()
{
    ProjectConnectionId = "<CONNECTION_NAME>",
};

ToolboxVersion toolboxVersion = await toolboxClient.CreateToolboxVersionAsync(
    toolboxName: "my-toolbox",
    tools: [tool],
    description: "Delegate tasks to a specialist agent"
);

const tools = [
  {
    type: "a2a_preview",
    name: "<AGENT_NAME>",
    description: "<What this agent does>",
    base_url: "<AGENT_BASE_URL>",
    project_connection_id: "<CONNECTION_NAME>",
  },
];

resources:
  - kind: connection
    name: a2a-conn
    category: RemoteA2A
    authType: None
    target: https://your-remote-agent.azurecontainerapps.io
  - kind: toolbox
    name: a2a-tools
    description: Agent-to-Agent toolbox
    tools:
      - type: a2a_preview
        project_connection_id: a2a-conn