Verwenden Sie azd ai mit Programmier-Agents und Skripten

Verwenden Sie azd ai aus Programmier-Agents und Skripts mit demselben Verhalten, das Menschen an einem Terminal erhalten. Sie legen einen eigenständigen Kontext fest, deaktivieren Eingabeaufforderungen, analysieren die JSON-Ausgabe und rufen direkte Agent-Endpunkte für eine zuverlässige Automatisierung auf.

Voraussetzungen

• Die azd Foundry Erweiterungen installiert.
• Eine authentifizierte azd Sitzung.
• Ein Microsoft Foundry-Projektendpunkt für die Befehle, die Sie ausführen möchten. Weitere Informationen finden Sie unter "Festlegen des azd-Projektkontexts".
• Optional: Ein bereitgestellter gehosteter Agent, wenn Sie einen Agentendpunkt aufrufen müssen. Informationen zum Einrichten finden Sie unter Bereitstellen eines gehosteten Agents.

Beginnen Sie mit dem Microsoft Foundry Skill

Coding-Agenten funktionieren am besten, wenn sie die azd ai Konventionen schon kennen. Die Microsoft Foundry Skill vermittelt einem Codierungs-Agenten dieses Wissen: Er generiert korrekte azd ai-Befehle und Foundry-Verkabelung und wendet die in diesem Artikel beschriebenen Vorgehensweisen an -- das Festlegen des Projektkontexts, die Übergabe von --no-prompt und das Anfordern von --output json für strukturierte Ergebnisse. Richten Sie Ihren Programmier-Agent zuerst auf den Skill, und verwenden Sie dann die Muster im Rest dieses Artikels, um das Ergebnis zu überprüfen und zu härten.

Festlegen des Projektkontexts einmal

Jeder Ressourcenbefehl, wie z. B. connection, toolbox, skill oder routine, benötigt einen Foundry-Projektendpunkt als Ziel. Legen Sie in der Automatisierung den Endpunkt einmal pro Sitzung, CI-Auftrag oder Codierungs-Agent-Aufruf fest, und verwenden Sie ihn dann für den Rest der Ausführung.

Es gibt zwei Muster.

Einmaliges Anheften mit azd ai project set

Wenn der Kontext über Shells hinweg beibehalten werden soll, ohne eine Umgebungsvariable zu exportieren, legen Sie ihn in der globalen Konfiguration fest:

azd ai project set https://my-project.services.ai.azure.com/api/projects/my-project --no-prompt
azd ai project show

azd ai project set <endpoint> ist vollständig nicht interaktiv, wenn Sie die URL bereits kennen. azd ai project show bestätigt, welche Quelle den aktiven Endpunkt aufgelöst hat. Verwenden Sie sie zu Beginn einer Sitzung, wenn Sie nicht sicher sind, in welchem Zustand sich der Host befindet.

Festlegen einer Umgebungsvariable

Legen Sie FOUNDRY_PROJECT_ENDPOINT in der Umgebung fest, in der Ihr Skript- oder Codierungs-Agent ausgeführt wird. Jeder azd ai-Befehl übernimmt sie automatisch nach der azd-Umgebung im Projekt und der globalen Konfiguration.

export FOUNDRY_PROJECT_ENDPOINT="https://my-project.services.ai.azure.com/api/projects/my-project"
azd ai connection list --output json

Dieses Muster eignet sich gut für CI, weil Geheimnisse und Konfigurationen in der Regel bereits als Umgebungsvariablen vorliegen und es keinen globalen Zustand gibt, der zwischen Jobs bereinigt werden müsste.

Eine vollständige Erläuterung der Auflösung des Endpunkts durch die CLI, einschließlich der Rangreihenfolge, finden Sie unter "Festlegen des azd-Projektkontexts".

Eingabeaufforderungen deaktivieren

Jeder azd ai Befehl akzeptiert --no-prompt. Wenn Sie ihn festlegen, schlägt der Befehl schnell fehl, anstatt die interaktive Eingabe zu blockieren. Ein fehlendes erforderliches Argument oder eine Bestätigung über delete, die andernfalls auf einen Tastendruck warten würde, führt bei strukturierter Ausgabe unmittelbar zu einem Fehler.

Legen Sie --no-prompt immer in CI und bei Coding-Agent-Aufrufen fest.

azd ai connection create my-search \
  --kind cognitive-search \
  --target https://my-search.search.windows.net \
  --auth-type api-key \
  --key "$KEY" \
  --no-prompt

JSON-Ausgabe abrufen

