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

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.

Stage Was Sie tun Weitere Informationen
Install Installiere azd und die Foundry-Erweiterungen. Einrichten Ihrer Entwicklerumgebung
Gerüst Initialisieren Sie ein Projekt aus einer Vorlage oder ihrem vorhandenen Code. Schnellstart: Bereitstellen eines gehosteten Agents
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 hinzu, und testen Sie lokal. Übersicht über Tools
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 konzentriert sich auf gehostete Agents.

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.

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

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-azd-Projektmodell gibt es keine eigenständige agent.yaml- oder agent.manifest.yaml-Datei.

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.

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.

# 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