Erstellen von gehosteten Agents mit Microsoft Foundry Toolkit für Visual Studio Code

Verwenden Sie Microsoft Foundry Toolkit für Visual Studio Code, um einen codebasierten Workflow aus einem Microsoft Agent Framework-Beispiel zu erstellen. Führen Sie sie lokal mit dem Agent Inspector aus, und stellen Sie den Quellcode dann als gehosteter Agent für den Foundry Agent Service bereit. Sie verwalten den Code und die zugehörigen Abhängigkeiten. Foundry verwaltet die Hostinginfrastruktur und skalierung.

Gehostete Workflows koordinieren Agents im Code. Sie unterscheiden sich von dem eingestellten deklarativen Workflow-Dienst von Foundry. Weitere Erstellungsrouten finden Sie unter Erstellen eines Agents.

Voraussetzungen

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

• Wählen Sie ein Foundry-Projekt mit einem bereitgestellten Modell aus. Verwenden Sie eine unterstützte Region des gehosteten Agents.

• Berechtigung für die Verwendung des Modells und Bereitstellen gehosteter Agents. Für die Bereitstellung von Quellcode umfasst die Rolle Foundry Project Manager auf Projektebene Agentenoperationen und Berechtigungen zur Rollenzuweisung. Siehe Berechtigungen des gehosteten Agents.

  Von Bedeutung

  Die Foundry-RBAC-Rollen wurden kürzlich umbenannt. Foundry User, Foundry Owner, Foundry Account Owner und Foundry Project Manager wurden zuvor Azure KI-Benutzer, Azure KI-Besitzer, Azure KI-Kontobesitzer und Azure AI Project Manager benannt. Möglicherweise werden die vorherigen Namen an einigen Stellen weiterhin angezeigt, während der Umbenennungsrollout ausgeführt wird. Die Rollen-IDs und Kernberechtigungen bleiben durch die Umbenennung unverändert.

• Azure CLI für die schritte zur lokalen Authentifizierung in diesem Artikel.

• Für die Containerbereitstellung werden der Zugriff auf die Registry und das Image durch Azure Container Registry-Einrichtung benötigt. Diese Registrierungsanforderungen gelten nicht für eine Quellcodebereitstellung.

Der Hauptbereitstellungspfad verwendet Code im Remotepaketmodus und erfordert keinen lokalen Docker-Build. Die lokale Ausführung sendet weiterhin Modellanforderungen an Foundry und kann Gebühren verursachen. Überprüfen Sie die Dienstbeschränkungen und Verfügbarkeits- und Toolkit-Versionshinweise für die von Ihnen verwendeten Features.

Erstellen eines gehosteten Agent-Workflows

Wählen Sie ein Agent Framework-Beispiel aus, das das Antwortprotokoll verwendet. Sie müssen zuerst keinen separaten Eingabeaufforderungs-Agent erstellen. Zum Vergleichen von Beispielen, Agent Builder und Copilot-unterstütztem Programmieren siehe Erstellungsweg auswählen.

1. Wählen Sie in der Ansicht "Foundry Toolkit " die Option "Developer Tools>Build>Create Agent" aus.

2. Wählen Sie unter "Code an agent from samples" die Option "Alle Beispiele durchsuchen" aus.

3. Filtern Sie in „Gehosteten Agent aus Beispiel erstellen“ nach Sprache, Framework = und Protokolltyp = Antworten. Suchen Sie nach workflow.

   Der folgende Screenshot zeigt die Galerie, wobei Basic Hosted Agent als Beispiel ausgewählt ist. Wählen Sie für diese Anleitung stattdessen das Workflowbeispiel für Ihre Sprache aus.

   

4. Wählen Sie das Workflowbeispiel für Ihre Sprache aus.

5. Wählen Sie Weiteraus.

6. Wählen Sie unter "Erstellen" den Arbeitsbereichsordner aus. Wenn der Ordner bereits Dateien enthält, geben Sie einen Ordnernamen für einen neuen untergeordneten Ordner ein.

7. Wenn das Umgebungssetup angezeigt wird, wählen Sie Setup mit Microsoft Foundry und dann Ihr Abonnement und Projekt aus. Wenn bereits ein Standardprojekt ausgewählt ist, verwendet das Formular dieses Projekt.

8. Wählen Sie eine vorhandene kompatible Modellbereitstellung aus.

   Der folgende Screenshot zeigt Beispielprojekteinstellungen mit ausgeblendeten lokalen Pfaden. Verwenden Sie Ihr eigenes Ziel und die für Ihr Beispiel erforderliche Modellbereitstellung.

   

