Schnellstart: Bereitstellen Ihres ersten gehosteten Agents

• Azure Developer CLI (AZD) 1.25.3 oder höher.

• Die azd microsoft.foundry Erweiterung. Installieren und überprüfen Sie die Erweiterung nach der Installation von AZD:

  azd ext install microsoft.foundry
  

• Azure CLI installiert und authentifiziert:

  az login
  

• Die in dieser Schnellstartanleitung verwendeten Python SDK-Pakete:

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

• Ein vorhandenes Foundry-Projekt mit einem bereitgestellten Modell. Der Python SDK-Pfad in dieser Schnellstartanleitung erstellt und leitet eine gehostete Agent-Version weiter, erstellt jedoch kein Gerüst für ein neues Foundry-Projekt oder erstellt eine Modellbereitstellung für Sie. Wenn Sie den vollständigen Bereitstellungsworkflow benötigen, verwenden Sie die Registerkarte Azure Developer CLI in diesem Artikel.

• Visual Studio Code.
• Microsoft Foundry Toolkit für Visual Studio Code.

• Ein Coding-Agent-Host mit installierter Microsoft Foundry Skill.

• Azure CLI und Azure Developer CLI (AZD) installiert und authentifiziert:

  az login
  azd auth login
  

Schritt 1: Initialisieren des Beispiel-Agents

Initialisieren Sie einen neuen gehosteten Agent mithilfe des grundlegenden Agent Framework-Beispiels in einem leeren Verzeichnis:

azd ai agent init -m "https://github.com/microsoft-foundry/foundry-samples/blob/main/samples/python/hosted-agents/agent-framework/responses/01-basic/azure.yaml" --deploy-mode code

Der interaktive Ablauf fragt Folgendes ab:

• Agentname: Passen Sie den Namen an oder übernehmen Sie den Standardwert, agent-framework-agent-basic-responses
• Foundry Project: Wählen Sie ein neues Foundry-Projekt erstellen oder ein vorhandenes Foundry-Projekt verwenden
• Tenant: Wählen Sie Ihren Azure Mandanten aus.
• Abonnement: Wählen Sie Ihr Azure-Abonnement aus.
• Location: Wählen Sie einen Azure Bereich aus.
• Modell: Wählen Sie die Standard-, gpt-5.4-mini- oder ein anderes Modell aus, auf das Sie zugreifen können.
• Modellversion: Wählen Sie die Standardoption aus.
• Modell-SKU: Wählen Sie eine Option mit verfügbarem Kontingent aus, das nicht Batch ist, in der Regel "Standard" oder "GlobalStandard".
• Bereitstellungskapazität: Wählen Sie die Standardeinstellung10 aus.
• Bereitstellungsname: Wählen Sie die Standardeinstellunggpt-5.4-mini aus.

Nach Abschluss sehen Sie, dass die KI-Agent-Definition erfolgreich zu Ihrem azd-Projekt hinzugefügt wurde!. Ändern Sie das Verzeichnis in einen neu erstellten Agentordner.

cd agent-framework-agent-basic-responses

Schritt 2: Bereitstellen Azure Ressourcen

Stellen Sie die in azure.yaml definierten Ressourcen bereit:

azd provision

Schritt 3: Lokal testen des Agents

azd ai agent run

Dieser Befehl erstellt eine virtuelle Umgebung, installiert Abhängigkeiten, startet den Agenten unter Verwendung des in azure.yaml definierten startupCommand und öffnet den Agent-Inspektor in Ihrem Browser, damit Sie mit dem Agenten chatten können.

Schritt 4: Im Foundry-Agent-Dienst bereitstellen

Erstellen und Bereitstellen des Agentcontainers:

azd deploy

Wenn der Befehl abgeschlossen ist, zeigt die Ausgabe Links zum Agent-Playground und zum Agent-Endpunkt an:

