Configurar CI/CD para agentes alojados com o Azure Developer CLI

Automatize a implementação do seu agente alojado com azd pipeline config. Neste artigo, vai configurar a integração contínua e a entrega contínua no GitHub Actions ou no Azure DevOps e, em seguida, aplicar opções azd ai adequadas a pipelines para tarefas executadas sem intervenção.

Pré-requisitos

• Um projeto de agente hospedado inicializado que trabalha localmente com azd ai agent run e azd ai agent invoke --local. Para configuração, veja Inicializar um projeto agente.
• Um projeto com o qual já implementaste com sucesso pelo menos uma azd upvez. Para os passos de implementação, consulte Implementar um agente alojado.
• As extensões do Foundry azd instaladas localmente e no executor do seu pipeline.
• Uma sessão azd autenticada.
• O seu código num repositório Git alojado no GitHub ou no Azure DevOps.

Configurar a linha de processamento

Execute o comando de configuração do pipeline:

azd pipeline config

Este comando interativo:

1. Deteta o seu fornecedor Git, como GitHub ou Azure DevOps.
2. Cria um service principal para autenticação de CI/CD.
3. Configura os segredos e variáveis do repositório com os valores do teu ambiente azd.
4. Gera um ficheiro de workflow, como .github/workflows/azure-dev.yml para GitHub Actions, ou um ficheiro Azure Pipelines YAML.

Revise o fluxo do oleoduto

O pipeline gerado corre por defeito em push to main e executa:

1. azd provision -- cria ou atualiza a infraestrutura do Azure a partir de infra/ modelos do Bicep.
2. azd deploy -- constrói o contentor, envia para o ACR e cria uma nova versão do agente hospedado.

Este é o mesmo fluxo de executar azd up localmente, mas automatizado em CI.

Configurar Ações no GitHub

Depois de azd pipeline config, ficarás com um ficheiro .github/workflows/azure-dev.yml. Um fluxo de trabalho típico é o seguinte:

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

Configurar Azure DevOps

azd pipeline configtambém suporta Azure DevOps.

1. Selecione "Azure DevOps" quando solicitado.
2. Revise o ficheiro gerado azure-pipelines.yml .
3. Confirme se o ficheiro gerado contém passos equivalentes de instalação, log-in, provisionamento e deploy.

Definir opções compatíveis com o pipeline

A maioria dos comandos azd ai aceita opções que os tornam seguros para serem executados sem supervisão em CI. Defina estes parâmetros nos passos relevantes azd ai do seu pipeline.

• --no-prompt -- desativa os prompts interativos. O comando falha de imediato com uma mensagem de erro esclarecedora, em vez de ficar bloqueado à espera de entrada. Todos os azd ai comandos apoiam isso. Defina sempre isto em CI; sem isso, a falta de um valor obrigatório pode bloquear a tarefa até atingir o tempo limite.
• --output json -- emite uma saída estruturada que podes analisar com jq, PowerShell ConvertFrom-Json, ou qualquer outra ferramenta JSON, para comandos que a suportem, como azd ai agent show e os connectioncomandos , toolbox, skill, e routine . azd ai agent invoke usa --output raw em vez disso.
• --project-endpoint(-p) -- fixa o endpoint do projeto Microsoft Foundry para um único comando de recurso (connection, toolbox, skill, ou routine). Os comandos azd ai agent identificam o projeto a partir do ambiente ativo azd, da configuração global ou da variável de ambiente FOUNDRY_PROJECT_ENDPOINT.
• --debug -- emite uma saída diagnóstica verbosa. Útil para investigar uma falha de CI, mas ruidoso em execuções normais.

Example:

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

Definir o contexto do projeto em CI

Os pipelines são executados fora de um contexto de projeto interativo azd, por isso azd ai os comandos diretos precisam de saber a que projeto Foundry se devem dirigir. Escolhe aquele dos dois padrões seguintes que se adequa ao teu pipeline.

Definir a variável ambiente

Define FOUNDRY_PROJECT_ENDPOINT uma única vez no trabalho ou em todo o fluxo de trabalho. Todos os comandos azd ai obtêm-no automaticamente depois do azd env no projeto e da configuração global.

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

Fixe o ponto final com azd ai project set

Executa azd ai project set $FOUNDRY_PROJECT_ENDPOINT --no-prompt no início da tarefa. Ele escreve o endpoint na configuração global do azd (~/.azd/config.json), e os comandos azd ai subsequentes na mesma tarefa utilizam esse contexto.

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

A CLI resolve o endpoint nesta ordem: a --project-endpoint bandeira, o ambiente ativo azd dentro de um azd projeto, a configuração global definida por azd ai project set, e finalmente a FOUNDRY_PROJECT_ENDPOINT variável de ambiente. Se nenhuma resolver, o comando sai com um erro estruturado.

Para mais informações sobre como executar azd ai comandos sem um projeto azd no disco, veja Definir o contexto do projeto azd.

Verificar com avaliação em CI

Depois de o pipeline ser implementado, ou obter acesso a um projeto-alvo, utilize azd ai agent eval run para verificações de regressão. Faz uma avaliação armazenada contra o agente atual e falha se as pontuações caírem abaixo do teu limiar.

azd ai agent eval run --no-prompt

eval run resolve eval.yaml na raiz do projeto por predefinição, ou pode indicar --config <path>. Não regenera conjuntos de dados nem avaliadores como efeito colateral. Para executar a suíte de avaliação em CI, execute azd ai agent eval generate primeiro. Esse comando requer um agente destacado que possas invocar.

Configurar implementações específicas do ambiente

Para múltiplos ambientes, como desenvolvimento, encenação e produção:

1. Cria ambientes AZD separados:

   azd env new staging
   azd env set AZURE_LOCATION=eastus2
   

2. Configure um pipeline por ambiente ou utilize disparadores por ramificação:

   • main -> Produção
   • develop -> encenação

3. Utilize as variáveis de ambiente do azd de cada execução do pipeline para isolar os recursos.

Gerenciar segredos

azd pipeline config armazena os seguintes valores como segredos ou variáveis do repositório:

• AZURE_CLIENT_ID -- ID de cliente principal de serviço.
• AZURE_TENANT_ID -- ID do tenant do Microsoft Entra.
• AZURE_SUBSCRIPTION_ID -- subscrição do Target.
• AZURE_ENV_NAME -- nome do ambiente azd.
• AZURE_LOCATION-- Região Azure.

Adicione segredos específicos do agente, como chaves de API do MCP referenciadas no mapa env do seu serviço azure.ai.agent em azure.yaml, como segredos adicionais do repositório. Associe cada um a uma variável de ambiente azd no pipeline.

Resolução de problemas no pipeline

Revê os problemas comuns antes de executares novamente o pipeline. Para o provisionamento de CI, poderá precisar da função Foundry Owner, além das funções do Azure.

Conteúdo relacionado

• Implemente um agente hospedado para perceber o que acontece durante a implementação.
• Referência de YAML do Azure para consultar os detalhes da configuração da implementação.
• Configurar um pipeline de DevOps com o azd para obter a referência completa do pipeline do azd.