Die meisten azd ai Befehle unterstützen --output json, einschließlich der connectionBefehle , toolbox, skillund routine Ressourcenbefehle und azd ai agent show. Verwenden Sie sie, um das Ergebnis zuverlässig mit jq, ConvertFrom-Json oder dem JSON-Parser Ihrer Sprache zu analysieren, anstatt die für Menschen lesbare Textausgabe zu scrapen. Der azd ai agent invoke-Befehl verwendet --output raw für die unveränderte Serverantwort.

# List connections, extract names with jq
azd ai connection list --output json | jq -r '.[].name'

# Show a single resource as JSON
azd ai routine show daily-digest --output json | jq '.trigger'

# PowerShell example
$conn = azd ai connection show my-search --output json | ConvertFrom-Json
Write-Host $conn.target

Die Textausgabe ist für Menschen vorgesehen und kann sich zwischen Versionen ändern. Die JSON-Form ist der stabile Vertrag.

Idempotentes Erstellen von Ressourcen

create ist kein Upsert. Wenn die benannte Ressource bereits vorhanden ist, schlägt eine erneute Ausführung fehl. Diese Standardeinstellung eignet sich gut für gemeinsam genutzte, auf ein Projekt begrenzte Ressourcen, da sie verhindert, dass ein Aufrufer den Zustand eines anderen Aufrufers unbemerkt überschreibt.

Für die Automatisierung, die unabhängig vom vorherigen Zustand erfolgreich sein muss, akzeptieren connection die --force Befehle, um die vorhandene Ressource zu ersetzen.

azd ai connection create my-search \
  --kind cognitive-search \
  --target https://my-search.search.windows.net \
  --auth-type api-key \
  --key "$KEY" \
  --force --no-prompt

Wenn Sie nur ein paar Felder ändern müssen und alles andere beibehalten möchten, verwenden Sie update. Oder verwenden Sie die dedizierten Auflistungsunterbefehle wie tool, , tag, metadataund key.

Erstellen einer Toolbox aus einer Datei

Für eine Toolbox mit mehreren Einträgen, die integrierte Tools, Verbindungen und Fähigkeiten bündelt, speichern Sie die vollständige Definition in einer YAML-Datei und übergeben Sie --from-file an azd ai toolbox create. Die Datei verwendet die entsprechende AgentSchema-Form.

azd ai toolbox create research --from-file ./resources/research-toolbox.yaml --no-prompt

--from-file ist eine One-Shot-Eingabe, die zur Aufrufzeit gelesen wird. Die CLI verfolgt oder liest die Datei nicht erneut, sodass zukünftige Bearbeitungen an yaML erst wirksam werden, wenn Sie den Befehl erneut ausführen. Erstellen Sie Verbindungen mit expliziten Flags (--kind, --target, --auth-type und den übereinstimmenden Anmeldeinformations-Flags), und verweisen Sie dann anhand des Namens aus der Toolbox-Datei auf sie.

Aufrufen eines bereitgestellten Agents ohne azd-Projekt

Wenn ein Coding-Agent oder Skript einen bereitgestellten Agenten aufrufen muss, der sich außerhalb seines Arbeitsverzeichnisses befindet, verwenden Sie --agent-endpoint, um ihn direkt anzusprechen. Dieser Ansatz umgeht sowohl azure.yaml als auch die aktive azd env. Die URL allein reicht aus.

azd ai agent invoke \
  --agent-endpoint https://my-project.services.ai.azure.com/api/projects/my-project/agents/release-summarizer/versions/3 \
  "Summarize today's release notes." \
  --no-prompt

Verwenden Sie dieses Shape, wenn die CI eines Repositorys einen Agent aufrufen muss, der einem anderen Repository gehört, oder wenn ein MCP-Server mehrere Agents vorhebt und nur seine Endpunkt-URLs kennt.Use this shape when one repository's CI needs to call an agent owned by a different repository, or when an MCP server fronts several agents and only knows their endpoint URLs. Die vollständigen invoke Optionen finden Sie unter Aufrufen eines gehosteten Agents.

Übergeben von Geheimnissen an eine lokale Ausführung

Um den Agenten lokal mit Secrets zu starten, legen Sie diese als azd-Umgebungsvariablen fest und referenzieren Sie sie in der env-Map für Ihren azure.ai.agent-Dienst in azure.yaml. Die Werte befinden sich in .azure/<env>/.env, was standardmäßig von Git ignoriert wird.

azd env set OPENAI_KEY "$AZURE_OPENAI_KEY"

# azure.yaml
services:
  my-agent:
    host: azure.ai.agent
    env:
      OPENAI_KEY: ${OPENAI_KEY}