Deploying services (azd deploy)

  Done: Deploying service basic-agent
  - Agent playground (portal): https://ai.azure.com/.../build/agents/basic-agent/build?version=1
  - Agent endpoint: https://ai-account-<name>.services.ai.azure.com/api/projects/<project>/agents/basic-agent/versions/1

Schritt 5: Aufrufen Ihres Agents

1. Senden Sie dieselbe Eingabeaufforderung an den bereitgestellten Agent:

   azd ai agent invoke "Write a haiku about deploying cloud applications."
   

   Innerhalb weniger Sekunden sollte eine Haiku-Antwort angezeigt werden.

2. (Optional) Containerprotokolle streamen, während Sie mit dem Agenten interagieren:

   azd ai agent monitor --follow
   

Schritt 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 diese Werte aus dem Portal:

   • Projektendpunkt unter Übersicht.
   • Bereitstellungsname aus Build>Bereitstellungen.

Schritt 2: Herunterladen des Basic-Beispiel-Agent-Codes

Klonen Sie das Repository für Foundry-Beispiele.

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

Schritt 3: Erstellen einer Python Umgebung und Konfigurieren von Einstellungen

Erstellen Sie eine virtuelle Umgebung, und installieren Sie die Python Pakete, die für diese Schnellstartanleitung erforderlich sind.

Für macOS oder Linux:

python -m venv .venv
source .venv/bin/activate
pip install "azure-ai-projects>=2.3.0" azure-identity python-dotenv

Für Windows (PowerShell)

python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install "azure-ai-projects>=2.3.0" azure-identity python-dotenv

Erstellen Sie einen Arbeitsordner für das Bereitstellungsskript, und erstellen Sie dann eine .env Datei in diesem Ordner:

FOUNDRY_PROJECT_ENDPOINT=<your-project-endpoint>
FOUNDRY_MODEL_NAME=<your-model-deployment-name>
FOUNDRY_HOSTED_AGENT_NAME=basic-agent
FOUNDRY_SAMPLE_PATH=<full-path-to-foundry-samples/samples/python/hosted-agents/agent-framework/responses/01-basic>

Schritt 4: Bereitstellen des gehosteten Agents mit Python

Erstellen Sie im selben Arbeitsordner wie .env eine Datei mit dem Namen deploy_hosted_agent.py und dem folgenden Inhalt:

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["FOUNDRY_MODEL_NAME"]
agent_name = os.environ.get("FOUNDRY_HOSTED_AGENT_NAME", "basic-agent")
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", "deploy_hosted_agent.py"}

  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="Basic hosted agent deployed from local Python source.",
      definition=HostedAgentDefinition(
        cpu="0.5",
        memory="1Gi",
        code_configuration=CodeConfiguration(
          runtime="python_3_14",
          entry_point=["python", "main.py"],
          dependency_resolution=CodeDependencyResolution.REMOTE_BUILD,
        ),
        environment_variables={
          "FOUNDRY_PROJECT_ENDPOINT": endpoint,
          "FOUNDRY_MODEL_NAME": model_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()
        ),
      ),
    )

    print(f"Agent endpoint configured for version {created.version}")

    with project_client.get_openai_client(agent_name=agent_name) as openai_client:
      response = openai_client.responses.create(
        input="Write a haiku about deploying cloud applications.",
      )

    print(f"Agent response: {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,
      )
      print("Agent endpoint restored")

    if created is not None:
      project_client.agents.delete_version(
        agent_name=agent_name,
        agent_version=created.version,
        force=True,
      )
      print(f"Deleted hosted agent version {created.version}")

Führen Sie das Skript aus:

python deploy_hosted_agent.py

Das Skript zippt die Beispielquelle, lädt sie als neue Version des gehosteten Agents hoch, wartet auf den Abschluss der Bereitstellung, leitet den Endpunkt des gehosteten Agents vorübergehend an diese Version weiter, ruft den bereitgestellten Agent auf und stellt dann die vorherige Endpunktkonfiguration wieder her und löscht die temporäre Version.

