Schnellstart: Eine Toolbox erstellen und mit einem gehosteten Agent verwenden

Verwenden Sie für den Python SDK-Pfad den abschnitt Python weiter unten in diesem Artikel anstelle des Azure Developer CLI- oder VS Code-Workflows. Dieser Pfad erstellt die Toolbox mit project_client.toolboxes.create_version(...)und lädt dann den Hosted-Agent-Code als neue Version hoch und verweist ihn anhand des Namens auf diese Toolbox.

Installieren Sie die in diesem Pfad verwendeten Python Pakete:

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

Sie benötigen ein vorhandenes Foundry-Projekt mit einem bereitgestellten chatfähigen Modell. Der Python SDK-Pfad in dieser Schnellstartanleitung erstellt die Toolbox und die Version des gehosteten Agents, aber er erstellt kein Gerüst für ein neues Foundry-Projekt und keine Modellbereitstellung für Sie.

Verwenden Sie für den .NET SDK-Pfad weiter unten in diesem Artikel den C#-Abschnitt anstelle des Azure Developer CLI- oder VS Code-Workflows. Dieser Pfad erstellt die Toolbox mit AgentToolboxes.CreateVersion(...)und lädt dann den C#-Code für gehosteten Agent als neue Version hoch und verweist ihn anhand des Namens auf diese Toolbox.

Außerdem benötigen Sie das .NET 10 SDK oder höher und ein vorhandenes Foundry-Projekt mit einem bereitgestellten Chat-fähigen Modell.

Außerdem benötigen Sie Visual Studio Code mit der Erweiterung Microsoft Foundry Toolkit, die bei Azure angemeldet ist.

Das Beispiel enthält ein toolbox.yaml in src/toolbox-agent, das beide Tools hinter einen Endpunkt definiert. Erstellen Sie die Toolbox aus dieser Datei:

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

Die erste Version wird automatisch zur Standardversion. Der Befehl druckt den versionierten MCP-Endpunkt der Toolbox. Kopieren Sie den Endpoint Wert aus der Ausgabe. Legen Sie sie in den TOOLBOX_ENDPOINT nächsten Schritten als Umgebungsvariable fest. Dies sieht wie folgt aus:

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

1. Öffnen Sie Visual Studio Code, und wählen Sie "Foundry Toolkit" in der Aktivitätsleiste aus.

2. Melden Sie sich bei Ihrem Azure Konto an, wenn Sie dazu aufgefordert werden.

3. Erweitern Sie unter My Resources zunächst Ihr Projekt und dann Tools.

4. Wählen Sie in der Ansicht "Extras " das Symbol "+Toolbox hinzufügen " aus.

5. Geben Sie den Toolboxnamen (my-toolbox) und eine Beschreibung ein.

6. Wählen Sie die Websuche aus.

7. Wählen Sie + Add tool aus, fügen Sie einen Remote-MCP-Server hinzu, und geben Sie die Server-URL https://learn.microsoft.com/api/mcp ein. Der Server ist öffentlich, sodass keine Authentifizierung erforderlich ist.

8. Wählen Sie "Veröffentlichen" aus. Durch das Veröffentlichen wird die erste Version der Toolbox erstellt.

9. Kopieren Sie den MCP-Endpunkt der Toolbox. Führen Sie den folgenden Befehl aus, und kopieren Sie den endpoint Wert aus der Ausgabe. Legen Sie sie in den nächsten Schritten als TOOLBOX_ENDPOINT Umgebungsvariable fest:

   azd ai toolbox show my-toolbox --output json
   

Python SDK-Pfad

Führen Sie die folgenden Schritte aus, wenn Sie die Toolbox erstellen und die Version des gehosteten Agents mithilfe des Python SDK anstelle des Azure Developer CLI- oder VS Code-Ablaufs bereitstellen möchten.

1. Erstellen oder Auswählen eines Foundry-Projekts

1. Öffnen Sie das Foundry-Portal , und erstellen Sie ein Foundry-Projekt, oder wählen Sie ein vorhandenes Projekt aus.
2. Stellen Sie im Projekt ein chatfähiges Modell wie gpt-5.4-mini bereit.
3. Kopieren Sie den Projektendpunkt aus Overview und den Namen der Bereitstellung aus Build>Deployments.

2. Laden Sie das Toolbox-Beispiel für den gehosteten Agent herunter.

Klonen Sie das Repository für Foundry-Beispiele:

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

Erstellen Sie einen Arbeitsordner für die Bereitstellungsskripts. Erstellen Sie in diesem Ordner eine .env Datei mit den folgenden Werten:

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>

Schritt 3: Erstellen der Toolbox mit Python

Erstellen Sie eine Datei create_toolbox.py namens im selben Arbeitsordner wie .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}")

Führen Sie das Skript aus:

python create_toolbox.py

Der gehostete Beispiel-Agent kann die Toolbox entweder über TOOLBOX_ENDPOINT oder über FOUNDRY_PROJECT_ENDPOINT plus TOOLBOX_NAME auflösen. Dieser Pfad verwendet TOOLBOX_NAME, sodass Sie den Versionsendpunkt .envnicht speichern müssen.

4. Bereitstellen des gehosteten Agents mit Python

