快速入門：建立一個工具箱並與託管代理一起使用

關於 Python SDK 路徑，請使用本文後面的 Python 部分，而非 Azure 開發者的 CLI 或 VS Code 工作流程。 該路徑會建立帶有 project_client.toolboxes.create_version(...)的工具箱，然後上傳託管代理程式作為新版本，並依名稱指向該工具箱。

安裝此路徑中使用的 Python 套件：

pip install "azure-ai-projects>=2.3.0" azure-identity python-dotenv

你需要一個現有的 Foundry 專案，並部署支援聊天的模型。 這個快速入門中的 Python SDK 路徑會建立工具箱和託管代理版本，但它不會為你建立新的 Foundry 專案或建立模型部署。

關於 .NET SDK 路徑，請使用本文後面的 C# 部分，而非 Azure 開發者 CLI 或 VS Code 工作流程。 該路徑會建立帶有 AgentToolboxes.CreateVersion(...)的工具箱，然後上傳 C# 主機代理程式作為新版本，並以名稱指向該工具箱。

你還需要 .NET 10 SDK 或更新版本，以及一個已部署具備聊天功能的 Foundry 專案。

你也需要 Visual Studio Code，並安裝 Microsoft Foundry Toolkit 擴充功能，且已登入 Azure。

範例在 toolbox.yaml 中包含一個 src/toolbox-agent ，該檔案會定義位於同一個端點後方的兩個工具。 從該檔案建立工具箱：

azd ai toolbox create my-toolbox --from-file ./src/toolbox-agent/toolbox.yaml

第一個版本會自動成為預設版本。 該指令會列印工具箱的版本化 MCP 端點。 從輸出中複製Endpoint值。 在接下來的步驟中將它設為 TOOLBOX_ENDPOINT 環境變數。 看起來像這樣：

https://<account>.services.ai.azure.com/api/projects/<project>/toolboxes/my-toolbox/versions/1/mcp?api-version=v1

1. 打開 Visual Studio Code，在活動欄選擇 Foundry Toolkit。

2. 如果系統提示，請登入你的 Azure 帳號。

3. 在 「我的資源」中，展開你的專案，然後再展開 「工具」。

4. 在 工具 檢視中，選擇 + 新增工具箱 圖示。

5. 輸入工具箱名稱（）my-toolbox及說明。

6. 選擇 網頁搜尋。

7. 選擇 + 新增工具，選擇新增遠端 MCP 伺服器，並輸入伺服器網址 https://learn.microsoft.com/api/mcp。 伺服器是公開的，因此不需要認證。

8. 選取發行。 發佈會建立工具箱的第一個版本。

9. 複製工具箱的 MCP 端點。 執行以下指令，並從輸出中複製該 endpoint 值。 在接下來的步驟中，將它設為 TOOLBOX_ENDPOINT 環境變數：

   azd ai toolbox show my-toolbox --output json
   

Python SDK 路徑

如果你想建立工具箱並部署託管代理版本，使用 Python SDK 而非 Azure 開發者 CLI 或 VS Code 流程，請遵循以下步驟。

1. 建立或選擇 Foundry 專案

1. 開啟 Foundry 入口網站 並建立一個 Foundry 專案，或選擇現有的專案。
2. 在專案中，部署一個具備聊天功能的模型，例如 gpt-5.4-mini。
3. 從 Overview 複製專案端點，並從 Build>Deployments 複製部署名稱。

2. 下載工具箱中的 hosted-agent 範例

複製 Foundry 的範例存放庫：

git clone https://github.com/microsoft-foundry/foundry-samples.git

建立一個部署腳本的工作資料夾。 在該資料夾中，建立內容如下的 .env 檔案：

FOUNDRY_PROJECT_ENDPOINT=<your-project-endpoint>
AZURE_AI_MODEL_DEPLOYMENT_NAME=<your-model-deployment-name>
FOUNDRY_HOSTED_AGENT_NAME=toolbox-agent
TOOLBOX_NAME=my-toolbox
FOUNDRY_SAMPLE_PATH=<full-path-to-foundry-samples/samples/python/hosted-agents/agent-framework/responses/04-foundry-toolbox/src/agent-framework-agent-with-foundry-toolbox-responses>

