Agententwicklung mit der Azure Developer CLI

Important

Elemente, die in diesem Artikel als Vorschau gekennzeichnet sind, befinden sich derzeit in der Vorschau. Diese Vorschau wird ohne Service Level Agreement (SLA) bereitgestellt, und Microsoft empfiehlt sie 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 codebasierte und deklarative Agenttypen.

Typ Description Wann verwenden?
Bereitgestellter Agent Eine containerisierte Anwendung, die Sie in Code erstellen, als Docker-Image verpacken und in Foundry 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.
promptbasierter Sprachagent Ein deklarativer VoIP-Agent, der ein verwaltetes oder selbst bereitgestelltes Modell ohne benutzerdefinierten Laufzeitcode verwendet. Sie möchten ein Konversations-Spracherlebnis in Echtzeit, ohne eine Audiopipeline erstellen und hosten zu müssen.
Gehosteter VoIP-Agent mit einem verwalteten Wrapper Ein gehostetes Ziel verarbeitet die Konversationslogik, während ein separater Sprachdienst über conversationEngine an dieses delegiert. Voice Live behandelt die Audioerfahrung. Sie benötigen benutzerdefinierte Agentlogik, ohne spracherkennung und Synthese im gehosteten Ziel zu implementieren.

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 gehosteten Agent inline und verwendet uses: , um auf andere Dienste zu verweisen, z. B. das Projekt, Verbindungen, Toolboxen, Fähigkeiten und Routinen. Im aktuellen Hosted-Agent-agent.yaml-Projektmodell gibt es keine eigenständige agent.manifest.yaml- oder azd-Datei.

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.
  • 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 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 Eine Abfolge von Nachrichten innerhalb einer Sitzung. Foundry verwaltet den Konversationsverlauf und kann ihn anfrageübergreifend wiederherstellen.

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.

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

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

Verwandte Inhalte

  • Last updated on