Configurar CI/CD para agentes hospedados com a CLI do Desenvolvedor do Azure

Automatize a implantação do agente hospedado com azd pipeline config. Neste artigo, você configura a integração contínua e a entrega contínua no GitHub Actions ou no Azure DevOps e, em seguida, aplica sinalizadores azd ai adequados ao pipeline para execuções não assistidas.

Pré-requisitos

• Um projeto inicializado do agente hospedado que funciona localmente com azd ai agent run e azd ai agent invoke --local. Para configurar, consulte Inicializar um projeto de agente.
• Um projeto que você implantou com êxito pelo menos uma vez com azd up. Para obter as etapas de implantação, consulte Implantar um agente hospedado.
• As extensões azd do Foundry instaladas localmente e no executor de pipeline.
• Uma azd sessão autenticada.
• Seu código em um repositório Git hospedado em GitHub ou Azure DevOps.

Configurar o pipeline

Execute o comando de configuração do pipeline:

azd pipeline config

Este comando interativo:

1. Detecta seu provedor Git, como GitHub ou Azure DevOps.
2. Cria uma entidade de serviço para autenticação de CI/CD.
3. Configura segredos e variáveis do repositório com os valores do seu ambiente do azd.
4. Gera um arquivo de fluxo de trabalho, como .github/workflows/azure-dev.yml para GitHub Actions ou um arquivo YAML Azure Pipelines.

Revisar o fluxo do pipeline

O pipeline gerado é executado quando há push para main por padrão e executa:

1. azd provision -- cria ou atualiza a infraestrutura do Azure a partir de infra/ modelos do Bicep.
2. azd deploy -- cria o contêiner, envia para o ACR e cria uma nova versão do agente alojado.

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

Configurar GitHub Actions

Depois de azd pipeline config, você terá um arquivo .github/workflows/azure-dev.yml. Um fluxo de trabalho típico se parece com:

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 dá suporte a Azure DevOps.

1. Selecione "Azure DevOps" quando solicitado.
2. Examine o arquivo gerado azure-pipelines.yml .
3. Confirme se o arquivo gerado contém etapas equivalentes de instalação, entrada, provisionamento e implantação.

Definir sinalizadores adequados ao pipeline

A maioria dos comandos azd ai aceita flags que os tornam seguros para execução sem supervisão em CI. Defina-os nas etapas azd ai relevantes do seu pipeline.

• --no-prompt -- desabilita solicitações interativas. O comando falha rapidamente com um erro útil, em vez de bloquear a entrada. Todos os azd ai comandos dão suporte a ele. Sempre defina isso na CI; sem essa configuração, a falta de um valor obrigatório pode deixar o job travado até expirar por tempo limite.
• --output json -- gera uma saída estruturada que você pode analisar com jq, PowerShell ConvertFrom-Json ou qualquer outra ferramenta JSON, para comandos que oferecem suporte a isso, como azd ai agent show e os comandos connection, 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 resolvem 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 de diagnóstico detalhada. Útil ao investigar uma falha de CI, mas gera muito ruído em execuções normais.

Exemplo:

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, portanto os comandos diretos azd ai precisam saber qual projeto do Foundry devem ter como destino. Escolha qual dos dois padrões a seguir se adapta ao seu pipeline.

Definir a variável de ambiente

Defina FOUNDRY_PROJECT_ENDPOINT uma vez no trabalho ou em todo o fluxo de trabalho. Cada comando azd ai o reconhece automaticamente após considerar o ambiente do azd no projeto e a 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

Fixar o ponto de extremidade com azd ai project set

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

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

A CLI determina o endpoint nesta ordem: a flag --project-endpoint, o ambiente azd ativo dentro de um projeto azd, a configuração global definida por azd ai project set e, por fim, a variável de ambiente FOUNDRY_PROJECT_ENDPOINT. Se nada for resolvido, o comando será encerrado com um erro estruturado.

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

Verificar com a avaliação em CI

Depois que o pipeline é implantado ou obtém acesso a um projeto de destino, use azd ai agent eval run para verificações de regressão. Execute uma avaliação armazenada em relação ao agente atual e falhe no trabalho se as pontuações estiverem abaixo do limite.

azd ai agent eval run --no-prompt

eval run resolve eval.yaml na raiz do projeto por padrão, ou você pode passar --config <path>. Ele não regenera conjuntos de dados e avaliadores como um efeito colateral. Para iniciar a suíte de eval na CI, execute azd ai agent eval generate primeiro. Esse comando requer um agente implantado que você pode invocar.

Configurar implantações específicas do ambiente

Para vários ambientes, como desenvolvimento, preparo e produção:

1. Criar ambientes azd separados:

   azd env new staging
   azd env set AZURE_LOCATION=eastus2
   

2. Configure um pipeline por ambiente, ou use gatilhos baseados em ramificações:

   • main -> produção
   • Preparo de develop>

3. Use as próprias variáveis de ambiente do azd de cada execução de pipeline para que os recursos fiquem isolados.

Gerenciar segredos

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

• AZURE_CLIENT_ID -ID do cliente da entidade de serviço.
• AZURE_TENANT_ID - ID do locatário do Microsoft Entra.
• AZURE_SUBSCRIPTION_ID -- assinatura de destino.
• AZURE_ENV_NAME -- nome do ambiente azd.
• AZURE_LOCATION -- região do Azure.

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

Solucionar problemas de pipeline

Revise os problemas comuns antes de executar o pipeline novamente. Para o provisionamento de CI, talvez você precise da função Foundry Owner, além das funções do Azure.

Conteúdo relacionado

• Implante um agente hospedado para entender o que acontece durante a implantação.
• referência de YAML do Azure para revisar os detalhes da configuração da implantação.
• Configure um pipeline de DevOps com azd para consultar a referência completa do pipeline do azd.