步驟 3：用 Python 建立工具箱

在與 create_toolbox.py 相同的工作資料夾中建立一個名為 .env 的檔案：

import os

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

load_dotenv()

endpoint = os.environ["FOUNDRY_PROJECT_ENDPOINT"].rstrip("/")
toolbox_name = os.environ["TOOLBOX_NAME"]

with (
    DefaultAzureCredential() as credential,
    AIProjectClient(endpoint=endpoint, credential=credential) as project_client,
):
    created = project_client.toolboxes.create_version(
        name=toolbox_name,
        description="Toolbox with web search and Microsoft Learn MCP.",
        tools=[
            WebSearchToolboxTool(
                name="web_search",
                search_context_size="medium",
            ),
            MCPToolboxTool(
                server_label="mslearn",
                server_url="https://learn.microsoft.com/api/mcp",
                require_approval="never",
            ),
        ],
    )
    print(f"Created toolbox version {created.version} for {created.name}")

    mcp_endpoint = (
        f"{endpoint}/toolboxes/{created.name}/versions/"
        f"{created.version}/mcp?api-version=v1"
    )
    print(f"Toolbox version: {created.version}")
    print(f"Toolbox MCP endpoint: {mcp_endpoint}")

執行腳本：

python create_toolbox.py

樣本託管 Agent 可以從TOOLBOX_ENDPOINT或從FOUNDRY_PROJECT_ENDPOINT加上TOOLBOX_NAME解析工具箱。 此路徑使用 TOOLBOX_NAME，因此你不需要將版本控制端點存於 .env。

4. 使用 Python 部署託管代理

在與 deploy_toolbox_agent.py 相同的工作資料夾中建立一個名為 .env 的檔案：

import os
import tempfile
import time
import zipfile
from pathlib import Path

from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import (
    AgentEndpointConfig,
    CodeConfiguration,
    CodeDependencyResolution,
    FixedRatioVersionSelectionRule,
    HostedAgentDefinition,
    ProtocolConfiguration,
    ProtocolVersionRecord,
    ResponsesProtocolConfiguration,
    VersionSelector,
)
from azure.identity import DefaultAzureCredential
from dotenv import load_dotenv

load_dotenv()

endpoint = os.environ["FOUNDRY_PROJECT_ENDPOINT"]
model_name = os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"]
agent_name = os.environ.get("FOUNDRY_HOSTED_AGENT_NAME", "toolbox-agent")
toolbox_name = os.environ["TOOLBOX_NAME"]
sample_path = Path(os.environ["FOUNDRY_SAMPLE_PATH"]).resolve()


def create_code_zip(source_dir: Path) -> Path:
    zip_path = Path(tempfile.gettempdir()) / f"{agent_name}.zip"
    excluded = {".git", ".venv", "__pycache__", ".env"}

    with zipfile.ZipFile(zip_path, "w", zipfile.ZIP_DEFLATED) as zip_file:
        for path in source_dir.rglob("*"):
            if not path.is_file():
                continue
            if any(part in excluded for part in path.parts):
                continue
            zip_file.write(path, path.relative_to(source_dir))

    return zip_path


def wait_for_active_version(project_client: AIProjectClient, version: str) -> None:
    for attempt in range(60):
        time.sleep(10)
        details = project_client.agents.get_version(
            agent_name=agent_name,
            agent_version=version,
        )
        status = details["status"]
        print(f"Provisioning status: {status} (attempt {attempt + 1}/60)")

        if status == "active":
            return

        if status == "failed":
            raise RuntimeError(f"Hosted agent provisioning failed: {dict(details)}")

    raise RuntimeError("Timed out waiting for the hosted agent version to become active.")


code_zip_path = create_code_zip(sample_path)