Schritt 5: Aufrufen Ihres Agents

Verwenden Sie nach Abschluss des Skripts den gehosteten Agent auf eine der folgenden Arten:

1. Bearbeiten Sie deploy_hosted_agent.py und ändern Sie den an openai_client.responses.create(...) übergebenen input-Wert. Führen Sie das Skript dann erneut aus.
2. Wenn Sie statt einer temporären Validierungsbereitstellung eine dauerhaft geroutete Version wünschen, passen Sie das Skript so an, dass die Schritte zur Wiederherstellung und delete_version(...) übersprungen werden, nachdem Sie die Auswirkungen auf das Routing des Datenverkehrs geprüft haben.

Schritt 1: Erstellen eines Foundry-Projekts

1. Öffnen Sie die Befehlspalette (Ctrl+SHIFT+P), und wählen Sie Foundry Toolkit: Erstellen Project aus.
2. Wählen Sie Ihr Azure-Abonnement aus.
3. Erstellen Sie eine neue Ressourcengruppe, oder wählen Sie eine vorhandene aus.
4. Geben Sie einen Namen für das Foundry-Projekt ein.

Schritt 2: Bereitstellen eines Modells

1. Öffnen Sie die Befehlspalette, und wählen Sie foundry Toolkit: Open Model Catalog.
2. Suchen Sie nach gpt-4.1 und wählen Sie Deploy.
3. Wählen Sie auf der Modellbereitstellungsseite Deploy to Microsoft Foundry aus.

Schritt 3: Erstellen eines gehosteten Agent-Projekts

1. Öffnen Sie die Befehlspalette, und wählen Sie "Foundry Toolkit" aus: Neuen gehosteten Agent erstellen.
2. Wählen Sie Python als Sprache aus.
3. Wählen Sie für "Framework" die Option "Agent Framework" aus.
4. Wählen Sie die Antwort-API als Protokolltyp aus.
5. Wählen Sie "Einfach" als Beispielcode aus.
6. Wählen Sie die Schaltfläche Weiter aus.
7. Wählen Sie einen Ordner für die Projektdateien aus, und geben Sie einen Namen für den Agent ein.
8. Wählen Sie unter "Umgebungseinrichtung" die Option "Mit Microsoft Foundry einrichten" aus. Der Inhalt wird automatisch mit dem Projekt und dem Modell aufgefüllt, das Sie in den Schritten 1 und 2 erstellt haben.
9. Wählen Sie die Schaltfläche "Erstellen " aus.

Ein neues VS Code-Fenster wird geöffnet, wobei das Projekt der aktive Arbeitsbereich ist.

Schritt 4: Installieren von Abhängigkeiten

Erstellen Sie eine virtuelle Umgebung, und installieren Sie die Anforderungen.

Für macOS oder Linux:

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Für Windows (PowerShell)

python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt

Schritt 5: Lokal testen des Agents

Drücken Sie F5 , um den lokalen HTTP-Server mit aktivierter Debuggingfunktion zu starten. Der Foundry Toolkit Agent Inspector wird für interaktive Tests geöffnet, und Sie können Haltepunkte in Ihrem Code festlegen.

So führen Sie den Server ohne Debugging aus:

python main.py

Der Agent wartet auf http://localhost:8088/. Senden sie eine Testaufforderung mit curl (oder einem beliebigen HTTP-Client):

curl -sS -H "Content-Type: application/json" -X POST http://localhost:8088/responses \
    -d '{"input": "Write a haiku about deploying cloud applications.", "stream": false}'

Schritt 6: Bereitstellen im Foundry-Agentendienst

1. Öffnen Sie die Befehlspalette, und wählen Sie Foundry Toolkit: Deploy Hosted Agent. Eine Bereitstellungswebansicht wird geöffnet.
2. Wählen Sie für die Bereitstellungsmethode"Code" aus.
3. Wählen Sie "Remote" als Paketmodus aus.
4. Der Agentname wird automatisch aufgefüllt.
5. Wählen Sie die Schaltfläche Weiter aus.
6. Die Seite " Überprüfen und Bereitstellen " wird automatisch aufgefüllt.
7. Wählen Sie die Schaltfläche "Bereitstellen" aus .

