Agententwicklung mit der Azure Developer CLI

Important

Elemente, die in diesem Artikel als Vorschau gekennzeichnet sind, befinden sich derzeit in der Vorschau. Diese Vorschauversion wird ohne Service Level Agreement bereitgestellt, und Microsoft empfiehlt ihren Einsatz nicht für Produktionsworkloads. 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.

Die Azure Developer CLI (azd) und die Erweiterung azd ai agent bieten Ihnen einen einzigen Befehlszeilenworkflow, der von der Idee zu einem produktionsbereiten Agent auf Microsoft Foundry wechselt. Sie können codebasierte gehostete Agents und deklarative promptbasierte Sprach-Agents entwickeln. 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.

Stage Was Sie tun Weitere Informationen
Install Installiere azd und die Foundry-Erweiterungen. Einrichten Ihrer Entwicklerumgebung
Gerüst Initialisieren Sie einen gehosteten Agent aus einer Vorlage oder Ihrem vorhandenen Code, oder erstellen Sie einen promptbasierten VoIP-Agent. Schnellstart: Bereitstellen eines gehosteten Agenten oder Schnellstart: Erstellen eines Prompt-Voice-Agenten
Definieren Konfigurieren Sie den Agent, Modellbereitstellungsabhängigkeiten, Protokolle, Tools und Umgebung in azure.yaml. Erstellen Sie azure.yaml für gehostete Agenten
Entwickeln Schreiben Sie Agentlogik, fügen Sie Tools mithilfe einer Toolbox hinzu, und testen Sie lokal. Toolboxübersicht
Bereitstellen Stellen Sie die Infrastruktur bereit, und führen Sie die Bereitstellung in Foundry durch. Bereitstellen eines gehosteten Agents
Betreiben Überwachen sie Protokolle, verwalten Sie Versionen und automatisieren Sie die Ausführung. Verwalten von gehosteten Agents
Evaluieren Messen Sie die Agent-Qualität, und verbessern Sie den Prompt. Ausführen von Agent-Auswertungen mit der azd CLI

Agenttypen

Die azd ai agent Erweiterung unterstützt gehostete, Prompt- und Sprach-Agents.

Typ Description Wann verwenden?
Bereitgestellter Agent Eine Anwendung, die Sie als Quellcode oder als Containerimage bereitstellen. Sie benötigen benutzerdefinierte Logik, Frameworkintegration oder vollständige Kontrolle über das Verhalten.
Prompt-Agent Ein Agent wurde vollständig durch Anweisungen und Toolkonfigurationen ohne benutzerdefinierten Code definiert. Sie möchten einen schnellen, konfigurationsgesteuerten Agent ohne Schreiben von Anwendungscode.
Sprachagent Ein deklarativer Prompt-Sprachagent oder ein Sprach-Wrapper, der eine Verbindung mit einem gehosteten Agenten herstellt. Sie benötigen eine Echtzeit-Spracherfahrung über einen Voice Live-Client.

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

Eingabeaufforderungsbasierte VoIP-Agents erfordern keinen benutzerdefinierten Container. Wenn Sie eine benutzerdefinierte Sprach-zu-Sprache- oder kaskadierte Audiopipeline in Ihrem eigenen Container ausführen müssen, erstellen Sie einen VoIP-Agent mit einem gehosteten Agent , und verwenden Sie das invocations_ws Protokoll.

Verwenden Sie den gehosteten VoIP-Wrapper-Workflow, um die Unterhaltungslogik in einem gehosteten Text-Agent beizubehalten, während Voice Live Audio behandelt. Der Wrapper und das Ziel sind getrennte Dienste im selben azure.yaml-Projekt. Dieser Fluss ersetzt nicht den vorhandenen benutzerdefinierten invocations_ws Audiopipelinefluss.

Bevor Sie die Sprach-CLI-Optionen der öffentlichen Vorschau verwenden, überprüfen Sie Ihre installierte Erweiterung wie in den Voraussetzungen für den Schnellstart des Sprach-Agents beschrieben.

Konfigurationsdateien

Ein gehostetes Agentprojekt verwendet eine azure.yaml Datei im Projektstamm, um sowohl den Agent als auch das Bereitstellungs- und Bereitstellungsmodell zu deklarieren. Die Datei verwendet ein Modell mit aufgeteilten Diensten, bei dem jeder benannte Dienst einen host-Wert wie azure.ai.project, azure.ai.agent, azure.ai.connection, azure.ai.toolbox, azure.ai.skill oder azure.ai.routine hat.

