Szybki start: jak utworzyć zestaw narzędzi i używać go z agentem hostowanym

Jeśli korzystasz ze ścieżki SDK dla języka Python, użyj sekcji dotyczącej języka Python w dalszej części tego artykułu zamiast ścieżki Azure Developer CLI lub przepływu pracy w programie VS Code. To podejście tworzy toolbox za pomocą polecenia project_client.toolboxes.create_version(...), a następnie przesyła kod hostowanego agenta jako nową wersję i wskazuje ten toolbox po nazwie.

Zainstaluj pakiety Python używane w tej ścieżce:

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

Potrzebujesz istniejącego projektu Foundry z wdrożonym modelem obsługującym czaty. Ścieżka Python SDK w tym przewodniku Szybki start tworzy zestaw narzędzi i wersję agenta hostowanego, ale nie generuje szkieletu nowego projektu Foundry ani nie tworzy wdrożenia modelu.

W przypadku zestawu SDK platformy .NET użyj sekcji dotyczącej języka C# w dalszej części tego artykułu zamiast interfejsu wiersza polecenia Azure Developer CLI lub przepływu pracy w programie VS Code. Ten sposób tworzy zestaw narzędzi za pomocą AgentToolboxes.CreateVersion(...), a następnie przesyła kod hostowanego agenta C# jako nową wersję i wskazuje na ten zestaw narzędzi po nazwie.

Potrzebujesz również zestawu .NET 10 SDK lub nowszego oraz istniejącego projektu Foundry z wdrożonym modelem obsługującym czat.

Potrzebujesz również programu Visual Studio Code z rozszerzeniem Microsoft Foundry Toolkit oraz zalogowania do platformy Azure.

Przykład zawiera element toolbox.yaml w src/toolbox-agent, który definiuje oba narzędzia w ramach jednego punktu końcowego. Utwórz zestaw narzędzi na podstawie tego pliku:

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

Pierwsza wersja staje się wersją domyślną automatycznie. Polecenie wyświetla wersjonowany punkt końcowy MCP zestawu narzędzi. Endpoint Skopiuj wartość z danych wyjściowych. Ustaw ją jako zmienną TOOLBOX_ENDPOINT środowiskową w następnych krokach. Wygląda to tak:

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

1. Otwórz Visual Studio Code i wybierz pozycję Foundry Toolkit na pasku działań.

2. Zaloguj się do konta Azure, jeśli zostanie wyświetlony monit.

3. W obszarze Moje zasoby rozwiń projekt, a następnie rozwiń węzeł Narzędzia.

4. W widoku Narzędzia wybierz ikonę + Dodaj przybornik .

5. Wprowadź nazwę zestawu narzędzi (my-toolbox) i jego opis.

6. Wybierz pozycję Wyszukiwanie w Internecie.

7. Wybierz + Dodaj narzędzie, wybierz opcję dodania zdalnego serwera MCP, a następnie wprowadź adres URL serwera https://learn.microsoft.com/api/mcp. Serwer jest publiczny, więc nie jest wymagane uwierzytelnianie.

8. Wybierz Publikuj. Opublikowanie powoduje utworzenie pierwszej wersji zestawu narzędzi.

9. Skopiuj punkt końcowy MCP zestawu narzędzi. Uruchom następujące polecenie i skopiuj wartość endpoint z danych wyjściowych. Ustaw ją jako zmienną TOOLBOX_ENDPOINT środowiskową w następnych krokach:

   azd ai toolbox show my-toolbox --output json
   

ścieżka zestawu SDK Python

Wykonaj poniższe kroki, jeśli chcesz utworzyć zestaw narzędzi i wdrożyć wersję z hostowanym agentem przy użyciu zestawu SDK języka Python zamiast korzystać z przepływu pracy Azure Developer CLI lub programu VS Code.

1. Tworzenie lub wybieranie projektu Foundry

1. Otwórz portal Foundry i utwórz projekt Foundry lub wybierz istniejący.
2. W projekcie wdróż model obsługujący czaty, taki jak gpt-5.4-mini.
3. Skopiuj punkt końcowy projektu z sekcji Przegląd oraz nazwę wdrożenia z Kompilacja>Wdrożenia.

2. Pobierz przykład hostowanego agenta z zestawu narzędzi

Sklonuj repozytorium przykładów Foundry:

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

Utwórz folder roboczy dla skryptów wdrażania. W tym folderze utwórz plik .env z następującymi wartościami:

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>

Krok 3. Tworzenie przybornika za pomocą Python

Utwórz plik o nazwie create_toolbox.py w tym samym folderze roboczym co .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}")

Uruchom skrypt:

python create_toolbox.py

Przykładowy hostowany agent może odnaleźć zestaw narzędzi albo z TOOLBOX_ENDPOINT, albo z FOUNDRY_PROJECT_ENDPOINT w połączeniu z TOOLBOX_NAME. Ta ścieżka używa TOOLBOX_NAME, więc nie trzeba przechowywać endpointu z wersją w .env.

4. Wdrażanie hostowanego agenta przy użyciu Python

