Schnellstart: Bereitstellen Ihres ersten gehosteten Agents

• Azure Developer CLI , Version 1.24.0 oder höher

• Visual Studio Code
• Microsoft Foundry Toolkit für visual Studio Code-Erweiterung

Erforderliche Berechtigung

Sie benötigen Azure AI-Projektmanager im Projektbereich, um gehostete Agents zu erstellen und bereitzustellen. Diese Rolle umfasst sowohl die Berechtigungen der Datenebene zum Erstellen von Agents als auch die Möglichkeit, die Azure AI-Benutzerrolle der plattformbasierten Agentidentität zuzuweisen. Die Agentidentität benötigt Azure AI-Benutzer im Projekt, um zur Laufzeit auf Modelle und Artefakte zuzugreifen.

Wenn Sie azd oder die VS Code-Erweiterung verwenden, verarbeiten die Tools die meisten RBAC-Zuordnungen automatisch, einschließlich:

Stellen Sie sicher, dass die verwaltete Identität des Foundry-Projekts über die ACR-Pull-Rolle in der Azure-Containerregistrierung verfügt, die Sie verwenden. Wenn Sie über die Zugriffsrechte "Besitzer" oder "Benutzerzugriffsadministrator" verfügen und dies bevorzugen, können auch die Tools azd/vscode diese Zuweisung für Sie durchführen. Azure AI-Nutzer für die von der Plattform erstellte Agentenidentität (Laufzeitmodell und Toolzugriff)

Schritt 1: Einrichten des Beispielprojekts

Installieren Sie die Azure Entwickler-CLI-Agent-Erweiterung, und initialisieren Sie ein neues gehostetes Agent-Projekt.

1. Installieren Sie die Erweiterung ai agent für die Azure Developer CLI:

   azd ext install azure.ai.agents
   

   Führen Sie Folgendes aus, um zu überprüfen, ob die Erweiterung installiert ist:

   azd ext list
   

2. Initialisieren eines neuen gehosteten Agentprojekts:

   azd ai agent init
   

   Wenn Sie dazu aufgefordert werden, wählen Sie "Neu starten" aus einer Vorlage aus. Der interaktive Fluss führt Sie durch die folgende Konfiguration:

   • Umgebungsname – legt den Namen der Ressourcengruppe fest (zum Beispiel erstellt my-hosted-agentrg-my-hosted-agent).
   • Azure subscription – wählen Sie das Abonnement aus, in dem die Foundry-Ressourcen erstellt werden sollen.
   • Standort – Wählen Sie eine Region für die Ressourcen aus.
   • Modell-SKU – Wählen Sie die für Ihre Region und Ihr Abonnement verfügbare SKU aus.
   • Bereitstellungsname – Geben Sie einen Namen für die Modellbereitstellung ein.
   • Containergröße – Wählen Sie die CPU- und Speicherzuweisung aus, oder übernehmen Sie die Standardwerte.

   Hinweis

   Wenn bereits eine Ressourcengruppe mit demselben Namen vorhanden ist, azd provision wird die vorhandene Gruppe verwendet. Um Konflikte zu vermeiden, wählen Sie zuerst einen eindeutigen Umgebungsnamen aus, oder löschen Sie zuerst die vorhandene Ressourcengruppe.

   Von Bedeutung

   Wenn Sie keinen MCP-Server verwenden, kommentieren oder entfernen Sie die folgenden Zeilen in der agent.yaml Datei:

   - name: AZURE_AI_PROJECT_TOOL_CONNECTION_ID
     value: <CONNECTION_ID_PLACEHOLDER>
   

   Alternativ können Sie auch diesen cmd verwenden:

   azd init -t Azure-Samples/azd-ai-starter-basic
   

   Das -t Flag bedeutet Vorlage.

   Sie geben azd an, diese spezifische Vorlage zu verwenden:

   Azure-Samples/azd-ai-starter-basic – ein Startprojekt aus dem Beispiel-Repository von Microsoft

   Die Starter-Vorlage für KI richtet eine minimale App mit KI-Unterstützung unter Verwendung von Azure-Diensten ein. In der Regel umfasst es Folgendes:

   • Ein einfaches Back-End (häufig Python oder Node.js)
   • Integration in Azure OpenAI-Dienst
   • Bereitzustellende Infrastruktur:
     • Web-App (Azure App Service)
     • KI-Ressourcen
   • Vorkonfigurierte Umgebung für schnelle Bereitstellung

   Tipp

   Wenn Sie in einer nicht interaktiven Umgebung arbeiten, zum Beispiel in einer CI/CD-Pipeline oder einer SSH-Sitzung, verwenden Sie das --no-prompt-Flag mit azd ai agent init. Sie müssen auch alle erforderlichen Werte als Befehlszeilenkennzeichnungen bereitstellen, anstatt auf interaktive Eingabeaufforderungen zu reagieren.