Datei Purpose Wer verwaltet es
azure.yaml Deklariert das Foundry-Projekt, Modellbereitstellungen, gehosteten Agentdienst, Abhängigkeiten, Protokolle, Tools, Umgebungsvariablen, Containerressourcen und Bereitstellungseinstellungen. Agentidentität, Modell, Protokolle, Tools und Umgebungswerte leben im azure.ai.agent Dienst. Die Initialisierung generiert dies. Sie passen sie nach Bedarf an.

Der azure.ai.agent-Dienst definiert Ihren Agent inline oder über ein explizites Root-$ref für eine direkte YAML- oder JSON-Definition. Verwenden Sie azd ai agent add <service> --file <path> für einen dateigestützten Dienst. Parametrisierte AgentManifest Wrapper werden von der aktuellen Initialisierung nicht unterstützt. Die Liste des Dienstes uses: verweist auf Abhängigkeiten wie Projekt, Verbindungen und Toolboxen.

Für einen promptbasierten Sprachagenten speichert azure.yaml die deklarative Agent-Definition, einschließlich kind: prompt-voice, des Modells, des Modelltyps und des Agentnamens. Es enthält keine Containerlaufzeit für gehostete Agents. Informationen zum Anpassen von Anweisungen, Audio, Turn-Erkennung, Transkription, Sprachausgabe, Tools und Begrüßungen finden Sie unter Konfigurieren eines VoIP-Agents.

Bei einem gehosteten VoIP-Wrapper conversationEngine.name wird auf den Dienstnamen des gehosteten Ziels verwiesen. Die Abhängigkeit des Wrappers uses bestimmt die Bereitstellungsreihenfolge, und conversationEngine.version verwendet standardmäßig die von der aktuellen Umgebung bereitgestellte Version. Weitere Informationen finden Sie in der Sprachdienstreferenz für die Konfigurationsfelder.

Variablenersetzung

Verwenden Sie ${VAR_NAME} in azure.yaml für Werte, die sich je nach azd-Umgebung unterscheiden. Der Platzhalter wird beim Bereitstellen oder zur Laufzeit aus .azure/<env>/.env aufgelöst, sodass dasselbe azure.yaml in Umgebungen wie dev, Staging und Produktion funktioniert.

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.
  • Ein nicht leerer Endpunkt, der aus der aktiven Umgebung aufgelöst wird, hat Vorrang vor dem globalen Kontext. Informationen zu Shell-Fallback und befehlsspezifischem Verhalten finden Sie unter Festlegen des Projektkontexts.

Protokolle

Ein Protokoll definiert den HTTP-Vertrag zwischen Foundry und Ihrem Agent-Container. Ihr Agent lauscht an Port 8088 und stellt unabhängig vom Protokoll einen Integritätstest bereit.

Protocol API-Stil Wann verwenden?
responses OpenAI-Antwort-API (POST /responses) Die Standardauswahl, kompatibel mit dem OpenAI API-Ökosystem.
invocations Benutzerdefinierter JSON-Vertrag (POST /invocations) Wenn Sie volle Kontrolle über Anforderungs- und Antwortnutzlasten benötigen.

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

Diese Protokolleinstellungen gelten für Gehostete Agent-Container. Promptbasierte Sprachagenten konfigurieren kein Hosted-Agent-Protokoll.

azd ai agent invoke implementiert keine Sprachunterhaltungen für eingabeaufforderungsbasierte VoIP-Agents oder gehostete VoIP-Wrapper. Informationen zum CLI-Verhalten und zum Testen finden Sie unter Einschränkungen des VoIP-Agents.

Sitzungen und Unterhaltungen

Konzept Description
Session Eine isolierte Ausführungsumgebung für eine einzelne Agentinteraktion. Jede Sitzung wird in einer eigenen Sandbox mit dedizierten Ressourcen ausgeführt.
Gespräch Nachrichtenverlauf für das Responses-Protokoll. Aufrufe speichern den Konversationsverlauf nicht automatisch.

Sitzungen werden anhand von session_id identifiziert. Die CLI speichert die Sitzungsauswahl pro Agent und verwendet sie standardmäßig wieder. Verwenden Sie --new-session, um neu zu beginnen, oder --session-id <id>, um eine bestimmte Sitzung anzusteuern. Der Cache ist nicht nach dem delegierten Benutzer indiziert. Behalten Sie bei Verwendung von --user-identity eine explizite Benutzer-zu-Sitzung-Zuordnung bei.

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.

