Einrichten von CI/CD für gehostete Agents mit der Azure Developer CLI

Automatisieren Sie die Bereitstellung Ihres Hosted-Agents mit azd pipeline config. In diesem Artikel richten Sie eine kontinuierliche Integration und Lieferung in GitHub Actions oder Azure DevOps ein und wenden dann pipelinefreundliche azd ai Kennzeichnungen für unbeaufsichtigte Aufträge an.

Voraussetzungen

• Ein initialisiertes gehostetes Agentprojekt, das lokal mit azd ai agent run und azd ai agent invoke --localarbeitet. Informationen zum Einrichten finden Sie unter Initialisieren eines Agentprojekts.
• Ein Projekt, das Sie mit azd up mindestens einmal erfolgreich bereitgestellt haben. Schritte zur Bereitstellung finden Sie unter Bereitstellen eines gehosteten Agents.
• Die lokal und in Ihrem Pipeline-Runner installierten azd Foundry-Erweiterungen.
• Eine authentifizierte azd Sitzung.
• Ihr Code in einem Git-Repository, das in GitHub oder Azure DevOps gehostet wird.

Konfigurieren der Pipeline

Führen Sie den Pipelinekonfigurationsbefehl aus:

azd pipeline config

Dieser interaktive Befehl:

1. Erkennt Ihren Git-Anbieter, z. B. GitHub oder Azure DevOps.
2. Erstellt einen Dienstprinzipal für die CI/CD-Authentifizierung.
3. Konfiguriert Geheimnisse und Variablen des Repositorys anhand der Werte Ihrer azd-Umgebung.
4. Generiert eine Workflowdatei, wie .github/workflows/azure-dev.yml für GitHub Actions oder eine Azure-Pipelines-YAML-Datei.

Überprüfen des Pipelineflusses

Die generierte Pipeline wird standardmäßig bei einem Push nach main ausgeführt und führt Folgendes aus:

1. azd provision -- erstellt oder aktualisiert Azure-Infrastruktur mithilfe von infra/ Bicep-Vorlagen.
2. azd deploy -- erstellt den Container, überträgt ihn in ACR und erstellt eine neue gehostete Agent-Version.

Dies ist derselbe Ablauf wie beim lokalen Ausführen von azd up, jedoch automatisiert in CI.

Konfigurieren von GitHub-Aktionen

Nach azd pipeline config haben Sie eine .github/workflows/azure-dev.yml-Datei. Ein typischer Workflow sieht wie folgt aus:

name: Azure Developer CLI

on:
  push:
    branches:
      - main
  workflow_dispatch:

permissions:
  id-token: write
  contents: read

jobs:
  build:
    runs-on: ubuntu-latest
    env:
      AZURE_CLIENT_ID: ${{ vars.AZURE_CLIENT_ID }}
      AZURE_TENANT_ID: ${{ vars.AZURE_TENANT_ID }}
      AZURE_SUBSCRIPTION_ID: ${{ vars.AZURE_SUBSCRIPTION_ID }}
      AZURE_ENV_NAME: ${{ vars.AZURE_ENV_NAME }}
      AZURE_LOCATION: ${{ vars.AZURE_LOCATION }}
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Install azd
        uses: Azure/setup-azd@v2

      - name: Install Foundry extensions
        run: azd ext install microsoft.foundry

      - name: Sign in to Azure (federated credentials)
        run: azd auth login --client-id $AZURE_CLIENT_ID --federated-credential-provider github --tenant-id $AZURE_TENANT_ID

      - name: Provision and Deploy
        run: azd up --no-prompt

Konfigurieren von Azure DevOps

azd pipeline configunterstützt auch Azure DevOps.

1. Wählen Sie "Azure DevOps" aus, wenn Sie dazu aufgefordert werden.
2. Überprüfen Sie die generierte azure-pipelines.yml Datei.
3. Vergewissern Sie sich, dass die generierte Datei entsprechende Installations-, Anmelde-, Provisionierungs- und Bereitstellungsschritte enthält.

Pipeline-freundliche Flags festlegen

Die meisten azd ai-Befehle akzeptieren Flags, mit denen sie sicher unbeaufsichtigt in CI ausgeführt werden können. Legen Sie diese bei den entsprechenden azd ai-Schritten in Ihrer Pipeline fest.

• --no-prompt - deaktiviert interaktive Eingabeaufforderungen. Der Befehl schlägt schnell mit einem hilfreichen Fehler fehl, anstatt bei der Eingabe zu blockieren. Jeder azd ai Befehl unterstützt ihn. Legen Sie dies in CI immer fest. Ohne diese Einstellung kann ein fehlender erforderlicher Wert den Auftrag blockieren, bis ein Timeout auftritt.
• --output json -- gibt strukturierte Ausgabe aus, die Sie mit jq, PowerShell ConvertFrom-Json oder einem beliebigen anderen JSON-Tool parsen können, für Befehle, die dies unterstützen, wie etwa azd ai agent show sowie die Befehle connection, toolbox, skill und routine. azd ai agent invoke verwendet --output raw stattdessen.
• --project-endpoint (-p) -- legt den Microsoft-Foundry-Projektendpunkt für einen einzelnen Ressourcenbefehl fest (connection, toolbox, skill oder routine). Die azd ai agent-Befehle lösen das Projekt aus der aktiven azd-Umgebung, der globalen Konfiguration oder der Umgebungsvariablen FOUNDRY_PROJECT_ENDPOINT auf.
• --debug -- gibt ausführliche Diagnoseausgabe aus. Hilfreich bei der Untersuchung eines CI-Fehlers, aber zu viele Informationen für normale Ausführungen.