3. Stellen Sie die erforderlichen Azure Ressourcen bereit:

   Hinweis

   Sie benötigen Contributor Zugriff auf Ihr Azure-Abonnement für die Ressourcenbereitstellung.

   azd provision
   

   Dieser Befehl dauert ca. 5 Minuten und erstellt die folgenden Ressourcen:

   Resource	Zweck	Kosten
   Ressourcengruppe	Organisiert alle zugehörigen Ressourcen im selben Bereich	Keine Kosten
   Modellbereitstellung	Vom Agent verwendete Modell	Siehe Foundry-Preise
   Projekt einer Gießerei	Hostet Ihren Agenten und stellt KI-Funktionen bereit.	Konsumbasiert; siehe Foundry-Preise
   Azure Container Registry	Speichert Ihre Container-Images für Agenten	Standardebene; siehe ACR-Preise
   Log Analytics Arbeitsbereich	Verwalten aller Protokolldaten an einer zentralen Stelle	Keine direkten Kosten. Siehe Log Analytics Kosten
   Application Insights	Überwacht die Agentenleistung und zeichnet sie auf.	Zahlung nach Verbrauch; siehe Azure Monitor Preise
   Verwaltete Identität	Authentifiziert Ihren Agent bei Azure Diensten	Keine Kosten

   Tipp

   Führen Sie azd down aus, nachdem Sie diese Schnellstartanleitung abgeschlossen haben, um Ressourcen zu löschen und weitere Kosten zu vermeiden.

Schritt 2: Lokal testen des Agents

Überprüfen Sie vor der Bereitstellung, ob der Agent lokal funktioniert.

1. Starten Sie den Agent lokal:

   azd ai agent run
   

   Dieser Befehl richtet die Umgebung automatisch ein, installiert Abhängigkeiten und startet den Agent. Es nutzt das in startupCommand definierte azure.yaml, um Ihren Agenten zu starten.

   Hinweis

   Vorschaupakete können während des Setups Pip-Abhängigkeits-Versionskonfliktwarnungen erzeugen. Diese Warnungen sind nicht blockierend – der Agent startet und reagiert trotz dieser Warnungen richtig.

   Wenn der Agent nicht gestartet werden kann, überprüfen Sie die folgenden häufigen Probleme:

   Fehler	Lösung
   AuthenticationError oder DefaultAzureCredential Fehler	Führen Sie azd auth login erneut aus, um die Sitzung zu aktualisieren.
   ResourceNotFound	Überprüfen Sie, ob Ihre Endpunkt-URLs den Werten im Foundry-Portal entsprechen.
   DeploymentNotFound	Überprüfen Sie den Bereitstellungsnamen in Build>Bereitstellungen.
   Connection refused	Stellen Sie sicher, dass kein anderer Prozess Port 8088 verwendet.

2. Senden Sie in einem separaten Terminal eine Testnachricht an den lokalen Agent:

   azd ai agent invoke --local "What is Microsoft Foundry?"
   

   Sie sollten eine Antwort mit Websuchergebnissen zu Microsoft Foundry sehen.

Schritt 3: Bereitstellen im Foundry Agent-Dienst

Da Sie die Infrastruktur bereits in Schritt 1 bereitgestellt haben, stellen Sie Ihren Agentcode für Azure bereit:

azd deploy

Der Agentcontainer wird remote erstellt, sodass Docker Desktop nicht auf Ihrem Computer erforderlich ist.

Sobald die Ausgabe abgeschlossen ist, wird ein Link zum Agent Playground und zum Endpunkt angezeigt, um den Agenten programmgesteuert aufzurufen.

Deploying services (azd deploy)

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

Schritt 1: Erstellen eines Foundry-Projekts

Verwenden Sie die Microsoft Foundry Toolkit-Erweiterung in VS Code, um eine neue Microsoft Foundry Project-Ressource zu erstellen.

1. Öffnen Sie die Befehlspalette (Ctrl+UMSCHALT+P), und wählen Sie Microsoft Foundry: Create 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 die Findry-Project Ressource ein.

Fahren Sie nach Abschluss der Projekterstellung mit dem nächsten Schritt fort, und stellen Sie ein Modell bereit.

