Configuración de CI/CD para agentes hospedados con la CLI para desarrolladores de Azure

Automatice la implementación del agente hospedado con azd pipeline config. En este artículo, se configura la integración y la entrega continuas en Acciones de GitHub o Azure DevOps y, a continuación, se aplican azd ai indicadores compatibles con los pipelines para los trabajos automáticos.

Prerequisites

• Proyecto de agente hospedado inicializado que funciona localmente con azd ai agent run y azd ai agent invoke --local. Para la instalación, consulte Inicialización de un proyecto de agente.
• Un proyecto que hayas desplegado correctamente al menos una vez con azd up. Para conocer los pasos de implementación, consulte Implementación de un agente hospedado.
• Las extensiones de azd Foundry instaladas localmente y en el ejecutor de tu pipeline.
• Una sesión autenticada azd .
• Tu código en un repositorio Git alojado en GitHub o Azure DevOps.

Configuración de la canalización

Ejecute el comando de configuración de canalización:

azd pipeline config

Este comando interactivo:

1. Detecta el proveedor de Git, como GitHub o Azure DevOps.
2. Crea una entidad de servicio para la autenticación de CI/CD.
3. Configura los secretos y las variables del repositorio con los valores de tu entorno de azd.
4. Genera un archivo de flujo de trabajo, como .github/workflows/azure-dev.yml para Acciones de GitHub o un archivo YAML de Azure Pipelines.

Revisión del flujo de canalización

La canalización generada se ejecuta al hacer push a main de forma predeterminada y realiza lo siguiente:

1. azd provision -- crea o actualiza infraestructura de Azure a partir de infra/ las plantillas de Bicep.
2. azd deploy : compila el contenedor, inserta en ACR y crea una nueva versión del agente hospedado.

Este es el mismo flujo que ejecutar azd up localmente, pero automatizado en CI.

Configuración de acciones de GitHub

Después de azd pipeline config, tendrá un archivo .github/workflows/azure-dev.yml. Un flujo de trabajo típico tiene el siguiente aspecto:

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

Configuración de Azure DevOps

azd pipeline configtambién admite Azure DevOps.

1. Seleccione "Azure DevOps" cuando se le solicite.
2. Revise el archivo generado azure-pipelines.yml .
3. Confirme que el archivo generado contiene pasos de instalación, inicio de sesión, aprovisionamiento e implementación equivalentes.

Establecer indicadores compatibles con canalizaciones

La mayoría de los comandos azd ai aceptan indicadores que los hacen seguros para ejecutarse sin supervisión en CI. Configúralos en los pasos azd ai correspondientes de tu pipeline.

• --no-prompt -- deshabilita las solicitudes interactivas. El comando genera un error rápidamente mostrando un error útil, en lugar de bloquearse al recibir la entrada. Cada azd ai comando lo admite. Configúralo siempre en CI; sin ello, la falta de un valor obligatorio puede bloquear el trabajo hasta que se agote el tiempo de espera.
• --output json -- emite una salida estructurada que puede analizar con jq, PowerShell ConvertFrom-Jsono cualquier otra herramienta JSON, para los comandos que lo admiten, como azd ai agent show y los connectioncomandos , toolbox, skilly routine . azd ai agent invoke usa --output raw en su lugar.
• --project-endpoint (-p) -- fija el punto de conexión del proyecto Microsoft Foundry para un solo comando de recurso (connection, toolbox, skill o routine). Los comandos azd ai agent determinan el proyecto a partir del entorno azd activo, la configuración global o la variable de entorno FOUNDRY_PROJECT_ENDPOINT.
• --debug -- emite un mensaje de diagnóstico detallado. Resulta útil al investigar un fallo en la CI, pero genera demasiado ruido en las ejecuciones normales.

Ejemplo:

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

Establecimiento del contexto del proyecto en CI

Los pipelines se ejecutan fuera del contexto interactivo de un azd proyecto, por lo que los comandos azd ai directos necesitan saber a qué proyecto de Foundry deben dirigirse. Elija cuál de los dos patrones siguientes se ajusta a la canalización.

Establecimiento de la variable de entorno

Establezca FOUNDRY_PROJECT_ENDPOINT una sola vez en una tarea o en todo el flujo de trabajo. Cada comando azd ai lo detecta automáticamente tras consultar la variable de entorno azd del proyecto y la configuración 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

Anclar el punto de conexión con azd ai project set

Ejecuta azd ai project set $FOUNDRY_PROJECT_ENDPOINT --no-prompt al principio del trabajo. Escribe el punto de conexión en la configuración global de azd (~/.azd/config.json), y los comandos azd ai posteriores en la misma tarea usan ese contexto.

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

La CLI resuelve el punto de conexión en este orden: la opción --project-endpoint, el entorno activo azd dentro de un proyecto azd, la configuración global establecida por azd ai project set y, por último, la variable de entorno FOUNDRY_PROJECT_ENDPOINT. Si ninguno se resuelve, el comando finaliza con un error estructurado.

Para obtener más información sobre la ejecución azd ai de comandos sin un proyecto azd en el disco, consulte Establecimiento del contexto del proyecto azd.

Verifica con eval en CI

Después de que se implemente la canalización, o de que obtenga acceso a un proyecto de destino, use azd ai agent eval run para realizar comprobaciones de regresión. Ejecuta una evaluación almacenada sobre el agente actual y da por erróneo el trabajo si las puntuaciones caen por debajo de tu umbral.

azd ai agent eval run --no-prompt

eval run resuelve eval.yaml en la raíz del proyecto de forma predeterminada, o bien puede pasar --config <path>. No regenera conjuntos de datos ni evaluadores como efecto secundario. Para abrir el conjunto de herramientas de evaluación en CI, ejecute azd ai agent eval generate primero. Ese comando requiere un agente implementado que se pueda invocar.

Configuración de implementaciones específicas del entorno

Para varios entornos, como desarrollo, ensayo y producción:

1. Crear entornos azd separados:

   azd env new staging
   azd env set AZURE_LOCATION=eastus2
   

2. Configure una canalización por entorno o use desencadenadores basados en ramas:

   • main -> producción
   • develop -> entorno de prueba

3. Utilice las variables de entorno azd propias de cada ejecución del pipeline para que los recursos estén aislados.

Administración de secretos

azd pipeline config almacena los valores siguientes como secretos de repositorio o variables:

• AZURE_CLIENT_ID -- identificador de cliente de la entidad de servicio.
• AZURE_TENANT_ID -- ID de inquilino de Microsoft Entra.
• AZURE_SUBSCRIPTION_ID -- suscripción de destino.
• AZURE_ENV_NAME -- Nombre del entorno azd.
• AZURE_LOCATION -- región de Azure.

Añade secretos específicos del agente, como las claves de la API de MCP a las que se hace referencia en el envmapa de tu azure.ai.agentservicio en azure.yaml, como secretos adicionales del repositorio. Asigne cada una de ellas a una variable de entorno azd en la canalización.

Solución de problemas de canalización

Revise los problemas comunes antes de volver a ejecutar la canalización. Para el aprovisionamiento de CI, puede que necesites Propietario de Foundry además de los roles de Azure.

Contenido relacionado

• Implemente un agente hospedado para comprender lo que sucede durante la implementación.
• referencia de YAML de Azure para revisar los detalles de la configuración de despliegue.
• Configure un pipeline de DevOps con azd para obtener la referencia completa del pipeline de azd.