Nach Abschluss der Bereitstellung wird der Agent im Foundry-Toolkit-Explorer unter Hosted Agents (Preview) angezeigt.

Schritt 7: Aufrufen Ihres Agents

1. Erweitern Sie im Explorer des Foundry Toolkits Gehostete Agents (Vorschau) und wählen Sie Ihren Agent aus. Auf der Detailseite wird der Status unter "Bereitstellungsdetails" angezeigt.
2. Wählen Sie die Registerkarte „Playground“ aus und senden Sie einen Test-Prompt, wie z. B. Write a haiku about deploying cloud applications..

1. Wenn Sie das Beispielskript wie geschrieben verwendet haben, stellt es die Endpunktkonfiguration bereits wieder her und löscht die temporäre version des gehosteten Agents nach der Überprüfung.
2. Wenn Sie für diese Schnellstartanleitung eine dedizierte Ressourcengruppe erstellt haben, können Sie die Ressourcengruppe aus dem Azure Portal löschen, nachdem Sie die Projekt- oder Modellbereitstellung nicht mehr benötigen.

Schritt 1: Öffnen Sie einen Arbeitsbereich mit dem Foundry Skill

Öffnen Sie einen leeren Ordner in Ihrem Codierungs-Agent-Host, z. B. GitHub Copilot in Visual Studio Code, Copilot CLI oder Claude Code. Vergewissern Sie sich, dass die microsoft-foundry Fähigkeit verfügbar ist, bevor Sie den Codierungs-Agent bitten, Azure Ressourcen zu erstellen.

Wenn der Skill nicht verfügbar ist, befolgen Sie Verwenden des Microsoft Foundry Skill in Programmier-Agents.

Schritt 2: Fordern Sie das Skill auf, den gehosteten Agenten zu erstellen.

Bitten Sie Ihren Codierungs-Agent, die Fähigkeit für den vollständigen Workflow des gehosteten Agents zu verwenden:

Use the Microsoft Foundry Skill hosted-agent quick-start workflow to create my
first hosted agent end to end. Verify my environment first, and stop if I need
to sign in myself. Use Python 3.13, Agent Framework, the Responses API, the
Basic sample, and code deployment. Create a new Foundry project unless I provide
an existing project. Use the model deployment from the Basic sample unless I
provide an existing deployment. Test the agent locally, deploy it to Foundry
Agent Service, and invoke it with: "Write a haiku about deploying cloud
applications."

Der Programmier-Agent sollte die verfügbaren Foundry-Tools prüfen, wenn MCP-Tools verfügbar sind, den Schnellstartworkflow für den gehosteten Agent laden und fehlende Angaben wie das Abonnement, die Region, den Projektnamen und die Frage, ob ein vorhandenes Foundry-Projekt verwendet werden soll, abfragen oder dafür Standardwerte verwenden.

Schritt 3: Überprüfen und Genehmigen des Plans

1. Überprüfen Sie den Plan, dateien, Befehle, Azure Ressourcen und Rollenzuweisungen, die der Codierungs-Agent vorschlägt.
2. Um dieser Schnellstartanleitung zu entsprechen, wählen Sie Python 3.13, Agent Framework, Antwort-API, Standardbeispielcode und Codebereitstellung aus.
3. Genehmigen Sie die Erstellung kostenpflichtiger Ressourcen erst, nachdem Sie das Abonnement, die Region, die Ressourcengruppe, die Modellbereitstellung und das Kontingent überprüft haben.
4. Wenn Sie vom Coding-Agent aufgefordert werden, sich zu authentifizieren, führen Sie az login und azd auth login selbst aus und bitten Sie den Coding-Agent dann, fortzufahren.