9. Überprüfen Sie das Ziel, und wählen Sie dann "Erstellen" aus.

10. Öffnen Sie das generierte Projekt in Visual Studio Code, und lesen Sie dessen README.md.

Die Kacheln Agent Framework, Copilot SDK und LangGraph auf Create Agent öffnen den Tab Create mit ausgewähltem Hello-World-Starter. Verwenden Sie "Alle Beispiele durchsuchen ", um einen Workflow anstelle eines dieser Starter auszuwählen. Sie können die Galerie auch über My Resources>Agents>Hosted Agent> öffnen.

Beispielnamen und -inhalte können sich mit dem Katalog ändern. Einige Versionen bezeichnen diese Beispiele als Workflows. Verwenden Sie den link GitHub des Beispiels, um zu bestätigen, dass Sie den beabsichtigten Workflow ausgewählt haben.

Skip for now generiert den Code, ohne das Modellsetup abzuschließen. Wenn Sie dies auswählen, konfigurieren Sie die erforderlichen Projekt- und Modellwerte, bevor Sie das Beispiel ausführen. Bereitstellen von & und Verwenden eines neuen Modells, wenn angeboten, stellt eine Modellbereitstellung und nicht den gehosteten Agent bereit. Das Erstellen der lokalen Projektdateien stellt den Agent nicht bereit.

Konfigurieren des lokalen Projekts

Lassen Sie den Ordner, der azure.yaml enthält, als Stamm des Arbeitsbereichs geöffnet. Überprüfen Sie den Pfad des Hosted-Agent-Diensts project in dieser Datei, um das Quellverzeichnis zu finden.

Beispiellayouts können sich ändern. Verwenden Sie die generierten README.md und azure.yaml, anstatt anzunehmen, dass sich der Code und die Umgebungsdatei im Stammverzeichnis des Arbeitsbereichs befinden.

Abhängigkeiten installieren

Verwenden Sie die Abhängigkeitsdateien des generierten Beispiels. Halten Sie den ausgewählten Interpreter oder das SDK mit der zugehörigen Laufzeitkonfiguration konsistent.

Festlegen des Projekts und des Modells

Überprüfen Sie die .env Datei im Quellverzeichnis. Wenn sie nicht vorhanden ist, erstellen Sie sie mit den für das Beispiel erforderlichen Werten.

Beide Workflowbeispiele laden .env beim Start. Der Projektendpunkt ist kein Azure OpenAI-Kontoendpunkt. Behalten Sie die Datei außerhalb der Quellcodeverwaltung bei, und fügen Sie keine Anmeldeinformationen in Ihren Anwendungscode ein.

Lokal authentifizieren

Die Beispiele verwenden DefaultAzureCredential. Melden Sie sich für den Anmeldeinformationspfad der Azure CLI mit einem Konto an, das auf das Modell des Projekts zugreifen kann:

az login

Referenz: Melden Sie sich mit Azure CLI an.

Die Toolkit-Anmeldung wählt das Projekt für Erweiterungsvorgänge aus. Der lokale Agentprozess benötigt ebenfalls eine unterstützte Anmeldeinformation. Weitere Optionen finden Sie unter DefaultAzureCredential für Python oder Anmeldeinformationsketten für .NET.

Lokales Ausführen des gehosteten Workflows

Verwenden Sie die generierte Debugkonfiguration, um den HTTP-Server zu starten und den Agent Inspector zu öffnen. Durch das Öffnen des Agent Inspector allein wird der Server nicht gestartet.

1. Kehren Sie zum generierten Projektarbeitsbereich zurück.
2. Legen Sie einen Haltepunkt im Workflowcode fest, wenn Sie die Ausführung prüfen möchten.
3. Drücken Sie F5. Wenn Sie dazu aufgefordert werden, wählen Sie "HTTP-Server für lokalen Agent debuggen" aus.
4. Warten Sie, bis der Server gestartet wird, und der Agent-Inspektor wird geöffnet.
5. Senden Sie die Testanforderung für Ihr Beispiel.
6. Überprüfen Sie die Antwort, und wiederholen Sie sie mit einer anderen Anforderung. Wenn Sie einen Haltepunkt festlegen, überprüfen Sie die Werte, und setzen Sie die Ausführung fort.

Nachdem das Beispiel funktioniert, ändern Sie den Workflow, und wiederholen Sie den lokalen Test. Wenn Sie Tools hinzufügen, senden Sie eine Anforderung, die ein echtes Toolergebnis erfordert, und prüfen Sie den Anruf. Eine reine Modellantwort oder eine simulierte Antwort belegt nicht, dass das Live-Tool funktioniert.

