Configurare CI/CD per gli agenti ospitati con l'interfaccia della riga di comando per sviluppatori Azure

Automatizza la distribuzione dell'agente ospitato con azd pipeline config. In questo articolo si configurano l'integrazione e il recapito continui in GitHub Actions o Azure DevOps, quindi si applicano i flag azd ai supportati dalle pipeline per processi senza intervento dell'utente.

Prerequisiti

• Progetto agente ospitato inizializzato che funziona localmente con azd ai agent run e azd ai agent invoke --local. Per l'installazione, vedere Inizializzare un progetto di agente.
• Un progetto che hai distribuito correttamente almeno una volta con azd up. Per la procedura di distribuzione, vedere Distribuire un agente ospitato.
• Le estensioni azd Foundry installate in locale e nello strumento di esecuzione della pipeline.
• Sessione autenticata azd .
• Il codice in un repository Git ospitato su GitHub o Azure DevOps.

Configurare la pipeline

Eseguire il comando di configurazione della pipeline:

azd pipeline config

Questo comando interattivo:

1. Rileva il provider Git, ad esempio GitHub o Azure DevOps.
2. Crea un service principal per l'autenticazione CI/CD.
3. Configura i segreti e le variabili del repository con i valori del tuo ambiente azd.
4. Genera un file del flusso di lavoro, ad esempio .github/workflows/azure-dev.yml per GitHub Actions o un file YAML Azure Pipelines.

Esaminare il flusso della pipeline

La pipeline generata viene eseguita al push su main per impostazione predefinita ed esegue:

1. azd provision -- crea o aggiorna l'infrastruttura di Azure a partire dai modelli Bicep infra/.
2. azd deploy -- compila il contenitore, esegue il push in ACR e crea una nuova versione dell'agente ospitato.

Si tratta dello stesso flusso di esecuzione di azd up in locale, ma automatizzato nell'integrazione continua.

Configurare GitHub Actions

Dopo azd pipeline config, si avrà un .github/workflows/azure-dev.yml file. Un flusso di lavoro tipico è simile al seguente:

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

Configurare Azure DevOps

azd pipeline configsupporta anche Azure DevOps.

1. Quando richiesto, selezionare "Azure DevOps".
2. Esaminare il file generato azure-pipelines.yml .
3. Verificare che il file generato contenga passaggi di installazione, accesso, provisioning e distribuzione equivalenti.

Impostare i flag supportati dalle pipeline

La maggior parte dei comandi azd ai accetta flag che li rendono sicuri da eseguire automaticamente in CI. Impostare i flag nei passaggi azd ai pertinenti della pipeline.

• --no-prompt -- disabilita le richieste interattive. Il comando non riesce rapidamente con un messaggio di errore utile anziché bloccarsi in attesa di input. Ogni azd ai comando lo supporta. Impostare sempre questo comando nell'integrazione continua. In caso contrario, la mancanza di un valore obbligatorio può bloccare il processo fino al timeout.
• --output json-- genera un output strutturato che è possibile analizzare con jq, PowerShell ConvertFrom-Jsono qualsiasi altro strumento JSON, per i comandi che lo supportano, ad esempio azd ai agent show e i connectioncomandi , toolboxskill, e .routine azd ai agent invoke usa --output raw invece .
• --project-endpoint (-p) -- imposta l'endpoint del progetto Microsoft Foundry per un singolo comando relativo a una risorsa (connection, toolbox, skill o routine). I comandi azd ai agent comandi risolvono il progetto dall'ambiente azd attivo, dalla configurazione globale o dalla variabile di ambiente FOUNDRY_PROJECT_ENDPOINT.
• --debug -- genera un output di diagnostica verboso. Utile durante l'analisi di un errore CI, ma rumoroso per le normali esecuzioni.

Esempio:

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

Impostare il contesto del progetto in CI

Le pipeline vengono eseguite al di fuori di un contesto di progetto interattivo azd, quindi azd ai i comandi diretti devono sapere a quale progetto Foundry fare riferimento. Scegliere quale dei due modelli seguenti si adatta alla pipeline.

Impostare la variabile di ambiente

Impostare FOUNDRY_PROJECT_ENDPOINT una sola volta sul processo o sull'intero flusso di lavoro. Ogni comando azd ai lo seleziona automaticamente dopo l'ambiente azd nel progetto e la configurazione globale.

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

Aggiungere l'endpoint con azd ai project set

Eseguire azd ai project set $FOUNDRY_PROJECT_ENDPOINT --no-prompt all'inizio del processo. Scrive l'endpoint nella configurazione azd globale (~/.azd/config.json) e i successivi comandi azd ai nello stesso processo usano tale contesto.

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

L'interfaccia della riga di comando risolve l'endpoint in questo ordine: il --project-endpoint flag, l'ambiente attivo azd all'interno di un azd progetto, la configurazione globale impostata da azd ai project sete infine la FOUNDRY_PROJECT_ENDPOINT variabile di ambiente. Se nessuno si risolve, il comando termina con un errore strutturato.

Per altre informazioni sull'esecuzione azd ai di comandi senza un progetto azd su disk, vedere Impostare il contesto del progetto azd.

Verificare con eval nell'integrazione continua

Dopo che la pipeline è stata distribuita o ha ottenuto accesso a un progetto di destinazione, usa azd ai agent eval run per i controlli di regressione. Eseguire un comando eval archiviato sull'agente corrente e il processo non riesce se i punteggi scendono al di sotto della soglia.

azd ai agent eval run --no-prompt

eval run per impostazione predefinita si risolve eval.yaml nella radice del progetto oppure è possibile passare --config <path>. Non rigenera i set di dati e gli analizzatori come effetto collaterale. Per visualizzare la suite eval nell'integrazione continua, eseguire prima azd ai agent eval generate. Questo comando richiede un agente distribuito che è possibile richiamare.

Configurare distribuzioni specifiche dell'ambiente

Per più ambienti, ad esempio sviluppo, collaudo e produzione:

1. Creare ambienti azd separati:

   azd env new staging
   azd env set AZURE_LOCATION=eastus2
   

2. Configurare una pipeline per ogni ambiente o usare trigger basati su rami:

   • main -> produzione
   • develop -> gestione temporanea

3. Usare le variabili di ambiente azd specifiche di ogni esecuzione della pipeline per isolare le risorse.

Gestire le credenziali riservate

azd pipeline config archivia i valori seguenti come segreti o variabili del repository:

• AZURE_CLIENT_ID -- ID client dell'entità servizio.
• AZURE_TENANT_ID -- ID del tenant Microsoft Entra.
• AZURE_SUBSCRIPTION_ID -- Sottoscrizione di destinazione.
• AZURE_ENV_NAME -- Nome della variabile di ambiente.
• AZURE_LOCATION -- area geografica di Azure.

Aggiungete segreti specifici dell'agente, ad esempio chiavi API MCP a cui si fa riferimento nella mappa env per il servizio azure.ai.agent in azure.yaml, come ulteriori segreti del repository. Mappare ciascuno a una variabile di ambiente azd nella pipeline.

Risolvere i problemi relativi alla pipeline

Esaminare i problemi comuni prima di ripetere l'esecuzione della pipeline. Per il provisioning dell'integrazione continua, oltre ai ruoli di Azure potrebbe essere necessario Proprietario di Foundry.

Contenuti correlati

• Distribuire un agente ospitato per comprendere cosa accade durante la distribuzione.
• Riferimento YAML di Azure per esaminare i dettagli della configurazione di distribuzione.
• Configurare una pipeline DevOps con azd per il riferimento completo alla pipeline azd.