Resource Was es ist Verwaltet mit
Connection Verknüpft ein Foundry-Projekt mit einer externen Ressource, z. B. einem MCP-Server, Azure KI-Suche oder dem Grounding mit Bing. azd ai connection-Befehle
Werkzeugkasten Eine benannte Sammlung von Werkzeugen, die Agenten zur Laufzeit verwenden. azd ai toolbox-Befehle
Skill Eine wiederverwendbare Verhaltensrichtlinie, die über Agenten im Projekt hinweg geteilt wird. azd ai skill-Befehle
Routine Ein Trigger plus eine Aktion, die einen Agent aufruft. azd ai routine-Befehle

Diese Ressourcen werden für Entwickler und Agents im selben Projekt freigegeben. Ihre Befehle unterscheiden sich: Verbindungen und Routinen haben update, Fähigkeiten veröffentlichen eine neue Version über update, und Toolboxes verwenden versionsproduzierende Verbindungs- und Fähigkeitsmutationen gefolgt von publish.

Bewerten und Verbessern eines Agenten

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

  • Die Schnelle Agent-Auswertung verwendet azd ai agent eval und einen lokalen eval.yaml-Workflow, einschließlich des Optimiererworkflows. Die Projektbewertung verwendet die separat installierte azd ai eval Erweiterung und evals/azure.eval.yaml, zusammen mit Ablaufverfolgungs- oder Datasetquellen und expliziten CI-Qualitätstoren. Die beiden Konfigurationsformate sind nicht austauschbar.
  • 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.

Befehlsgruppen nach Entwicklerjob

Wählen Sie einen Befehl für das gewünschte Ergebnis aus. Hängen Sie --help an, um die Flags und unterstützten Ausgabeformate zu überprüfen.