Beispiel:

azd ai agent invoke my-agent "ping" --no-prompt --output raw

Festlegen des Projektkontexts in CI

Pipelines werden außerhalb eines interaktiven azd Projektkontexts ausgeführt, sodass azd ai direkte Befehle wissen müssen, welches Foundry-Projekt als Ziel verwendet werden soll. Wählen Sie aus, welcher der folgenden beiden Muster zu Ihrer Pipeline passt.

Festlegen der Umgebungsvariable

Legen Sie FOUNDRY_PROJECT_ENDPOINT einmal für den Auftrag oder den gesamten Workflow fest. Jeder azd ai-Befehl übernimmt sie automatisch nach der projektinternen azd-Umgebung und der globalen Konfiguration.

jobs:
  agent-checks:
    runs-on: ubuntu-latest
    env:
      FOUNDRY_PROJECT_ENDPOINT: ${{ vars.FOUNDRY_PROJECT_ENDPOINT }}
    steps:
      - uses: actions/checkout@v4
      - uses: Azure/setup-azd@v2
      - run: azd ext install microsoft.foundry
      - run: azd ai agent show --no-prompt --output json

Heften Sie den Endpunkt mit azd ai project set an.

Führen Sie azd ai project set $FOUNDRY_PROJECT_ENDPOINT --no-prompt frühzeitig im Auftrag aus. Der Endpunkt wird in die globale azd-Konfiguration (~/.azd/config.json) geschrieben, und nachfolgende azd ai-Befehle im selben Job verwenden diesen Kontext.

- run: azd ai project set ${{ vars.FOUNDRY_PROJECT_ENDPOINT }} --no-prompt
- run: azd ai agent show --no-prompt --output json

Die CLI ermittelt den Endpunkt in dieser Reihenfolge: das --project-endpoint-Flag, die aktive azd-Umgebung innerhalb eines azd-Projekts, die globale Konfiguration, die mit azd ai project set festgelegt wurde, und schließlich die Umgebungsvariable FOUNDRY_PROJECT_ENDPOINT. Wenn sich keines davon auflösen lässt, beendet sich der Befehl mit einer strukturierten Fehlermeldung.

Weitere Informationen zum Ausführen von azd ai Befehlen ohne azd-Projekt auf dem Datenträger finden Sie unter "Festlegen des azd-Projektkontexts".

Überprüfen mit eval in CI

Nachdem die Pipeline bereitgestellt ist oder Zugriff auf ein Zielprojekt hat, verwenden Sie azd ai agent eval run für Regressionsprüfungen. Führen Sie eine gespeicherte Auswertung für den aktuellen Agent aus, und lassen Sie den Auftrag fehlschlagen, wenn die Bewertungen unter Ihren Schwellenwert fallen.

azd ai agent eval run --no-prompt

eval run löst eval.yaml standardmäßig im Projektstammverzeichnis auf, oder Sie können --config <path> übergeben. Dabei werden Datensätze und Evaluatoren nicht als Nebeneffekt erneut generiert. Um die Eval-Suite in CI zu starten, führen Sie azd ai agent eval generate zuerst aus. Für diesen Befehl ist ein bereitgestellter Agent erforderlich, den Sie aufrufen können.

Konfigurieren von umgebungsspezifischen Bereitstellungen

Für mehrere Umgebungen, z. B. Entwicklung, Staging und Produktion:

1. Erstellen separater azd-Umgebungen:

   azd env new staging
   azd env set AZURE_LOCATION=eastus2
   

2. Konfigurieren einer Pipeline pro Umgebung oder Verwenden von branchbasierten Triggern:

   • main -> Produktion
   • develop -> Staging-Umgebung

3. Verwenden Sie für jede Pipeline-Ausführung deren eigene azd-Umgebungsvariablen, damit die Ressourcen voneinander isoliert sind.

Verwalten von Geheimnissen

azd pipeline config speichert die folgenden Werte als geheime Repositoryschlüssel oder Variablen:

• AZURE_CLIENT_ID -- Client-ID des Dienstprinzipals.
• AZURE_TENANT_ID -- Microsoft Entra-Mandanten-ID.
• AZURE_SUBSCRIPTION_ID -- Zielabonnement.
• AZURE_ENV_NAME -- Name der azd-Umgebung.
• AZURE_LOCATION -- Azure-Region.

Fügen Sie agentspezifische geheime Schlüssel hinzu, z. B. MCP-API-Schlüssel, auf die von der env Karte für Ihren azure.ai.agent-Dienst in azure.yaml verwiesen wird, als weitere Repositoryschlüssel. Ordnen Sie jede davon einer azd-Umgebungsvariable in der Pipeline zu.

Beheben von Pipelineproblemen

Überprüfen Sie häufige Probleme, bevor Sie die Pipeline erneut ausführen. Für die CI-Bereitstellung benötigen Sie möglicherweise zusätzlich zu Azure Rollen "Foundry Owner".

Verwandte Inhalte

• Stellen Sie einen gehosteten Agent bereit , um zu verstehen, was während der Bereitstellung geschieht.
• Referenz zu Azure YAML, um die Details der Bereitstellungskonfiguration zu überprüfen.
• Konfigurieren Sie eine DevOps-Pipeline mit azd für die vollständige Referenz zur azd-Pipeline.