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

Importante

Gli elementi contrassegnati come anteprima in questo articolo sono attualmente in anteprima. Questa anteprima viene fornita senza un contratto di servizio e Microsoft non lo consiglia per i carichi di lavoro di produzione. Alcune funzionalità potrebbero non essere supportate o potrebbero avere funzionalità limitate. Per ulteriori informazioni, vedere Condizioni supplementari per l'uso delle versioni di anteprima di Microsoft 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.

Scegli Terraform o Bicep per il provisioning dell'infrastruttura. Se vuoi che Terraform gestisca la risorsa del data plane dell'agente ospitato senza azd, usa invece distribuire un agente ospitato con Terraform.

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.

Scegliere il provider di infrastruttura

Per usare Terraform invece di Bicep, inizializzare il progetto con:

azd ai agent init --infra=terraform

Per un agente basato su contenitori, specificare la modalità di distribuzione in modo indipendente:

azd ai agent init --infra=terraform --deploy-mode container

L'opzione infrastruttura non modifica la modalità di distribuzione del codice predefinita per i progetti Python e .NET. Per Bicep, usare --infra=bicep o --infra. Senza --infra, azd sintetizza l'infrastruttura a partire da azure.yaml invece di scrivere file IaC.

Per un nuovo progetto, esaminare la directory infra/ generata e la configurazione del provider Terraform in azure.yaml. I progetti esistenti possono usare un livello di infrastruttura Foundry separato. Vedere Infrastruttura dell'agente ospitato per la struttura dei file e le limitazioni di esezione.

Effettuare il commit della configurazione dell'infrastruttura e del file di blocco del provider insieme al codice dell'applicazione. Non eseguire il commit dello stato terraform, .terraform/dei piani salvati o .azure/ dello stato dell'ambiente. L'inizializzazione è una fase di configurazione del progetto, non un comando da rieseguire a ogni deployment della CI.

Configurare lo stato di Terraform

Ignorare questa sezione se non si usa Terraform.

Prima di configurare la pipeline:

  1. Installare Terraform in locale e nel runner. Usare la stessa versione esaminata nello sviluppo e nell'integrazione continua.

  2. Creare un account Archiviazione di Azure e un contenitore BLOB per lo stato remoto all'esterno della distribuzione del carico di lavoro. Usare una chiave di stato diversa per ogni ambiente.

  3. Aggiungi una dichiarazione azurerm backend al blocco terraform esistente nel file del provider Terraform. Mantenere i vincoli del provider generato e della versione di Terraform:

    terraform {
      backend "azurerm" {}
    }
    
  4. Crea provider.conf.json nella directory dell'infrastruttura Terraform. Per un nuovo progetto che usa il layout predefinito, il percorso è infra/provider.conf.json:

    {
      "storage_account_name": "${RS_STORAGE_ACCOUNT}",
      "container_name": "${RS_CONTAINER_NAME}",
      "key": "hosted-agent-ci/${AZURE_ENV_NAME}.tfstate",
      "resource_group_name": "${RS_RESOURCE_GROUP}",
      "use_azuread_auth": true
    }
    

    Scegliere un prefisso di chiave univoco per l'applicazione se più applicazioni condividono il contenitore. azd risolve queste sostituzioni di ambiente e passa la configurazione a terraform init; non sono variabili di input terraform.

    Questo esempio abilita deliberatamente l'autenticazione di Microsoft Entra per l'accesso ai Blob con use_azuread_auth. L'autenticazione OIDC da sola non seleziona la modalità back-end. Senza di esso, un back-end può richiedere l'autorizzazione per recuperare una chiave dell'account di archiviazione. Per altre informazioni, vedere Abilitare lo stato remoto.

  5. Impostare i valori back-end nell'ambiente azd:

    azd env set RS_RESOURCE_GROUP "<state-resource-group>"
    azd env set RS_STORAGE_ACCOUNT "<state-storage-account>"
    azd env set RS_CONTAINER_NAME "<state-container>"
    
  6. Concedi all'identità della pipeline l'accesso al piano dati dei BLOB per il backend, separatamente dalle autorizzazioni dell'infrastruttura e di Foundry. Esaminare i requisiti di ruolo e di rete del back-end in Archiviare lo stato di Terraform in Archiviazione di Azure.

  7. Verificare che azd provision usi il back-end remoto prima di configurare la pipeline.