Der Screenshot zeigt einen toolfähigen lokalen Agent, nicht eines der Workflowbeispiele. Der Agent Inspector zeigt seine Antwort und Toolaufrufe zusammen mit einem Latenz-Wasserfall und einer Ausführungszeitleiste an. Die verfügbaren Inspektionsdetails hängen vom aktiven Agenten und dessen Instrumentierung ab.

Wenn Sie GitHub Copilot verwenden, können Sie /validate-microsoft-foundry-hosted-agent in Copilot Chat ausführen, um das Projekt anhand der Foundry-Best-Practices zu prüfen. Dieser Chatbefehl öffnet einen Bericht; es handelt sich nicht um einen Terminalbefehl oder einen Ersatz für die Ausführung des Workflows.

Die generierten Aufgaben verwenden den Port 8088 für den Agentserver. Python Debugging verwendet auch Port 5679. Wenn beim Start ein Portkonflikt gemeldet wird, beenden Sie den konfliktierenden Prozess, den Sie besitzen, oder passen Sie die generierte Aufgabenkonfiguration konsistent an.

Ausführen ohne den Debugger

Zur manuellen Ausführung öffnen Sie ein Terminal im Quellverzeichnis des Beispiels, wobei dessen Abhängigkeiten, Umgebungsvariablen und Azure-Anmeldeinformationen verfügbar sein müssen.

python main.py

$env:ASPNETCORE_URLS = "http://localhost:8088"
dotnet run

set ASPNETCORE_URLS=http://localhost:8088
dotnet run

export ASPNETCORE_URLS="http://localhost:8088"
dotnet run

Führen Sie dann Foundry Toolkit: Agent Inspector öffnen über die Befehlspalette aus und stellen Sie eine Verbindung mit dem lokalen Server über Port 8088 her. Ausführen eines Beispiels mit python oder dotnet run startet einen lokalen Prozess, nicht einen Container.

Visualisieren der Workflowausführung des gehosteten Agents

Verwenden Sie den Agent Inspector, um die Ereignisse, Antworten und Tool-Aufrufe zu untersuchen, die Ihr laufender Agent ausgibt. Wenn die Laufzeit Workflow-Ereignisse erzeugt, verwenden Sie die Workflow-Visualisierung, um die Abfolge der Schritte nachzuvollziehen.

Die verfügbaren Details hängen von der Instrumentierung des Beispiels ab. Befolgen Sie die Telemetrieeinrichtungsanweisungen des Beispiels für laufzeitspezifische Anforderungen.

In diesen Schritten wird das Antwortprotokoll verwendet. Andere Beispiele benötigen Clients, die ihrem Protokoll entsprechen: Die HTTP-Aufrufansicht ist kein WebSocket-Client, und Python Aktivitätsbeispiele verwenden Microsoft 365 Agents Playground. Folgen Sie den Lokalen Testanweisungen des ausgewählten Beispiels. Das Ändern eines Protokollnamens in der Konfiguration fügt dieses Protokoll nicht zu Ihrem Server hinzu. Siehe Wählen Sie ein Protokoll für gehosteten Agent aus.

Bereitstellen des gehosteten Agents

Nachdem sich der lokale Workflow wie erwartet verhält, stellen Sie ihn aus dem Projektarbeitsbereich bereit. Python und C# teilen das Bereitstellungsverfahren. Beginnen Sie mit dem Paketmodus Code und Remote, um den Quellcode hochzuladen und Foundry die Abhängigkeiten wiederherstellen zu lassen.

Vorbereiten der Bereitstellungskonfiguration

Überprüfen und speichern Sie den Hosted-Agent-Dienst in azure.yaml. Bewahren Sie die Protokollkonfiguration des Beispiels auf, und deklarieren Sie die Modellbereitstellung und andere erforderliche Laufzeiteinstellungen dort.

Bei der Bereitstellung werden deklarierte Umgebungswerte aus dem .env des Quellverzeichnisses oder der Prozessumgebung aufgelöst. Es leitet nicht jeden lokalen .env Eintrag weiter. Die Plattform stellt reservierte Laufzeitwerte wie FOUNDRY_PROJECT_ENDPOINT bereit; deklarieren Sie sie nicht erneut als Bereitstellungseinstellungen. Siehe Plattforminjizierte Umgebungsvariablen.