Schritt 4: Lassen Sie das Qualifikationsgerüst erstellen und den Agenten testen

Lassen Sie den Codierungs-Agent das gehostete Agent-Projekt erstellen, Ressourcen bereitstellen, wenn Sie ein neues Foundry-Projekt auswählen, lokale Umgebungswerte schreiben, die lokale Umgebung vorbereiten und einen lokalen Rauchtest ausführen. Für Python-Agenten verwendet der Skill-Workflow azd ai agent run, um während der ersten lokalen Ausführung Abhängigkeiten zu installieren.

Der Workflow sollte außerdem die vom Host des Codierungs-Agenten erforderliche Projektleitfaden-Datei hinzufügen und die generierte Projektkonfiguration vor dem lokalen Test auf Plausibilität prüfen.

Wenn Ihr Codierungs-Agent-Host keinen lokalen Server für den Rauchtest ausführen kann, verwenden Sie die Registerkarte Azure Developer CLI in diesem Artikel für die lokalen Testbefehle. Sie können mit der Bereitstellung erst fortfahren, wenn Sie sich stattdessen dafür entscheiden, den Agent per Fernzugriff zu validieren.

Schritt 5: Bereitstellen und Aufrufen des gehosteten Agents

Nachdem der lokale Rauchtest erfolgreich war, bitten Sie Ihren Codierungs-Agent, die Bereitstellung und Remoteüberprüfung abzuschließen:

Continue with the Microsoft Foundry Skill workflow. Deploy the hosted agent to
Foundry Agent Service, show the deployment status and playground link, and invoke
it remotely with: "Write a haiku about deploying cloud applications." If the
skill workflow requires evaluation suite generation before the final summary,
submit the generation job and show me the follow-up eval command.

Wenn der Workflow abgeschlossen ist, sollte der Programmier-Agent den Namen des gehosteten Agenten, die Version, den Bereitstellungsstatus, den Endpunkt, den Playground-Link, die erstellten Ressourcen, die Antwort auf den Testprompt und gegebenenfalls einen Befehl für die Evaluierungsnachverfolgung anzeigen.

azd down

azd listet die Ressourcen auf, die gelöscht werden, und fordert zur Bestätigung auf. Die Bereinigung dauert etwa 2-5 Minuten.

1. Öffnen Sie das Azure Portal, und wechseln Sie zur Ressourcengruppe, die Ihren Agent enthält.
2. Wählen Sie "Ressourcengruppe löschen", geben Sie den zu bestätigenden Ressourcengruppennamen ein, und wählen Sie "Löschen" aus.

Die Microsoft Foundry Skill löscht keine Ressourcen selbst. Es kann Ihrem Programmier-Agenten helfen, die Ressourcen zu identifizieren, die durch diesen Schnellstart erstellt wurden, und die richtige Bereinigungsmethode auszuwählen. Sie oder Ihr Codierungs-Agent führen den Bereinigungsbefehl weiterhin aus, nachdem Sie ihn überprüft und genehmigt haben.

1. Bitten Sie im Projektordner des gehosteten Agenten Ihren Coding-Agenten, die Bereinigung zu überprüfen:

   Use the Microsoft Foundry Skill to identify the Azure resources created for
   this quickstart. Confirm whether azd down is the right cleanup method for
   this project, and show me the resources before any deletion command runs.
   

2. Wenn das Projekt für gehostete Agents mit azd erstellt wurde und die Ressourcengruppe nur Quickstart-Ressourcen enthält, führen Sie Folgendes aus:

   azd down
   

3. Genehmigen Sie den Löschvorgang nur, nachdem Sie die Ressourcengruppe und ressourcen überprüft haben, die die Befehlsliste enthält.

Wenn Ihr Codierungs-Agent keine Bereinigungsbefehle ausführen kann, verwenden Sie die Registerkarte Azure Entwickler-CLI in diesem Artikel, oder löschen Sie die Ressourcengruppe aus dem Azure-Portal.