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, erstellt jedoch kein Gerüst für ein neues Foundry-Projekt oder erstellt eine Modellbereitstellung für Sie.

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

    toolbox = project_client.toolboxes.get(name=toolbox_name)
    mcp_endpoint = (
        f"{endpoint}/toolboxes/{toolbox.name}/versions/"
        f"{toolbox.default_version}/mcp?api-version=v1"
    )
    print(f"Default toolbox version: {toolbox.default_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 von TOOLBOX_ENDPOINT oder von FOUNDRY_PROJECT_ENDPOINT Plus TOOLBOX_NAMEauflö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."
                ),
            )
            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.

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 anhand des Namens:

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.