Geheimnisse, die sich nicht in einer lokalen .env-Datei befinden sollten, speichern Sie in einer Foundry-Projektverbindung und verweisen mit einem ${{connections.<name>.credentials.<field>}}-Platzhalter auf sie. Siehe lokales Ausführen eines gehosteten Agents für die vollständige lokale Ausführungsoberfläche.

Skript für ein kurzes Setup

Dieses Bash-Skript kombiniert die oben genannten Muster. Dadurch wird der Projektkontext angeheftet, eine Verbindung und eine Toolbox werden idempotent erstellt, ein Tool wird in die Toolbox eingebunden und das Ergebnis wird durch Analysieren von JSON überprüft.

#!/usr/bin/env bash
set -euo pipefail

azd ai project set "$FOUNDRY_PROJECT_ENDPOINT" --no-prompt

# A 'remote-tool' connection holds the URL and credentials for the MCP server.
azd ai connection create tavily \
  --kind remote-tool \
  --target https://mcp.tavily.com/mcp \
  --auth-type custom-keys \
  --custom-key "x-api-key=$TAVILY_KEY" \
  --force --no-prompt

# Create the toolbox with the connection wired in, in a single shot
cat > research-toolbox.yaml <<'EOF'
description: Research tools
connections:
  - name: tavily
EOF

azd ai toolbox create research --from-file ./research-toolbox.yaml --no-prompt

echo "Toolbox state:"
azd ai toolbox connection list research --output json | jq .

set -euo pipefail stellt sicher, dass das Skript sofort abbricht, wenn in einem Schritt ein Fehler auftritt. In Kombination mit --no-prompt erhalten Sie so einen deterministischen Exit-Code, der sich für CI-Gates eignet.

Endpunktauflösung überprüfen

Codierungs-Agents können vorhersagen, auf welches Foundry-Projekt ein Befehl ausgerichtet wird, indem sie diese Prioritätsreihenfolge ausführen. Die erste Quelle, die einen Wert liefert, gewinnt; spätere Quellen werden nicht konsultiert.

1. Flag --project-endpoint (oder -p) (gewinnt immer).
2. Innerhalb eines azd-Projekts: der aktive azd-env-Wert.
3. Globale Konfiguration (festgelegt nach azd ai project set).
4. Die Umgebungsvariable FOUNDRY_PROJECT_ENDPOINT
5. Fehler mit einem strukturierten Vorschlag, azd ai project set auszuführen oder --project-endpoint zu übergeben.

Die vollständige Erläuterung, einschließlich der Interaktion des eigenständigen Kontexts mit projektinterner Arbeit, finden Sie unter "Festlegen des azd-Projektkontexts".

Anwenden von Tipps für Programmier-Agents

• Übergeben Sie immer --no-prompt und fügen Sie bei Befehlen, die dies unterstützen, --output json hinzu. Gemeinsam erhalten Sie einen vorhersagbaren Ausgangscode sowie ein analysebares Ergebnis.
• Überprüfen Sie zu Beginn einer Sitzung mit azd ai project show den aufgelösten Kontext, wenn Sie sich nicht sicher sind, in welchem Zustand sich der Host befindet. Es handelt sich um einen kostengünstigen, schreibgeschützten Aufruf.
• Im Fehlerfall sollte das Parsen der strukturierten Empfehlung in der Fehlerausgabe gegenüber der Festlegung der nächsten Schritte bevorzugt werden. Ein Fehler wie „No Foundry project endpoint resolved“ bedeutet beispielsweise, dass Sie azd ai project set ausführen oder FOUNDRY_PROJECT_ENDPOINT festlegen sollten, bevor Sie es erneut versuchen.
• Verwenden Sie --debug nur, wenn ein Problem diagnostiziert wird. Es wird eine ausführliche, mehrzeilige Ausgabe erzeugt, die schwer zu analysieren ist und nie als programmgesteuerte Schnittstelle gedacht war.
• Behandeln Sie Fehler bei create mit „bereits vorhanden“ als behebbar. Führen Sie den Befehl mit --force erneut aus, wenn Sie die Ressource ersetzen möchten, oder wechseln Sie zu update und den Unterbefehlen für Sammlungen, wenn Sie nur einen Teil der Ressource ändern müssen.

Verwandte Inhalte

• Legen Sie den azd-Projektkontext fest, um zu verstehen, wie die CLI den Projektendpunkt von Foundry ermittelt.
• Einrichten von CI/CD für gehostete Agents mit der Azure Developer CLI für Muster, die azd ai in Pipelines ausführen.
• Aufrufen eines gehosteten Agents für vollständige azd ai agent invoke Optionen, einschließlich --agent-endpoint.