Schritt 2: Bereitstellen eines Modells

Verwenden Sie die Microsoft Foundry Toolkit-Erweiterung in VS Code, um ein Modell in Foundry bereitzustellen.

1. Öffnen Sie die Befehlspalette (Ctrl+SHIFT+P), und wählen Sie Microsoft Foundry: Open Model Catalog aus.

2. Durchsuchen Sie den Modellkatalog, oder suchen Sie nach gpt-4.1, und wählen Sie die Schaltfläche "Bereitstellen " aus.

3. Wählen Sie auf der Seite "Modellbereitstellung" die Schaltfläche Deploy to Microsoft Foundry aus.

Nachdem das Modell erfolgreich bereitgestellt wurde, fahren Sie mit dem nächsten Schritt fort, und erstellen Sie ein Gehostetes Agent-Projekt.

Schritt 3: Erstellen eines Projekts für gehostete Agenten

Verwenden Sie die Microsoft Foundry Toolkit-Erweiterung in VS Code, um ein Gerüst für ein neues gehostetes Agentprojekt zu erstellen.

1. Öffnen Sie die Befehlspalette (Ctrl+SHIFT+P), und wählen Sie Microsoft Foundry: Create new Hosted Agent aus.

2. Wählen Sie das Framework aus, das Sie verwenden möchten.

3. Wählen Sie eine Programmiersprache aus, Python oder C#.

4. Wählen Sie entweder die Antwort-API oder die Aufruf-API aus.

5. Wählen Sie den Beispielcode aus, den Sie verwenden möchten.

6. Wählen Sie den Ordner aus, in dem Ihre Projektdateien gespeichert werden sollen.

7. Geben Sie einen Namen für den gehosteten Agent ein.

Ein neues VS Code-Fenster wird mit dem neuen Agent-Projektordner als aktiver Arbeitsbereich gestartet.

Schritt 4: Installieren von Abhängigkeiten

Es wird empfohlen, eine virtuelle Umgebung zum Isolieren von Projektabhängigkeiten zu verwenden:

macOS/Linux:

python -m venv .venv
source .venv/bin/activate

Windows (PowerShell):

python -m venv .venv
.\.venv\Scripts\Activate.ps1

Installieren von Abhängigkeiten

Installieren Sie die erforderlichen Python Abhängigkeiten mithilfe von Pip:

pip install -r requirements.txt

Eine Liste der erforderlichen Pakete finden Sie im requirement.txt.

Schritt 5: Lokal testen des Agents

Führen Sie den Agent aus, und testen Sie ihn, bevor Sie ihn bereitstellen.

Option 1: Drücken Sie F5 (empfohlen)

Drücken Sie F5 im VS-Code, um mit dem Debuggen zu beginnen. Alternativ können Sie das Vs Code-Debugmenü verwenden:

1. Öffnen Sie die Ansicht "Ausführen und Debuggen" (STRG+UMSCHALT+D / CMD+UMSCHALT+D)
2. Wählen Sie im Dropdownmenü "Lokalen Workflow-HTTP-Server debuggen" aus.
3. Klicken Sie auf die grüne Schaltfläche "Debuggen starten " (oder drücken Sie F5).

Dies bewirkt Folgendes:

1. Starten des HTTP-Servers mit aktivierter Debuggingfunktion
2. Öffnen Sie den Inspector des Foundry Toolkit-Agenten für interaktive Tests
3. Zulassen, dass Sie Haltepunkte festlegen und den Workflow überprüfen können

Option 2: Im Terminal ausführen

Als HTTP-Server ausführen (Standard):

python main.py

Der gehostete Agent wird dadurch lokal auf http://localhost:8088/ gestartet.

PowerShell (Windows):

$body = @{
   input = "I need a hotel in Seattle from 2025-03-15 to 2025-03-18, budget under `$200 per night"
    stream = $false
} | ConvertTo-Json

Invoke-RestMethod -Uri http://localhost:8088/responses -Method Post -Body $body -ContentType "application/json"

Bash/curl (Linux/macOS):

curl -sS -H "Content-Type: application/json" -X POST http://localhost:8088/responses \
   -d '{"input": "Find me hotels in Seattle for March 20-23, 2025 under $200 per night","stream":false}'

Der Agent verwendet das get_available_hotels Tool, um nach verfügbaren Hotels zu suchen, die Ihren Kriterien entsprechen.

Schritt 6: Bereitstellen für den Foundry Agent Service

Stellen Sie Ihren Agent direkt über VS Code bereit.

