Schnellstart: Bereitstellen Ihres ersten gehosteten Agents

• Azure Developer CLI Version 1.23.0 oder höher
• Docker Desktop installiert und ausgeführt

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

Schritt 1: Einrichten des Beispielprojekts

Initialisieren Sie ein neues Projekt mit der Startvorlage Foundry und konfigurieren Sie es mit dem Beispiel "agent-with-foundry-tools".

1. Initialisieren Sie die Startvorlage in einem leeren Verzeichnis:

   azd init -t https://github.com/Azure-Samples/azd-ai-starter-basic
   

   Mit diesem interaktiven Befehl werden Sie zur Eingabe eines Umgebungsnamens aufgefordert (z. B my-hosted-agent. ). Der Umgebungsname bestimmt ihren Ressourcengruppennamen (rg-my-hosted-agent).

   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.

2. Das Agentenbeispiel initialisieren:

   azd ai agent init -m https://github.com/microsoft-foundry/foundry-samples/blob/main/samples/python/hosted-agents/agent-framework/agent-with-foundry-tools/agent.yaml
   

   Mit diesem interaktiven Befehl werden Sie zur Eingabe der folgenden Konfigurationswerte aufgefordert:

   • Azure-Abonnement – wählen Sie das Azure 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.
   • Containerspeicher – Geben Sie einen Wert für die Speicherzuordnung des Containers ein, oder akzeptieren Sie die Standardwerte.
   • Container-CPU – Geben Sie einen Wert für die CPU-Zuordnung des Containers ein, oder akzeptieren Sie die Standardwerte.
   • Minimale Replikate – Geben Sie einen Wert für die minimalen Replikate des Containers ein.
   • Max. Replikate – Geben Sie einen Wert für die maximalen Replikate des Containers ein.

   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>
   

3. Stellen Sie die erforderlichen Azure Ressourcen bereit:

   Hinweis

   Sie benötigen Contributor access in Ihrem 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.	Pay-as-you-go; siehe Azure Monitor Preisgestaltung
   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. Erstellen und Aktivieren einer virtuellen Python-Umgebung:

   Bash:

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

   PowerShell:

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

2. Installieren von Abhängigkeiten:

   pip install -r ./src/af-agent-with-foundry-tools/requirements.txt
   

3. Kopieren Sie die erforderlichen Umgebungsvariablen, die im Agentcode verwendet werden, in eine lokale env-Datei:

   Bash:

   azd env get-values > .env
   

   PowerShell:

   azd env get-values > .env
   

4. Fügen Sie die Variable AZURE_OPENAI_CHAT_DEPLOYMENT_NAME mit dem Namen der Modellbereitstellung in Ihre .env Datei ein.

   AZURE_OPENAI_CHAT_DEPLOYMENT_NAME="gpt-4.1"

5. Führen Sie den Agenten lokal aus:

   python ./src/af-agent-with-foundry-tools/main.py
   

   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.

6. Testen sie mit einem REST-Client. Der Agent wird auf localhost:8088 ausgeführt:

   Bash:

   curl -X POST http://localhost:8088/responses \
       -H "Content-Type: application/json" \
       -d '{"input": "What is Microsoft Foundry?"}'
   

   PowerShell:

   Invoke-RestMethod -Method Post `
       -Uri "http://localhost:8088/responses" `
       -ContentType "application/json" `
       -Body '{"input":"What is Microsoft Foundry?"}'
   

   Sie sollten eine Antwort mit Websuchergebnissen zu Microsoft Foundry sehen.

7. Beenden Sie den lokalen Server mit STRG+C.

Schritt 3: Bereitstellen im Foundry Agent-Dienst

Der Befehl azd up kombiniert drei Schritte in einem: Bereitstellungsinfrastruktur, Packen Ihrer Anwendung und Bereitstellen für Azure. Dies entspricht der Ausführung azd provision, azd package, und azd deploy separat.

Bevor Sie beginnen, überprüfen Sie, ob Docker Desktop ausgeführt wird:

docker info

Wenn dieser Befehl fehlschlägt, starten Sie Docker Desktop, und warten Sie, bis er initialisiert wird, bevor Sie fortfahren.

Stellen Sie Ihren Agent bereit:

azd up

Die erste Bereitstellung dauert länger, da Docker das Image erstellen muss.

Wenn Sie fertig sind, wird ein Link zum Agent-Playground und zum Endpunkt für den Agent angezeigt, der zum programmgesteuerten Aufrufen des Agents verwendet werden kann.

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-Erweiterung in VS Code, um eine neue Microsoft Foundry Project-Ressource zu erstellen.

1. Öffnen Sie die Befehlspalette (STRG+UMSCHALT+P), und wählen Sie "Microsoft Foundry: Create Project" aus.

2. Wählen Sie Ihr Azure-Abonnement.

3. Erstellen Sie eine neue Ressourcengruppe, oder wählen Sie eine vorhandene aus.

4. Geben Sie einen Namen für die Ressource "Foundry Project" 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-Erweiterung in VS Code, um ein Modell in Foundry bereitzustellen.

1. Öffnen Sie die Befehlspalette (STRG+UMSCHALT+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 " In Microsoft Foundry bereitstellen " 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-Erweiterung in VS Code, um ein Gerüst für ein neues gehostetes Agentprojekt zu erstellen.

1. Öffnen Sie die Befehlspalette (STRG+UMSCHALT+P), und wählen Sie "Microsoft Foundry" aus: Neuen gehosteten Agent erstellen.

2. Wählen Sie entweder die Vorlage "Einzelner Agent" oder "Workflow mit mehreren Agenten" aus.

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

4. Wählen Sie das vorhandene gpt-4.1-Modell aus, das Sie im vorherigen Schritt bereitgestellt haben.

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

6. 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

Die erforderlichen Pakete sind:

• azure-ai-agentserver-agentframework - Agent Framework und AgentServer SDK

Schritt 5: Lokal testen des Agents

Führen Sie den Agenten 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 des AI Toolkit Agent Inspector 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 im Foundry-Agent-Dienst

Stellen Sie Ihren Agent direkt über VS Code bereit.

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

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

3. Wählen Sie im daraufhin angezeigten Dialogfeld die Schaltfläche "Bestätigen" und "Bereitstellen" aus.

Wechseln Sie zum Microsoft Foundry-Explorer, indem Sie auf der linken Seite das Symbol auswählen. Der Agent wird nach Abschluss der Bereitstellung in der Randleiste der Strukturansicht gehosteter 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 eine Version (v1) aus, um die Detailseite zu öffnen.

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

Testen im Playground mit VS Code

Microsoft Foundry für VS Code enthält einen integrierten Playground zum Chatten und Interagieren mit Ihrem Agent.

1. Wählen Sie Ihren gehosteten Agenten aus der Strukturansicht "Gehostete Agente (Vorschau)" aus.

2. Wählen Sie eine Version (v1) aus, um die Detailseite zu öffnen.

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

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 Azure-Portal, navigieren Sie zu Ihrer Ressourcengruppe, und löschen Sie sie 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 eine Version (v1) aus, um die Detailseite zu öffnen.

3. Wählen Sie auf der rechten Seite die Schaltfläche "Protokolle" aus, um die Protokollanzeige zu öffnen.