Erstellen Sie eine Datei deploy_toolbox_agent.py namens im selben Arbeitsordner wie .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,
            )

Führen Sie das Skript aus:

python deploy_toolbox_agent.py

Dieses Skript lädt das Toolboxbeispiel als neue Version des gehosteten Agents hoch, verweist den gehosteten Agent vorübergehend auf diese Version, ruft es mit einer Microsoft Frage "Lernen" auf und stellt die vorherige Endpunktkonfiguration nach Abschluss wieder her.

5. Überprüfen Sie die durch die Toolbox gestützte Antwort

Wenn Sie die Toolbox richtig konfigurieren, zeigt die Antwort, dass der gehostete Agent die Tools der Toolbox erkannt und unter Verwendung der Microsoft Learn-Dokumentation geantwortet hat.

C#-SDK-Pfad

Verwenden Sie diesen Pfad, um die Toolbox zu erstellen und das C#-Beispiel für gehosteten Agent mit dem .NET SDK anstelle des workflows Azure Developer CLI oder VS Code bereitzustellen.

1. Erstellen oder Auswählen eines Foundry-Projekts

1. Öffnen Sie das Foundry-Portal , und erstellen Sie ein Foundry-Projekt, oder wählen Sie ein vorhandenes Projekt aus.
2. Stellen Sie im Projekt ein chatfähiges Modell wie gpt-4o bereit.
3. Kopieren Sie den Projektendpunkt aus Overview und den Namen der Bereitstellung aus Build>Deployments.

2. Laden Sie das Toolbox-Beispiel für den gehosteten Agent herunter.

Klonen Sie das Repository für Foundry-Beispiele:

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

Das C#-Beispiel für gehosteten Agent befindet sich unter samples/csharp/hosted-agents/agent-framework/foundry-toolbox-server-side/src/foundry-toolbox-server-side-dotnet-agent-framework. Der Bereitstellungscode in den nächsten Schritten legt diese Umgebungsvariablen für den Container fest:

3. Erstellen der Toolbox mit C#

Erstellen Sie eine .NET Konsolen-App, und installieren Sie die Pakete. Toolbox-APIs befinden sich in der Vorschau, installieren Sie also das Vorabversionspaket Azure.AI.Projects :

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

Ersetzen Sie Program.cs durch den folgenden Code und setzen Sie endpoint auf den Endpunkt Ihres Projekts:

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

Führen Sie die App aus:

dotnet run

Der gehostete Beispiel-Agent löst die Toolbox von FOUNDRY_PROJECT_ENDPOINT plus TOOLBOX_NAME auf, sodass Sie den versionierten Endpunkt nicht speichern müssen.

4. Bereitstellen des gehosteten Agents mit C#

Erstellen Sie eine zweite Konsolen-App für den Bereitstellungscode:

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

Ersetzen Sie Program.cs durch den folgenden Code. Setzen Sie chatModel, samplePath und endpoint auf Ihre Werte. samplePath ist der vollständige Pfad zum foundry-toolbox-server-side-dotnet-agent-framework Quellordner, den Sie in Schritt 2 geklont haben:

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

Führen Sie die App aus:

dotnet run

Dieser Code lädt das Toolboxbeispiel als neue Version des gehosteten Agents hoch, verweist den gehosteten Agent vorübergehend auf diese Version, ruft es mit einer Microsoft Frage "Lernen" auf und stellt die vorherige Endpunktkonfiguration wieder her, wenn sie abgeschlossen ist.

5. Überprüfen Sie die durch die Toolbox gestützte Antwort

Wenn Sie die Toolbox richtig konfigurieren, zeigt die Antwort, dass der gehostete Agent die Tools der Toolbox erkannt und unter Verwendung der Microsoft Learn-Dokumentation geantwortet hat.

Löschen Sie die Toolbox:

azd ai toolbox delete my-toolbox --force

Nachdem Sie die Toolbox gelöscht haben, funktioniert der Endpunkt nicht mehr. Entfernen Sie es aus src/toolbox-agent/.env und entfernen Sie es aus Ihrer azd-Umgebung:

azd env set TOOLBOX_ENDPOINT ""

Löschen Sie den Agent und seine Azure Ressourcen:

azd down

Löschen Sie die Toolbox nach Namen:

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

Wenn Sie für diese Schnellstartanleitung eine dedizierte Ressourcengruppe oder ein dediziertes Projekt erstellt haben, löschen Sie sie aus dem Azure-Portal, nachdem Sie die Toolbox, die Chatbereitstellung oder den gehosteten Agent nicht mehr benötigen.

Der Bereitstellungscode löscht bereits die version des gehosteten Agents und stellt die vorherige Endpunktkonfiguration wieder her, wenn sie abgeschlossen ist. Um die Toolbox zu löschen, fügen Sie diesen Code zu einer Konsolen-App hinzu, die die Azure.AI.Projects (Vorabversion) und Azure.Identity Pakete installiert hat:

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

Wenn Sie für diese Schnellstartanleitung eine dedizierte Ressourcengruppe oder ein dediziertes Projekt erstellt haben, löschen Sie sie aus dem Azure-Portal, nachdem Sie die Toolbox, die Chatbereitstellung oder den gehosteten Agent nicht mehr benötigen.