Überprüfen Sie die Regeln zum Ignorieren des Quellverzeichnisses vor dem Verpacken. Halten Sie .env, Anmeldeinformationen, virtuelle Umgebungen und Caches aus dem Paket heraus. Bei der ZIP-Bereitstellung ersetzt eine source-root-Datei .agentignore die Regeln in .gitignore und .dockerignore, daher behalten Sie die erforderlichen Ausschlüsse bei, wenn Sie diese Datei hinzufügen.

Quellcode im Remote-Paketmodus bereitstellen

Verwenden Sie den generierten Arbeitsbereichsstamm, damit das Toolkit die Dienstkonfiguration lesen und das Quellverzeichnis suchen kann.

1. Beenden Sie die lokale Debugsitzung.

2. Wählen Sie "Developer Tools>Build>Deploy to Microsoft Foundry" aus. Sie können Foundry Toolkit: Deploy Hosted Agent auch über die Befehlspalette ausführen.

   

3. Wenn Foundry Project Setup angezeigt wird, wählen Sie das Abonnement und project und dann "Weiter" aus. Stellen Sie andernfalls sicher, dass das Standardprojekt das beabsichtigte Ziel ist.

4. Wählen Sie unter "Grundlagen"die Option "Code als Bereitstellungsmethode " und "Remote als Paketmodus" aus.

5. Wählen Sie "Neuer Agent" aus, und geben Sie den Namen des gehosteten Agents ein. Um einen bereitgestellten Agent zu aktualisieren, wählen Sie den vorhandenen Agent aus, und wählen Sie stattdessen diesen Agent aus.

   

6. Wählen Sie Weiteraus.

7. Prüfen Sie unter Review + DeploySprache, Laufzeitversion, Einsprungpunkt und CPU und Arbeitsspeicher anhand des Beispiels. Vergewissern Sie sich, dass das Quellverzeichnis dem Pfad des Diensts project entspricht.

   Der folgende Screenshot zeigt ein Beispiel mit Python 3.14 und dem ausgeblendeten Einstiegspunkt und nicht den Einstellungen für diese Workflowbeispiele. Verwenden Sie für Python Python 3.13 mit python3 main.py. Verwenden Sie für C# .NET 10 und den erkannten Einstiegspunkt für Ihr generiertes Projekt.

   

8. Klicken Sie auf Bereitstellen. Verfolgen Sie den Fortschritt in Benachrichtigungen und in der Ausgabe.

9. Fahren Sie mit dem Testen des bereitgestellten Workflows fort.

Stimmen Sie die Laufzeit mit Der Beispielkonfiguration und der lokalen Umgebung überein. Akzeptieren Sie keine andere Laufzeit, nur weil dies die Standardauswahl des Assistenten ist.

Das Toolkit speichert Bereitstellungsoptionen, wenn Sie das Formular übermitteln. Diese lokalen Einstellungen belegen nicht, dass die Cloudbereitstellung erfolgreich war. Durch das Aktualisieren eines vorhandenen Agents wird eine neue Version erstellt, anstatt eine frühere Version zu ändern.

Auswählen eines anderen ZIP-Paketmodus

Das Toolkit bietet die folgenden Paketoptionen für Quellcode:

Die auswählbaren ZIP-Laufzeiten sind Python 3.13, Python 3.14 und .NET 10. Stimmen Sie die Laufzeit mit Ihrem Code und Ihren Abhängigkeiten überein. Layouts, Grenzwerte und Dienstanforderungen finden Sie unter Bereitstellen aus Quellcode. Informationen zur Laufzeitunterstützungsrichtlinie finden Sie unter "Unterstützte Laufzeiten für gehostete Agent".

Bereitstellen eines Containerimages

Wählen Sie "Container für Grundlagen" aus, wenn Sie ein benutzerdefiniertes Laufzeitimage benötigen oder bereits über ein kompatibles Image verfügen.

Bei den Build-Optionen sollten Sie das Dockerfile und den Build-Kontext überprüfen, bevor Sie die Anwendung bereitstellen. Wenn Sie im Assistenten ein Dockerfile generieren, überprüfen Sie die Datei und wählen Sie Weiter und bereitstellen. Diese Optionen verwenden Remote-ACR-Builds, nicht lokale Docker-Builds.

Benutzerdefinierte Registrierungsoptionen verwenden eine Registrierung im ausgewählten Abonnement. Der Buildpfad für die benutzerdefinierte Registry erfordert Zugriff auf öffentliche Netzwerke; der Buildpfad mit vorgefertigtem Image hat gesonderte Anforderungen an private Netzwerke. Wenn Sie ein Image auswählen, wird die Netzwerkkonnektivität nicht konfiguriert.

