Agententwicklung mit der Azure Developer CLI

Die Azure Developer CLI (azd) und die Erweiterung azd ai agent bieten Ihnen einen einzigen Befehlszeilenworkflow, der von der Idee zu einem produktionsbereiten gehosteten Agent auf Microsoft Foundry wechselt. In diesem Artikel werden die Entwicklerreise, die Dateien, die einen Agent definieren, und die wichtigsten Konzepte erläutert, die Sie unterwegs treffen.

Dieser Artikel richtet sich an Entwickler, die einen terminalorientierten, skriptfähigen Workflow dem Foundry-Portal oder Sprach-SDKs vorziehen.

Die Entwicklerreise

Der azd ai Workflow folgt demselben Lebenszyklus, unabhängig davon, ob Sie einen kleinen Prototyp oder einen Produktionsagenten erstellen. Sie erstellen einmalig ein Projektgerüst und kombinieren dann Befehle, wenn Ihr Projekt wächst.

Agenttypen

Die azd ai agent Erweiterung konzentriert sich auf gehostete Agents.

Gehostete Agents bieten Ihnen vollständige Kontrolle über die Laufzeit-, Framework- und Toolintegrationen, während Foundry Infrastruktur, Skalierung und Sitzungsverwaltung verarbeitet.

Konfigurationsdateien

Drei Dateien definieren, wie ein Agent erstellt und bereitgestellt wird.

Der wesentliche Unterschied besteht darin, dass agent.yaml beschreibt, was Ihr Agent ist, während azure.yaml beschreibt, wie er bereitgestellt wird.

Ressourcen, die im Foundry-Projekt selbst leben, z. B. Verbindungen, Toolboxen, Fähigkeiten und Routinen, werden über direkte azd ai Befehle verwaltet, anstatt in agent.yamldeklariert.

Variablenersetzung

Es werden zwei Variablensyntaxen in Agentprojektdateien angezeigt:

• ${VAR_NAME} ist ein azd Umgebungsvariablenplatzhalter. Es wird zur Bereitstellungszeit aus .azure/<env>/.env aufgelöst, sodass dasselbe agent.yaml in Umgebungen wie dev, staging und production funktioniert.
• {{ parameter }} ist ein Manifestvorlagenparameter. Die Auflösung erfolgt während azd ai agent init, wenn aus einer Vorlage ein konkretes Projekt erstellt wird.

Wo die CLI ausgeführt wird

Die azd ai Befehle funktionieren sowohl innerhalb als auch außerhalb eines azd Projektverzeichnisses:

• Innerhalb eines azd Projekts lösen Befehle den Foundry-Projektendpunkt aus der aktiven azd Umgebung auf.
• Legen Sie außerhalb eines azd-Projekts den aktiven Kontext einmal mit azd ai project set <endpoint> fest, oder geben Sie --project-endpoint bei einem einzelnen Ressourcenbefehl an (connection, toolbox, skill oder routine). Als Fallback liest azd ai die FOUNDRY_PROJECT_ENDPOINT-Umgebungsvariable.
• Eine projektinterne Umgebung hat immer Vorrang vor dem globalen Kontext, sodass ein Wechsel in ein Projektverzeichnis die CLI auf den Endpunkt dieses Projekts ausrichtet.

Protokolle

Ein Protokoll definiert den HTTP-Vertrag zwischen Foundry und Ihrem Agent-Container. Ihr Agent lauscht auf Port 8088 und stellt unabhängig vom verwendeten Protokoll eine Health-Probe bereit.

Die vollständige Spezifikation finden Sie unter Vertrag für die Laufzeit des gehosteten Agents.

Sitzungen und Unterhaltungen

Sitzungen werden anhand von session_id identifiziert. Wenn Sie ausführen azd ai agent invoke, verwendet Foundry die Sitzung standardmäßig aus dem letzten Aufruf. Verwenden Sie --new-session, um neu zu beginnen, oder --session-id <id>, um eine bestimmte Sitzung anzusteuern.

Ressourcen für ein Foundry-Projekt

Ein Foundry-Projekt beherbergt mehr als Agenten. Sie enthält auch gemeinsam genutzte Ressourcen, auf die Agenten zur Laufzeit zugreifen. Die CLI verwaltet jeden über eine dedizierte Befehlsgruppe.

Diese Ressourcen werden für Entwickler und Agents im selben Projekt freigegeben. Jede Befehlsgruppe stellt die Standardverben create, update, delete, show und list bereit.

Bewerten und Verbessern eines Agenten

Nachdem ein Agent ausgeführt wurde, helfen Ihnen zwei zugehörige Workflows dabei, seine Qualität zu messen und zu verbessern:

• Die Evaluation führt Ihren Agenten gegen einen Datensatz aus, bewertet die Antworten mit einem oder mehreren Evaluatoren und liefert ein aggregiertes Qualitätssignal. Sie verwalten es mit azd ai agent eval.
• Die Optimierung schreibt iterativ die Aufforderung Ihres Agenten um, ein Auswertungssignal aufzuheben. Es verwendet eine Bewertung als objektive Funktion und erzeugt eine Kandidatenaufforderung, die Sie überprüfen und akzeptieren. Sie verwalten es mit azd ai agent optimize.

Einzelheiten finden Sie unter Agentbewertungen mit der azd CLI ausführen und Agentprompts optimieren.

Bereitstellungslebenszyklus

Die vollständige Entwicklerschleife wird in einer kurzen Sequenz von Befehlen zusammengefasst. Erstellen Sie ein Gerüst einmal, und verwenden Sie dann die direkten Befehle, wenn Ihr Projekt wächst.

# Scaffold a project from a template or your existing code
azd ai agent init

# Run locally and invoke
azd ai agent run
azd ai agent invoke --local "Hello, world!"

# Provision infrastructure and deploy the agent
azd up

# Extend the project with shared resources at any time
azd ai connection create my-search --kind cognitive-search --target https://... --auth-type api-key --key "..."
azd ai routine create daily-digest --trigger recurring --cron "0 7 * * *" --agent-name my-agent

# Evaluate quality
azd ai agent eval generate
azd ai agent eval run

# Tear down all Azure resources
azd down

Verwandte Inhalte

• Schnellstart: Bereitstellen Ihres ersten gehosteten Agents
• Was sind gehostete Agenten?
• Laufzeitvertrag für gehostete Agenten
• Lebenszyklus der Agententwicklung