with (
    code_zip_path.open("rb") as code_stream,
    DefaultAzureCredential() as credential,
    AIProjectClient(endpoint=endpoint, credential=credential) as project_client,
):
    original_agent_endpoint = None
    created = None

    try:
        created = project_client.agents.create_version_from_code(
            agent_name=agent_name,
            description="Hosted agent with Foundry Toolbox integration.",
            definition=HostedAgentDefinition(
                cpu="1",
                memory="2Gi",
                code_configuration=CodeConfiguration(
                    runtime="python_3_13",
                    entry_point=["python", "main.py"],
                    dependency_resolution=CodeDependencyResolution.REMOTE_BUILD,
                ),
                environment_variables={
                    "FOUNDRY_PROJECT_ENDPOINT": endpoint,
                    "AZURE_AI_MODEL_DEPLOYMENT_NAME": model_name,
                    "TOOLBOX_NAME": toolbox_name,
                },
                protocol_versions=[
                    ProtocolVersionRecord(protocol="responses", version="2.0.0")
                ],
            ),
            code=code_stream,
        )

        print(f"Created hosted agent version {created.version}")
        wait_for_active_version(project_client, created.version)

        original_agent_endpoint = project_client.agents.get(
            agent_name=agent_name
        ).agent_endpoint
        project_client.agents.update_details(
            agent_name=agent_name,
            agent_endpoint=AgentEndpointConfig(
                version_selector=VersionSelector(
                    version_selection_rules=[
                        FixedRatioVersionSelectionRule(
                            agent_version=created.version,
                            traffic_percentage=100,
                        ),
                    ]
                ),
                protocol_configuration=ProtocolConfiguration(
                    responses=ResponsesProtocolConfiguration()
                ),
            ),
        )

        with project_client.get_openai_client(agent_name=agent_name) as openai_client:
            response = openai_client.responses.create(
                input=(
                    "How do I create a hosted agent in Microsoft Foundry? "
                    "Use the Microsoft Learn documentation."
                ),
            )
            if response.status != "completed":
                raise RuntimeError(f"Agent invocation failed: {response.error}")
            print(response.output_text)
    finally:
        if original_agent_endpoint is not None:
            project_client.agents.update_details(
                agent_name=agent_name,
                agent_endpoint=original_agent_endpoint,
            )

        if created is not None:
            project_client.agents.delete_version(
                agent_name=agent_name,
                agent_version=created.version,
                force=True,
            )

執行腳本：

python deploy_toolbox_agent.py

此腳本會將工具箱範例上傳為新的託管代理版本，暫時指向該版本，並以 Microsoft Learn 問題呼叫該版本，完成後還原先前的端點設定。

5. 驗證由工具箱支援的回應

如果你正確設定工具箱，回應顯示託管代理發現了工具箱工具，並透過 Microsoft Learn 文件來回答。

C# SDK 路徑

使用此路徑建立工具箱，並部署 C# 託管代理範例，使用 .NET SDK 取代 Azure 開發者 CLI 或 VS Code 工作流程。

1. 建立或選擇 Foundry 專案

1. 開啟 Foundry 入口網站 並建立一個 Foundry 專案，或選擇現有的專案。
2. 在專案中，部署一個具備聊天功能的模型，例如 gpt-4o。
3. 從 Overview 複製專案端點，並從 Build>Deployments 複製部署名稱。

2. 下載工具箱中的 hosted-agent 範例

複製 Foundry 的範例存放庫：

git clone https://github.com/microsoft-foundry/foundry-samples.git

C# 代管代理程式範例位於 samples/csharp/hosted-agents/agent-framework/foundry-toolbox-server-side/src/foundry-toolbox-server-side-dotnet-agent-framework 之下。 接下來的部署程式碼會在容器上設定以下環境變數：

3. 用 C 建立工具箱#

建立一個 .NET 控制台應用程式並安裝套件。 Toolbox API 目前處於預覽階段，請安裝預發布 Azure.AI.Projects 套件：