Lo stato e i piani salvati possono contenere valori sensibili. Limita l'accesso a entrambi e non caricarli come artefatti del workflow senza restrizioni.

Il blocco del backend protegge le operazioni sullo stato di Terraform. Non coordina altri strumenti che aggiornano lo stesso agente ospitato. Serializzare i rilasci di produzione tra azd, Terraform e qualsiasi altro processo di scrittura della distribuzione.

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.

Per i progetti Terraform in GitHub, il comando verifica che i tre RS_* valori siano presenti e li copia nelle variabili del repository. Questo controllo non verifica l'esistenza, le autorizzazioni o la connettività dell'archiviazione.

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 usando il provider configurato in azure.yaml, inclusi i file Terraform o Bicep estratti.
  2. azd deploy -- compila il contenitore, esegue il push in ACR e crea una nuova versione dell'agente ospitato.

Per la distribuzione del codice, azd deploy carica il pacchetto di origine invece di compilare il contenitore. In entrambe le modalità, azd gestisce la distribuzione delle versioni dell'agente; la scelta dell'infrastruttura Terraform non pone tali versioni sotto la gestione di Terraform.

Si tratta dello stesso flusso di esecuzione di azd up in locale, ma automatizzato nell'integrazione continua. La distribuzione non sostituisce uno smoke test a livello di applicazione.

Per una versione di sola applicazione rispetto all'infrastruttura esistente, eseguire azd deploy senza ripetere il provisioning quando la configurazione dell'infrastruttura rimane invariata. Mantenere il provisioning delle risorse condivise all'interno del flusso di lavoro del team della piattaforma se tale team ne gestisce il ciclo di vita.

Se il team dell'applicazione deve usare Terraform anche per gestire l'agente logico, utilizzate le fasi di distribuzione autonome di Terraform. Questo percorso separa l'infrastruttura di base, la compilazione e il push delle immagini e gli aggiornamenti delle definizioni dell'agente senza richiedere azd.

Configurare GitHub Actions

Dopo aver eseguito azd pipeline config, esaminare .github/workflows/azure-dev.yml. Mantenere i passaggi di configurazione e autenticazione di Terraform generati se si sceglie Terraform.

L'esempio seguente illustra il flusso di provisioning e distribuzione. Per Terraform, configura le tre variabili RS_* del repository dal tuo backend e imposta TERRAFORM_VERSION sulla versione di Terraform approvata. Non sono necessari questi valori per Bicep.

name: Azure Developer CLI

on:
  push:
    branches:
      - main
  workflow_dispatch:

permissions:
  id-token: write
  contents: read

concurrency:
  group: hosted-agent-deployment
  cancel-in-progress: false

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 }}
      ARM_CLIENT_ID: ${{ vars.AZURE_CLIENT_ID }}
      ARM_TENANT_ID: ${{ vars.AZURE_TENANT_ID }}
      ARM_SUBSCRIPTION_ID: ${{ vars.AZURE_SUBSCRIPTION_ID }}
      ARM_USE_OIDC: "true"
      RS_RESOURCE_GROUP: ${{ vars.RS_RESOURCE_GROUP }}
      RS_STORAGE_ACCOUNT: ${{ vars.RS_STORAGE_ACCOUNT }}
      RS_CONTAINER_NAME: ${{ vars.RS_CONTAINER_NAME }}
    steps:
      - name: Checkout
        uses: actions/checkout@v4

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

      - name: Install Terraform
        if: ${{ hashFiles('infra/**/*.tf') != '' }}
        uses: hashicorp/setup-terraform@v3
        with:
          terraform_version: ${{ vars.TERRAFORM_VERSION }}
          terraform_wrapper: false

      - 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 infrastructure
        run: azd provision --no-prompt

      - name: Deploy agent
        run: azd deploy --no-prompt

Il gruppo di concorrenza serializza le distribuzioni di questo workflow. Coordina eventuali altri repository o strumenti che distribuiscono lo stesso agente; un gruppo di concorrenza di GitHub non è un meccanismo di blocco valido per l'intero servizio.

L'autenticazione del provider Azure di Terraform e l'autenticazione azd sono separate. Mantenere le ARM_* impostazioni OIDC e il azd passaggio di accesso. Non aggiungere un segreto client di lunga durata esclusivamente perché l'infrastruttura usa Terraform.

