Initialisieren eines gehosteten Agent-Projekts mit der Azure Developer CLI

Important

Die in diesem Artikel markierten Elemente (Vorschau) sind aktuell als öffentliche Vorschau verfügbar. Diese Vorschauversion wird ohne Vereinbarung zum Servicelevel bereitgestellt und sollte nicht für Produktionsworkloads verwendet werden. Manche Features werden möglicherweise nicht unterstützt oder sind nur eingeschränkt verwendbar. Weitere Informationen finden Sie unter Supplementale Nutzungsbedingungen für Microsoft Azure Previews.

Verwenden Sie azd ai agent init, um ein Grundgerüst für ein gehostetes Agentprojekt mit den Dateien zu erstellen, die Sie benötigen, um einen KI-Agenten für Microsoft Foundry zu erstellen, zu testen und bereitzustellen. In diesem Artikel wählen Sie einen Ausgangspunkt und initialisieren das Projekt anhand einer Vorlage, mit Ihrem eigenen Code oder auf Basis eines vorhandenen Foundry-Projekts.

Voraussetzungen

Auswählen eines Ausgangspunkts

Es gibt drei Möglichkeiten, ein Projekt zu beginnen. Wählen Sie den Pfad aus, der Ihrer Situation entspricht.

Consideration Mit einer Vorlage beginnen Verwenden von eigenem Code Verbinden eines vorhandenen Projekts
Am besten geeignet für: Neue Agenten, machen sich mit den Tools vertraut. Vorhandener Agentcode, den Sie auf Foundry hosten möchten. Agents, die bereits in einem Foundry-Projekt ausgeführt werden.
Befehl azd ai agent init in einem leeren Verzeichnis. azd ai agent init in einem Verzeichnis mit vorhandenem Code. azd ai agent initund wählen Sie dann ein vorhandenes Projekt aus.
Was Sie bekommen Ein vollständiges Gerüstprojekt: eine einzelne azure.yaml Agentquelle unter src/<agent-name>/ und ein Dockerfile für die Containerbereitstellung. Die Infrastruktur ist standardmäßig ohne Bicep und kann später ausgeworfen werden. Ein generierter azure.yaml Serviceeintrag und für die Containerbereitstellung ein Dockerfile, das Ihren Code kapselt. Die Infrastruktur ist standardmäßig ohne Bicep und kann später ausgeworfen werden. Ein azure.yaml, das mit Ihrem bestehenden Foundry-Projekt verbunden ist. Die Infrastruktur ist standardmäßig ohne Bicep und kann später ausgeworfen werden.
Codeänderungen Keiner. Ausführungsbereit. Möglicherweise benötigen Sie einen Protokolladapter. Keiner.

Aus einer Vorlage initialisieren

Führen Sie den interaktiven Assistenten in einem leeren Verzeichnis aus, und wählen Sie " Neu starten" aus einer Vorlage aus:

azd ai agent init

Der Assistent führt Sie durch die folgenden Auswahlmöglichkeiten.

Prompt Description
Agent-Vorlage Wählen Sie aus Vorlagen, die nach Framework und Sprache organisiert sind (Python oder .NET).
Azure-Abonnement Das Abonnement, das zum Suchen oder Erstellen eines Foundry-Projekts verwendet wird.
Gießereiprojekt Wählen Sie ein vorhandenes Projekt aus, oder erstellen Sie ein neues Projekt. Wenn Sie einen erstellen, wählen Sie auch eine Region aus.
Modellbereitstellung Wählen Sie eine vorhandene Modellbereitstellung aus, oder es wird eine aus den Standardwerten der Vorlage erstellt.

Der Agentname stammt aus der Vorlage. Die CLI erstellt eine azd Umgebung namens <directory>-dev und konfiguriert sie mit Details aus Ihrem ausgewählten Foundry-Projekt. Jede Vorlage enthält Agentquellcode, a Dockerfileund eine azure.yaml Datei, die als einheitliches Projektmanifest für das Projekt und die azd Konfiguration des gehosteten Agents fungiert.

Aus einer azure.yaml-URL initialisieren

Wenn Sie ein bestimmtes Agent-Beispiel haben, verweisen Sie -m auf das azure.yaml des Beispiels. Die CLI übernimmt diese Datei als Projektmanifest und lädt die referenzierte Agentquelle herunter.

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

Note

Agentmanifeste (agent.manifest.yaml) und eigenständige Agentdefinitionen (agent.yaml) sind veraltet. Ab den Foundry-Erweiterungen azd (azure.ai.agents 1.0.0-beta.1) leben alle gehosteten Agent-Konfigurationen in einem einzigen azure.yaml. Siehe Erstellen von azure.yaml für gehostete Agenten.

Die -m Option akzeptiert weiterhin eine Legacy-Agent-Manifest-URL, aber aktuelle Beispiele veröffentlichen eine einheitliche azure.yaml.

Angeben eines Modells

Wählen Sie bei der Initialisierung ein Modell aus:

azd ai agent init --model gpt-4.1

Oder verwenden Sie eine vorhandene Modellbereitstellung in Ihrem Foundry-Projekt:

azd ai agent init --model-deployment my-deployment

Auswählen eines Bereitstellungsmodus