dotnet new console --name create-toolbox
cd create-toolbox
dotnet add package Azure.AI.Projects --prerelease
dotnet add package Azure.Identity

請用以下程式碼替換 Program.cs ，並設 endpoint 為你的專案端點：

using Azure.AI.Projects;
using Azure.AI.Projects.Agents;
using Azure.Identity;
using OpenAI;
using OpenAI.Responses;

#pragma warning disable AAIP001, OPENAI001

var endpoint = "https://<account>.services.ai.azure.com/api/projects/<project>";
var toolboxName = "my-toolbox";

AIProjectClient projectClient = new(new Uri(endpoint), new DefaultAzureCredential());
AgentToolboxes toolboxes = projectClient.AgentAdministrationClient.GetAgentToolboxes();

ToolboxVersion created = toolboxes.CreateVersion(
    name: toolboxName,
    tools:
    [
        new WebSearchToolboxTool { Name = "web_search", SearchContextSize = WebSearchToolSearchContextSize.Medium },
        new MCPToolboxTool(serverLabel: "mslearn")
        {
            ServerUri = new Uri("https://learn.microsoft.com/api/mcp"),
            ToolCallApprovalPolicy = new McpToolCallApprovalPolicy(GlobalMcpToolCallApprovalPolicy.NeverRequireApproval),
        },
    ],
    description: "Toolbox with web search and Microsoft Learn MCP.");
Console.WriteLine($"Created toolbox version {created.Version} for {created.Name}");

執行應用程式：

dotnet run

範例託管代理程式會從 TOOLBOX_NAME 加上 FOUNDRY_PROJECT_ENDPOINT 解析出工具箱，因此你不需要儲存版本化端點。

4. 使用 C# 部署託管代理程式

建立第二個主控台應用程式來執行部署程式碼：

dotnet new console --name deploy-toolbox-agent
cd deploy-toolbox-agent
dotnet add package Azure.AI.Projects --prerelease
dotnet add package Azure.AI.Extensions.OpenAI
dotnet add package Azure.Identity

以下列程式碼取代 Program.cs。 將 endpoint、chatModel 和 samplePath 設為您要的值。 samplePath 是你在 foundry-toolbox-server-side-dotnet-agent-framework 步驟 2 中複製的原始碼資料夾的完整路徑：

using Azure.AI.Extensions.OpenAI;
using Azure.AI.Projects;
using Azure.AI.Projects.Agents;
using Azure.Identity;
using OpenAI.Responses;

#pragma warning disable AAIP001, OPENAI001

var endpoint = "https://<account>.services.ai.azure.com/api/projects/<project>";
var chatModel = "gpt-4o";
var toolboxName = "my-toolbox";
var agentName = "toolbox-agent";
var samplePath =
    @"<path-to-foundry-samples>\samples\csharp\hosted-agents\agent-framework\foundry-toolbox-server-side\src\foundry-toolbox-server-side-dotnet-agent-framework";

AIProjectClient projectClient = new(new Uri(endpoint), new DefaultAzureCredential());
var agentsClient = projectClient.AgentAdministrationClient;

HostedAgentDefinition definition = new(cpu: "1", memory: "2Gi")
{
    Versions = { new ProtocolVersionRecord(ProjectsAgentProtocol.Responses, "2.0.0") },
    CodeConfiguration = new(
        runtime: "dotnet_10",
        entryPoint: ["dotnet", "foundry-toolbox-server-side.dll"],
        dependencyResolution: CodeDependencyResolution.RemoteBuild),
};
definition.EnvironmentVariables.Add("FOUNDRY_PROJECT_ENDPOINT", endpoint);
definition.EnvironmentVariables.Add("AZURE_AI_MODEL_DEPLOYMENT_NAME", chatModel);
definition.EnvironmentVariables.Add("TOOLBOX_NAME", toolboxName);