Annotazioni

Installare le estensioni in CI perché l'immagine del runner non le include. microsoft.foundry aggrega le sette estensioni di base, non la valutazione, il set di dati, l'ottimizzazione o le estensioni del modello rilasciate separatamente. L'installazione del solo azure.ai.agents installa anche le relative dipendenze. Vedere Installare le estensioni Foundry.

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.

Per Terraform, configurare anche il back-end remoto, l'installazione di Terraform e l'autenticazione per il back-end e i provider. Non copiare in Azure Pipelines i presupposti specifici di GitHub relativi all'ambiente OIDC. Vedere Configurare Azure Pipelines.

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 connection list --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 connection list --no-prompt --output json

I comandi delle risorse di base risolvono un --project-endpoint esplicito, quindi l'ambiente azd attivo, il contesto globale e il fallback della shell. Un ambiente senza una chiave endpoint persistente può anche risolvere il valore della shell nella fase dell'ambiente. I comandi dipendenti dalla configurazione, agent show ad esempio richiedono ancora un elemento locale azure.yaml; un endpoint da solo non è sufficiente.

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 la distribuzione, usare azd ai agent eval run per eseguire la ricetta di valutazione rapida archiviata:

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.

Questo comando non espone i quality gate --fail-on dell'estensione valutazione del progetto. Per far fallire la CI al raggiungimento di una soglia definita, installare l'estensione facoltativaazure.ai.evaluations, eseguire lo scaffolding della valutazione con azd ai eval init e registrare gli asset configurati con azd ai eval create. Usare il --help di ciascun comando per i requisiti di configurazione.

Eseguire il commit della configurazione risultante evals/azure.eval.yaml , quindi eseguire:

azd ai eval run start --fail-on pass-rate=0.8 --no-prompt

I due formati di configurazione di valutazione non sono intercambiabili. L'estensione di valutazione del progetto usa evals/azure.eval.yaml, non la valutazione rapida eval.yaml. Eseguire azd ai eval run start --help per le opzioni di controllo qualità supportate.

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.

Convalidare un candidato prima dell'innalzamento di livello di produzione

Per impostazione predefinita, un endpoint Foundry segue la versione più recente. Una pipeline che esegue il deployment e poi i test può quindi modificare il traffico di produzione prima di eseguire i test.

Per le versioni gestite, aggiungere la produzione alla versione esistente prima della distribuzione. Acquisire la versione creata dalla distribuzione, convalidare esattamente quel candidato e promuoverlo solo dopo l'approvazione.

azd deploy attende che la versione venga attivata, ma la prontezza da sola non basta a stabilire che l'agente si comporti correttamente. Utilizzare una nuova sessione vincolata a una versione specifica e verificare che il contenuto della risposta sia quello previsto. Non considerare un output non vuoto della CLI come indicazione di un test smoke riuscito.

Durante la distribuzione, azd applica anche le impostazioni degli endpoint configurate per l'agente. Rivedi queste impostazioni e gli hook di distribuzione per evitare che sovrascrivano il pin di produzione. Mantenere la promozione separata dal normale azd deploy e dal provisioning dell'infrastruttura.

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.

Importante

I ruoli di Controllo degli accessi in base al ruolo di Foundry sono stati recentemente rinominati. Foundry User, Foundry Owner, Foundry Account Owner e Foundry Project Manager erano precedentemente denominati Azure AI User, Azure AI Owner, Azure AI Account Owner e Azure AI Project Manager. È possibile che i nomi precedenti vengano visualizzati in alcune posizioni durante l'esecuzione della ridenominazione. Gli ID ruolo e le autorizzazioni di base sono invariati dalla ridenominazione.

Problema Soluzione
azd ext install non riesce nell'integrazione continua Verificare che lo strumento di esecuzione abbia accesso a Internet e azd 1.36.0 o versione successiva per il set di estensioni corrente.
AuthorizationFailed durante il provisioning Verificare che l'entità di servizio abbia i ruoli Collaboratore e Foundry Owner.
Estensioni di Foundry non trovate Aggiungere azd ext install microsoft.foundry, o la singola estensione, prima di qualsiasi comando azd ai o azd up.
Segreti non disponibili Verificare che il comando azd pipeline config sia stato completato e che i segreti siano visibili nelle impostazioni del repository.