1. Öffnen Sie die Befehlspalette (Ctrl+SHIFT+P), und wählen Sie Microsoft Foundry: Deploy Hosted Agent aus.

2. Wählen Sie "Standard-ACR" aus.

3. Wählen Sie die CPU- und Speicherkonfiguration für den Container "Gehosteter Agent" aus.

Wechseln Sie zum Explorer des Microsoft Foundry Toolkits, indem Sie auf der linken Seite das Symbol auswählen. Der Agent wird nach Abschluss der Bereitstellung in der Randleiste der Strukturansicht Gehostete Agents (Vorschau) angezeigt.

Überprüfen des Agentstatus

Überprüfen Sie den Status Ihres Agents, um zu bestätigen, dass er ausgeführt wird.

1. Wählen Sie Ihren gehosteten Agent aus der Strukturansicht „Gehostete Agents (Vorschau)“ aus.

2. Wählen Sie den soeben bereitgestellten Agenten aus.

Auf der Detailseite wird der Status unter dem Bereich "Container-Details" angezeigt.

Testen im Playground mit VS Code

Das Microsoft Foundry Toolkit für VS Code umfasst einen integrierten Playground zum Chatten und Interagieren mit Ihrem Agent.

1. Wählen Sie Ihren gehosteten Agent aus der Strukturansicht „Gehostete Agents (Vorschau)“ aus.

2. Wählen Sie die Option "Playground" aus, und geben Sie eine Nachricht ein, und senden Sie sie, um Ihren Agent zu testen.

Agentstatus überprüfen

Überprüfen Sie den Status Ihres bereitgestellten Agents:

azd ai agent show

So zeigen Sie die Ausgabe im Tabellenformat an:

azd ai agent show --output table

Wenn Ihr Projekt über mehrere Agentdienste verfügt, geben Sie den Agentnamen als Positionsargument an:

azd ai agent show <agent-name>

Testen des bereitgestellten Agents

Senden Sie eine Testnachricht an Ihren bereitgestellten Agent:

azd ai agent invoke "What is Microsoft Foundry?"

Sie sollten eine Antwort mit Websuchergebnissen zu Microsoft Foundry sehen. Die Antwort kann einige Sekunden dauern, wenn der Agent externe Quellen abfragt.

Anzeigen von Agentprotokollen

Überwachen Sie die Liveprotokolle Ihres Agents:

# Fetch recent container console logs
azd ai agent monitor

# Fetch the last N lines of console logs
azd ai agent monitor --tail 20

# Fetch system event logs (container start and stop events)
azd ai agent monitor --type system

# Stream session logs in real time
azd ai agent monitor --session <session-id> --follow

Wenn Ihr Projekt über mehrere Agentdienste verfügt, geben Sie den Agentnamen als Positionsargument an:

azd ai agent monitor <agent-name> --follow

So zeigen Sie eine Vorschau an, was vor der Bestätigung gelöscht wird:

azd down --preview

Wenn Sie zum Löschen bereit sind, führen Sie Folgendes aus:

azd down

Der Bereinigungsprozess dauert ca. 2 bis 5 Minuten.

Um Ihre Ressourcen zu löschen, öffnen Sie das portal Azure, navigieren Sie zu Ihrer Ressourcengruppe, und löschen Sie es zusammen mit allen enthaltenen Ressourcen.

Zeigen Sie die Containerprotokolle Ihres Agents an

Sie können die Konsolen- und Systemprotokolle des Containers überprüfen, um Probleme zu beheben.

1. Wählen Sie Ihren gehosteten Agent aus der Strukturansicht „Gehostete Agents (Vorschau)“ aus.

2. Wählen Sie die Registerkarte "Playground" Ihres gehosteten Agents aus.

3. Wählen Sie in den Sitzungsdetails den Abschnitt "Protokolle" aus.

Anzeigen der Sitzungsdateien Ihres Agents

Sie können alle Dateien anzeigen, die im Startverzeichnis Ihres ADC-basierten Agents gespeichert sind.

1. Wählen Sie Ihren gehosteten Agent aus der Strukturansicht für gehostete Agents (Vorschau) aus.

2. Wählen Sie die Registerkarte "Playground" Ihres gehosteten Agents aus.

3. Wählen Sie den Abschnitt "Dateien" in den Sitzungsdetails aus.

Sie können Ordner innerhalb des aktuellen Ordners herunterladen, hochladen und erstellen, indem Sie auf einen Ordner klicken, in den Ordner wechseln, und durch Klicken auf die obere Navigationsleiste gelangen Sie zurück zu diesem Ordner.