Standardmäßig verwendet azd ai agent init die Codebereitstellung für Python- und .NET-Projekte. Bei der Codebereitstellung wird Ihr Quellcode als ZIP-Paket hochgeladen. Um stattdessen ein containerbasiertes Projektgerüst zu erstellen, übergeben Sie --deploy-mode container:

azd ai agent init --deploy-mode container

Um ein vorgefertigtes Container-Image bereitzustellen, übergeben Sie --image und --agent-name. Mit dieser Option werden Vorlagen und Sprachauswahl, Codegerüst, Dockerfile-Generierung und Azure Container Registry Setup übersprungen.

azd ai agent init --agent-name my-agent --image myregistry.azurecr.io/my-agent:v1

Vorlagen nicht interaktiv durchsuchen

Um den Katalog zu prüfen, bevor Sie das Gerüst erstellen, oder um azd ai agent init über ein Skript zu steuern, listen Sie den Katalog auf:

# Everything in the catalog
azd ai agent sample list

# Just the featured Python agent samples
azd ai agent sample list --featured-only --language python --type agent

# Full azd templates only, as JSON for scripting
azd ai agent sample list --type azd --output json

Jeder Eintrag enthält ein ausführungsbereites initCommand, das Sie kopieren und in dem Verzeichnis ausführen, in dem Sie das Gerüst erstellen möchten.

Tip

Wenn Sie ein Beispiel mit einer anderen Foundry-Agent-Identität wiederverwenden, übergeben Sie --agent-name <new-name> an azd ai agent init, damit der in azure.yaml geschriebene Name nicht mit dem Standardnamen des Beispiels kollidiert.

Initialisieren aus vorhandenem Code

Wenn Sie bereits Python- oder .NET-Agent-Code haben, führen Sie azd ai agent init im Verzeichnis aus, das Ihren Code bereits enthält:

cd my-agent/
azd ai agent init

Die CLI erkennt die vorhandenen Dateien und generiert einen azure.yaml Diensteintrag um sie herum, ohne den Code zu überschreiben. Für die Bereitstellung von Containern fügt es außerdem eine Dockerfile hinzu. Die Infrastruktur bleibt standardmäßig ohne Bicep, es sei denn, Sie generieren später Infrastructure as Code.

Ihr Agentcode muss den Vertrag für die Laufzeit des gehosteten Agents erfüllen:

  • Lauschen Sie auf Port 8088.
  • Stellen Sie einen Integritätstest unter GET /readiness bereit.
  • Behandeln Sie eines der unterstützten Protokolle (responses oder invocations).

Wenn Ihr Code noch keins dieser Protokolle spricht, fügen Sie einen Protokolladapter hinzu, einen einfachen SDK-Wrapper, der zwischen dem Foundry-Protokoll und der Logik Ihres Agents übersetzt wird.

Um einem vorhandenen azd-Projekt einen Agenten hinzuzufügen, erkennt init das Projekt und fügt Ihrem vorhandenen azure.yaml einen neuen Diensteintrag hinzu. Wird --src verwendet, um ein Unterverzeichnis anzugeben:

azd ai agent init --src src/my-agent

Herstellen einer Verbindung mit einem vorhandenen Foundry-Projekt

Um ein vorhandenes Foundry-Projekt über azd zu verwalten, führen Sie den Assistenten aus und wählen Sie die Option aus, eine Verbindung mit einem vorhandenen Projekt herzustellen. Sie können die interaktive Auswahl auch überspringen, indem Sie die Azure Ressourcen-ID des Projekts direkt angeben:

azd ai agent init --project-id /subscriptions/{sub}/resourceGroups/{rg}/providers/Microsoft.CognitiveServices/accounts/{account}/projects/{project}

Um die project-ID zu finden, öffnen Sie das Foundry-Portal, wechseln Sie zu "Verwalten>Project Details", und kopieren Sie den Wert der Ressourcen-ID.

Warning

Wenn Sie mit --project-id für ein vorhandenes Projekt initialisieren, überspringt das Tool die automatischen Rollenzuweisungen, die beim Erstellen eines neuen Projekts vorgenommen werden. Stellen Sie sicher, dass die erforderlichen Rollen bereits zugewiesen sind. Die vollständige Matrix finden Sie unter Berechtigungsreferenz für gehostete Agents.

Überprüfen, was erstellt wird

Nachdem init abgeschlossen ist, enthält Ihr Projektverzeichnis die folgende Struktur:

.
|-- azure.yaml                  # Unified azd project and hosted agent configuration
|-- src/
|   \-- <agent-name>/
|       |-- Dockerfile          # Container build definition
|       \-- ...                 # Agent source code
|-- .azure/                     # Environment configuration
\-- infra/                      # Optional IaC, created only after you eject infrastructure

Vorlagen und Beispiele veröffentlichen eine einheitliche azure.yaml-Datei im Projektstamm. Während des Inits azd übernimmt oder generiert diese Datei. Sie arbeiten künftig mit azure.yaml. Die Infrastruktur ist standardmäßig ohne Bicep. Werfen Sie die Infrastruktur nur aus, wenn Sie die generierten IaC-Dateien direkt verwalten müssen.

Verwandte Inhalte

  • Last updated on