Überprüfen Sie containeranforderungen und anleitungen für private Netzwerke , bevor Sie eine benutzerdefinierte Registrierung verwenden. Diese Bereitstellungen betreffen den Foundry Agent Service, nicht den eingestellten Hosted-Agent-Pfad für Azure Container Apps. Um einen älteren Agenten zu verschieben, befolgen Sie Migration von gehosteten Agents-Vorschau.

Testen des bereitgestellten Workflows

Eine erfolgreiche Erstellungsanforderung beweist nicht, dass die Laufzeit bereit ist oder dass das Modell und die Tools erreichbar sind. Testen Sie die genaue bereitgestellte Version.

1. Wählen Sie unter "MeineRessourcen-Agents>>gehosteter Agent" den Namen des Agents aus.
2. Wählen Sie die nummerierte Version aus, die Sie gerade bereitgestellt haben.
3. Warten Sie unter Details, bis der Bereitstellungsstatus anzeigt, dass der Agent läuft. Wenn ein Fehler auftritt, überprüfen Sie die Bereitstellungsausgabe, bevor Sie den Vorgang wiederholen.
4. Öffnen Sie Playground , und senden Sie die gleiche Anforderung, die Sie lokal getestet haben.
5. Überprüfen Sie die Antwort. Wenn Sie Tools hinzugefügt haben, senden Sie eine Anforderung, die diese Tools erfordert, und prüfen Sie die Anrufe.

Lokale und Cloudausführungen verwenden unterschiedliche Anmeldeinformationen, Abhängigkeitsumgebungen und Netzwerkpfade. Eine erfolgreiche lokale Antwort garantiert keine erfolgreiche Remoteantwort.

Überprüfen und Aktualisieren des bereitgestellten Agents

Verwenden Sie den Remote-Playground, um Ihren bereitgestellten Agent zu testen und zu prüfen. Im Gegensatz zu lokalen Tests mit Agent Inspector werden Anforderungen in diesem Playground für den in Foundry gehosteten Agent ausgeführt.

1. Wählen Sie im Foundry Toolkitdie Option Developer Tools>Build>Hosted Agent Playground aus.

   

2. Wählen Sie im Dropdownmenü "Gehosteter Agent " Ihren bereitgestellten Agent und die zu prüfende Version aus. Öffnen Sie Playground , um eine Anforderung zu senden und die Antwort- und Sitzungsdetails anzuzeigen.

   Der folgende Screenshot zeigt die beispielhafte Antwort eines bereitgestellten Agenten, nicht die erwartete Ausgabe keines der beiden Workflowbeispiele. Agent- und Sitzungsbezeichner werden ausgeblendet.

   

Verwenden Sie diese Steuerelemente, um den Agent zu prüfen und zu aktualisieren. Die verfügbaren Registerkarten hängen von ihren Protokoll- und verbundenen Diensten ab.

Verwenden Sie Traces und Bewertung, sofern verfügbar, zur Untersuchung und Qualitätsbewertung über eine einzelne erfolgreiche Antwort hinaus. Erfüllen Sie die Voraussetzungen für Hosted-Agent-Tracing und Hosted-Agent-Evaluierung.

Die Bereitstellung weist dem Agenten einen Endpunkt zur programmgesteuerten Verwendung zu. Für den API-Zugriff ist kein separater Publikationsschritt erforderlich. Das Veröffentlichen in Teams oder Microsoft 365 ist eine separate Aufgabe. Siehe den aktuellen Agent-Endpunkt und das Veröffentlichungsmodell.

Troubleshooting

Verwenden Sie den gemeldeten Fehler und die Beispielkonfiguration, um den fehlerhaften Schritt zu identifizieren.

Bereinigen von Ressourcen

Beenden Sie die lokale Debugsitzung, wenn Sie fertig sind. Wenn Sie den bereitgestellten Test-Agent nicht mehr benötigen, folgen Sie "Gehostete Agents verwalten", um ihn zu entfernen.

Durch das Löschen des Agenten werden seine Versionen gelöscht und aktive Sitzungen beendet. Es werden nicht alle zugeordneten Azure Ressource entfernt.

Löschen Sie nur Cloudressourcen, die für diese Übung erstellt wurden, die keine anderen Anwendungen verwenden. Löschen Sie kein freigegebenes Foundry-Projekt, keine Modellbereitstellung und keine Container-Registry.

Verwandte Inhalte

Verwenden Sie die folgenden Leitfäden, um Ihren Workflow zu erweitern:

• Microsoft-Agent-Framework-Workflows
• Gehostete Agentenkonzepte
• Erstellen Sie einen Prompt-Agenten