Job Commands Leitfaden
Ein Projekt und verwaltete Modelle konfigurieren azd ai project add, azd ai project deployment add Projektkonfiguration und Kontext
Endpunktkontext auswählen oder prüfen azd ai project set, azd ai project show, azd ai project unset, azd ai project context Die globale Endpunktauswahl ist von Infrastrukturdeklarationen getrennt. Die Kontextausgabe kann Geheimnisse enthalten.
Beispiele durchsuchen oder einen Agenten initialisieren azd ai agent sample list, azd ai agent init, azd ai agent add Gehostete, Prompt- und Sprachagenten initialisieren
Parsen, extrahieren und klassifizieren von Dokumenten und Inhalten für Agents azd ai cu analyze, azd ai cu analyzer Azure Content Understanding CLI-Schnellstart (Vorschau)
Lokal ausführen und prüfen azd ai agent run, azd ai inspector launch Lokale Entwicklung
Aufrufen, Delegieren der Benutzeridentität oder Senden von benutzerdefinierten Headern azd ai agent invoke Aufrufoptionen
Arbeit überprüfen, verfolgen oder abbrechen azd ai agent invocations show, azd ai agent invocations follow, azd ai agent invocations cancel Zeitintensiver Aufruf
Einen Endpunkt überprüfen oder aktualisieren azd ai agent endpoint show, azd ai agent endpoint update Endpoint- und Kartenupdates
Status überprüfen, Probleme diagnostizieren oder Protokolle lesen azd ai agent show, azd ai agent doctor, azd ai agent monitor Diagnostik und Protokolle
Einen Sandbox erstellen, auflisten, inspizieren, beenden oder löschen azd ai agent sessions create, azd ai agent sessions list, azd ai agent sessions show, azd ai agent sessions stop, , azd ai agent sessions delete Sitzungsverwaltung
Sandbox-Dateien bereitstellen, abrufen oder verwalten azd ai agent files upload, azd ai agent files download, azd ai agent files list, azd ai agent files mkdir, , azd ai agent files stat, azd ai agent files delete Sitzungsdateivorgänge
Bereitgestellten Quelltext wiederherstellen azd ai agent code download Code oder eine ZIP-Datei herunterladen
Dauerhafte Speicher überprüfen und freigegebene Elemente pflegen azd ai agent state-stores list, azd ai agent state-stores select, azd ai agent state-stores show, azd ai agent state-stores items Zustandsspeichervorgänge und Grenzwerte
Agentabhängigkeiten zur Bereitstellungskonfiguration hinzufügen azd ai agent connection add, azd ai agent toolbox add Beide Dienste müssen bereits in azure.yaml vorhanden sein; diese Befehle fügen uses Einträge hinzu, nicht Remoteressourcen.
Verwalten von Verbindungsanmeldeinformationen und Metadaten azd ai connection create, azd ai connection list, azd ai connection show, azd ai connection update, , azd ai connection delete Verbindungsauthentifizierung und Wartung
Erstellen, versionieren oder wiederverwendbare Fähigkeiten herunterladen azd ai skill add, azd ai skill create, azd ai skill update, azd ai skill list, azd ai skill show, , azd ai skill download, azd ai skill delete Skill-Workflows
Toolboxen erstellen und verwalten azd ai toolbox add, azd ai toolbox create, azd ai toolbox list, azd ai toolbox show, , azd ai toolbox delete Toolboxkonfiguration
Tool-Sammlungen entwickeln und bewerben azd ai toolbox connection, azd ai toolbox skill, azd ai toolbox versions list, azd ai toolbox publish Mutationen verzweigen von der neuesten Version; Promotion ist explizit.
Planen, Ausführen oder Prüfen von Routinen azd ai routine add, azd ai routine create, azd ai routine show, azd ai routine list, azd ai routine update, azd ai routine enable, azd ai routine disable, azd ai routine dispatch, azd ai routine run list, azd ai routine delete Routine-Workflows
Schnelle Auswertung generieren und ausführen azd ai agent eval generate, azd ai agent eval update, azd ai agent eval run, azd ai agent eval list, , azd ai agent eval show Schnelle Auswertung und Optimizer-Ressourcen
Einen Optimierungskandidaten verbessern und bereitstellen azd ai agent optimize, azd ai agent optimize status, azd ai agent optimize list, azd ai agent optimize cancel, , azd ai agent optimize apply, azd ai agent optimize deploy Optimierungsworkflow
Aktivitäts-Agent für Teams packen oder veröffentlichen azd ai agent pack, azd ai agent publish Teams-Verteilung
Gehostete Version oder Agent löschen azd ai agent delete Agentlöschung
Ein Projekt bewerten und Qualitätsschranken durchsetzen azd ai eval init, azd ai eval generate, azd ai eval create, azd ai eval run, azd ai eval dataset, , azd ai eval evaluator, azd ai eval job Projektbewertung; azure.ai.evaluationsseparat installieren.
Registrieren und Versionieren wiederverwendbarer Datensätze azd ai dataset Datenset-Lebenszyklus; azure.ai.dataset separat installieren.
Übermitteln, Anhalten, Fortsetzen, Abbrechen oder Bereitstellen von Feinabstimmungsaufträgen azd ai finetuning init, azd ai finetuning jobs Feinabstimmung; azure.ai.finetune separat installieren.
Hochladen und Verwalten von benutzerdefinierten Modellgewichtungen azd ai models Import und Wartung des benutzerdefinierten Modells; azure.ai.models separat installieren.

Jede Erweiterung, die Befehle hinzufügt, stellt version bereit; prüfen Sie stattdessen das microsoft.foundry Bundle mit azd ext list. Die Verbindungs-, Routine- und Qualifikationsgruppen stellen auch context für lokale Projekt- und Umgebungsüberprüfungen bereit; behandeln Sie die Ausgabe als potenziell empfindlich.

Verteilung der Aktivitäts-Agenten

Nach der Bereitstellung eines Activity-Protocol-Agents erstellt azd ai agent packappPackage.zip zum Querladen. Verwenden Sie --display-name, --app-version und --output-dir, um das Paket anzupassen. Verpacken ist nicht dasselbe wie Veröffentlichen.

azd ai agent publish veröffentlicht mit Microsoft 365. Einfache Aktivitäts-Agents verwenden standardmäßig die Verteilung shared, es sei denn, dies ist anders konfiguriert; --scope tenant erfordert eine Administratorgenehmigung. Digital Workers erfordern Mandantenumfang. Verwenden Sie wiederholbare --access-boundary Werte, --clear-access-boundaries zum Entfernen vorhandener Begrenzungen und wiederholbare --optional-permission-scope <resource-app-id>=<scope> Werte für optionale Berechtigungen. personal ist kein Veröffentlichungsumfang; verwenden Sie pack --scope personal und laden Sie das Paket per Sideloading für Benutzertests.

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.

Informationen zum Pfad des verwalteten VoIP-Agents finden Sie in der Schnellstartanleitung: Erstellen eines Eingabeaufforderungs-VoIP-Agents.

# 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