Utwórz plik o nazwie deploy_toolbox_agent.py w tym samym folderze roboczym co .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,
            )

Uruchom skrypt:

python deploy_toolbox_agent.py

Ten skrypt przesyła przykład zestawu narzędzi jako nową wersję hostowanego agenta, tymczasowo kieruje hostowanego agenta do tej wersji, wywołuje go przy użyciu pytania z Microsoft Learn, a po zakończeniu przywraca poprzednią konfigurację punktu końcowego.

5. Zweryfikuj odpowiedź wspomaganą przez zestaw narzędzi

Jeśli poprawnie skonfigurujesz zestaw narzędzi, odpowiedź pokaże, że hostowany agent wykrył narzędzia zestawu i udzielił odpowiedzi na podstawie dokumentacji Microsoft Learn.

Ścieżka zestawu SDK języka C#

Użyj tej ścieżki, aby utworzyć przybornik i wdrożyć przykład hostowanego agenta języka C# przy użyciu zestawu SDK .NET zamiast interfejsu wiersza polecenia dewelopera Azure lub przepływu pracy programu VS Code.

1. Tworzenie lub wybieranie projektu Foundry

1. Otwórz portal Foundry i utwórz projekt Foundry lub wybierz istniejący.
2. W projekcie wdróż model obsługujący czaty, taki jak gpt-4o.
3. Skopiuj punkt końcowy projektu z sekcji Przegląd oraz nazwę wdrożenia z Kompilacja>Wdrożenia.

2. Pobierz przykład hostowanego agenta z zestawu narzędzi

Sklonuj repozytorium przykładów Foundry:

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

Przykład hostowanego agenta C# znajduje się w samples/csharp/hosted-agents/agent-framework/foundry-toolbox-server-side/src/foundry-toolbox-server-side-dotnet-agent-framework. Kod wdrożenia w następnych krokach ustawia następujące zmienne środowiskowe w kontenerze:

3. Utwórz przybornik za pomocą języka C#

Utwórz aplikację konsolową .NET i zainstaluj pakiety. Interfejsy API zestawu narzędzi są dostępne w wersji zapoznawczej, dlatego zainstaluj pakiet w wersji wstępnej Azure.AI.Projects:

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

Zastąp Program.cs następującym kodem i ustaw endpoint jako punkt końcowy projektu:

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}");

Uruchom aplikację:

dotnet run

Przykładowy hostowany agent ustala zestaw narzędzi na podstawie FOUNDRY_PROJECT_ENDPOINT i TOOLBOX_NAME, więc nie trzeba przechowywać punktu końcowego z numerem wersji.

4. Wdrażanie hostowanego agenta za pomocą języka C#

Utwórz drugą aplikację konsolową dla kodu wdrożenia:

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

Zastąp element Program.cs poniższym kodem. Ustaw endpoint, chatModel i samplePath na własne wartości. samplePath to pełna ścieżka do folderu źródłowego foundry-toolbox-server-side-dotnet-agent-framework sklonowanego w kroku 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);
}

Uruchom aplikację:

dotnet run

Ten kod przesyła przykład zestawu narzędzi jako nową wersję hostowanego agenta, tymczasowo kieruje hostowanego agenta do tej wersji, wywołuje go przy użyciu pytania z platformy Microsoft Learn i po zakończeniu przywraca poprzednią konfigurację punktu końcowego.

5. Zweryfikuj odpowiedź wspomaganą przez zestaw narzędzi

Jeśli poprawnie skonfigurujesz zestaw narzędzi, odpowiedź pokaże, że hostowany agent wykrył narzędzia zestawu i udzielił odpowiedzi na podstawie dokumentacji Microsoft Learn.

Usuń skrzynkę narzędzi:

azd ai toolbox delete my-toolbox --force

Po usunięciu zestawu narzędzi jego punkt końcowy przestanie działać. Usuń to z src/toolbox-agent/.env i usuń to ze swojego środowiska azd:

azd env set TOOLBOX_ENDPOINT ""

Usuń agenta i jego zasoby Azure:

azd down

Usuń skrzynkę narzędziową według nazwy:

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"])

Jeśli utworzysz dedykowaną grupę zasobów lub projekt na potrzeby tego przewodnika Szybki start, usuń tę grupę zasobów lub ten projekt z portalu Azure, gdy zestaw narzędzi, wdrożenie czatu lub hostowany agent nie będą już potrzebne.

Kod wdrożenia usuwa już wersję hostowanego agenta i przywraca poprzednią konfigurację punktu końcowego po zakończeniu. Aby usunąć zestaw narzędzi, dodaj ten kod do aplikacji konsolowej, w której zainstalowano pakiety Azure.AI.Projects (wersja wstępna) i 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}'.");

Jeśli utworzysz dedykowaną grupę zasobów lub projekt na potrzeby tego przewodnika Szybki start, usuń tę grupę zasobów lub ten projekt z portalu Azure, gdy zestaw narzędzi, wdrożenie czatu lub hostowany agent nie będą już potrzebne.