ProjectsAgentVersion? created = null;
AgentEndpointConfiguration? originalEndpoint = null;
try
{
    created = agentsClient.CreateAgentVersionFromCode(
        agentName, samplePath, new AgentVersionFromCodeMetadata(definition));
    Console.WriteLine($"Created hosted agent version {created.Version}");

    for (var attempt = 1; attempt <= 60; attempt++)
    {
        Thread.Sleep(TimeSpan.FromSeconds(10));
        created = agentsClient.GetAgentVersion(agentName, created.Version);
        Console.WriteLine($"Provisioning status: {created.Status} (attempt {attempt}/60)");
        if (created.Status == AgentVersionStatus.Active) break;
        if (created.Status == AgentVersionStatus.Failed)
            throw new InvalidOperationException("Hosted agent provisioning failed.");
    }

    ProjectsAgentRecord agent = agentsClient.GetAgent(agentName);
    originalEndpoint = agent.AgentEndpoint;
    agentsClient.PatchAgent(agentName, new PatchAgentOptions
    {
        AgentEndpoint = new AgentEndpointConfiguration
        {
            VersionSelector = new([new FixedRatioVersionSelectionRule(created.Version, 100)]),
            ProtocolConfiguration = new() { Responses = new ResponsesProtocolConfiguration() },
        },
    });

    ProjectResponsesClient responsesClient = projectClient.ProjectOpenAIClient
        .GetProjectResponsesClientForAgentEndpoint(agentName);
    ResponseResult response = responsesClient.CreateResponse(
        "How do I create a hosted agent in Microsoft Foundry? Use the Microsoft Learn documentation.");
    Console.WriteLine(response.GetOutputText());
}
finally
{
    if (originalEndpoint is not null)
        agentsClient.PatchAgent(agentName, new PatchAgentOptions { AgentEndpoint = originalEndpoint });
    if (created is not null)
        agentsClient.DeleteAgentVersion(agentName, created.Version, force: true);
}

執行應用程式：

dotnet run

此程式碼會將工具箱範例上傳為新的主機代理版本，暫時將託管代理指向該版本，並以 Microsoft Learn 問題呼叫該版本，完成後還原先前的端點設定。

5. 驗證由工具箱支援的回應

如果你正確設定工具箱，回應顯示託管代理發現了工具箱工具，並透過 Microsoft Learn 文件來回答。

刪除工具箱：

azd ai toolbox delete my-toolbox --force

刪除工具箱後，它的端點就會停止運作。 從 src/toolbox-agent/.env 中移除它，並從您的 azd 環境中清除它：

azd env set TOOLBOX_ENDPOINT ""

刪除代理程式及其 Azure 資源：

azd down

依名稱刪除工具箱：

import os

from azure.ai.projects import AIProjectClient
from azure.identity import DefaultAzureCredential
from dotenv import load_dotenv

load_dotenv()

with (
    DefaultAzureCredential() as credential,
    AIProjectClient(
        endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
        credential=credential,
    ) as project_client,
):
    project_client.toolboxes.delete(name=os.environ["TOOLBOX_NAME"])

如果你為這個快速入門建立了專用的資源群組或專案，請在不再需要工具箱、聊天部署或託管代理之後，從 Azure 入口網站將其刪除。

部署程式碼已經刪除了託管代理版本，並在完成後還原了之前的端點設定。 要刪除工具箱，請將此程式碼加入安裝（ Azure.AI.Projects 預發布版）及 Azure.Identity 套件的主控台應用程式：

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

#pragma warning disable AAIP001

var endpoint = "https://<account>.services.ai.azure.com/api/projects/<project>";
var toolboxName = "my-toolbox";

AIProjectClient projectClient = new(new Uri(endpoint), new DefaultAzureCredential());
projectClient.AgentAdministrationClient.GetAgentToolboxes().Delete(toolboxName);
Console.WriteLine($"Deleted toolbox '{toolboxName}'.");

如果你為這個快速入門建立了專用的資源群組或專案，請在不再需要工具箱、聊天部署或託管代理之後，從 Azure 入口網站將其刪除。