Hinweis
Für den Zugriff auf diese Seite ist eine Autorisierung erforderlich. Sie können versuchen, sich anzumelden oder das Verzeichnis zu wechseln.
Für den Zugriff auf diese Seite ist eine Autorisierung erforderlich. Sie können versuchen, das Verzeichnis zu wechseln.
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 aktivenazd-Umgebung auf. - Legen Sie außerhalb eines
azd-Projekts den aktiven Kontext einmal mitazd ai project set <endpoint>fest, oder geben Sie--project-endpointbei einem einzelnen Ressourcenbefehl an (connection,toolbox,skilloderroutine). Als Fallback liestazd aidieFOUNDRY_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 evalund einen lokaleneval.yaml-Workflow, einschließlich des Optimiererworkflows. Die Projektbewertung verwendet die separat installierteazd ai evalErweiterung undevals/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