Conecta el agente en la nube de GitHub Copilot con Azure MCP Server usando extensiones de azd

Use la extensión de Azure Developer CLI (azd) (azure.coding-agent) para conceder al agente en la nube de GitHub Copilot acceso a Azure seguro y con alcance limitado mediante una identidad administrada. La extensión crea la identidad administrada, configura la credencial federada y configura el flujo de trabajo acciones de GitHub en el repositorio.

Consulte Introducción a las extensiones para obtener información sobre cómo las extensiones agregan funcionalidades a azd.

Prerrequisitos

• Instale la CLI para desarrolladores de Azure (azd). Consulte las instrucciones de instalación.
• Suscripción de Azure que le permite crear grupos de recursos e identidades administradas.
• Clon local del repositorio de GitHub que habilites para el agente en la nube de Copilot.
• Permisos de repositorio para:
  • Actualice el entorno de copilot GitHub.
  • Configurar la configuración del agente de Copilot en la nube.
  • Inserte los cambios en la .github/workflows carpeta.
• Al menos un git remoto configurado para el repositorio (necesario para las credenciales federadas).

Instalación o actualización de la extensión del agente en la nube de Copilot

1. Instalación por primera vez

   azd extension install azure.coding-agent
   

   Actualización a la versión más reciente

   azd extension upgrade azure.coding-agent
   

2. Compruebe que está instalado:

   azd extension list --installed
   

   Debería ver azure.coding-agent en la lista.

Usa la extensión del agente de nube de Copilot

La extensión del agente en la nube de Copilot automatiza la configuración del acceso Azure a través de una identidad administrada para el agente en la nube de Copilot. También debe realizar algunos pasos manuales para completar la configuración.

Habilitación del acceso a Azure

1. Dentro de la raíz del directorio del repositorio local, ejecute el siguiente comando:

   azd coding-agent config
   

2. Siga las indicaciones en pantalla para completar el flujo de trabajo de extensión.

   Durante la configuración, la extensión:

   • Crea (o reutiliza) un grupo de recursos.
   • Crea una identidad administrada de Azure.
   • Asigna el rol de lector a esa identidad dentro del grupo de recursos.
   • Establece credenciales federadas que vinculan el repositorio de GitHub a la identidad administrada.
   • Agrega (o actualiza) un copilot-setup-steps.yml flujo de trabajo y recursos relacionados.
   • Te guía para finalizar la configuración del entorno de GitHub para copilot.

Comprobación de la configuración (opcional)

1. Enumere la identidad administrada en el grupo de recursos creado (o actualizado):

   az identity list --resource-group <resource-group-name>
   

2. En GitHub, abre Configuración>Entornos>copilot, y confirma el registro de credenciales federadas que hace referencia a la identidad administrada (el emisor del asunto debe reflejar GitHub).

Configure Azure MCP Server para el agente de nube de Copilot

1. La extensión azd coding-agent crea una solicitud de incorporación de cambios para una nueva rama que contiene el archivo de flujo de trabajo de GitHub en origin/azd-enable-copilot-coding-agent-with-azure. Si desea usar la conexión del servidor MCP de Azure en la main rama, fusione este PR.

   La descripción de la solicitud de extracción y los registros de salida de la extensión en la consola incluyen un fragmento de configuración JSON que puede utilizar para configurar Azure MCP Server para el agente en la nube de Copilot:

   {
       "mcpServers": {
           "Azure": {
               "type": "local",
               "command": "npx",
               "args": [
                   "-y",
                   "@azure/mcp@latest",
                   "server",
                   "start"
               ],
               "tools": [
                   "*"
               ]
           }
       }
   }
   

2. Para configurar el servidor de Azure MCP, vaya a la página Configuración del repositorio.

3. Seleccione Copilot>Agente de nube en el panel de navegación izquierdo.

4. Pegue el fragmento de código JSON de la solicitud de incorporación de cambios en el cuadro de configuración de MCP y seleccione Guardar configuración de MCP.

   

Pruebe la extensión del agente en la nube de Copilot

1. Vaya al repositorio en GitHub.

2. Seleccione el icono Abrir paneles de agentes en la barra de navegación superior derecha.

3. En el panel flotante, seleccione el repositorio y la rama que usó para el comando azd. Si ha combinado la solicitud de incorporación de cambios generada en main, seleccione main.

4. Escriba un mensaje que indique específicamente al agente en la nube de Copilot que use el servidor MCP de Azure que configuró, como:

   Use the Azure MCP Server to list the resource groups in my subscription.
   Do not traverse or analyze the repository at all. Use only the Azure MCP Server.
   

   Presione Intro para ejecutar la instrucción e indicar al agente en la nube de Copilot que cree y ejecute una nueva tarea.

   Nota:

   También puede ejecutar las tareas del agente en la nube de Copilot en una rama distinta de main seleccionando esa rama en el panel desplegable.

5. Seleccione la tarea que aparece en la parte inferior del panel para ir a la página de detalles de la tarea.

   

6. Revise la salida para ver el agente en la nube de Copilot:

   • Inicie el servidor MCP de Azure:

     

   • Llame a varias herramientas para recopilar información sobre los recursos de Azure:

     Captura de pantalla que muestra la llamada a la herramienta de grupo de recursos.

   • Muestra el grupo de recursos en la salida final:

     

Configuración de permisos en la identidad administrada

La azd coding-agent extensión crea una identidad administrada de Azure que usa el servidor MCP de Azure para acceder a los recursos. Esta configuración le permite asignar roles diferentes a la identidad administrada para controlar las funcionalidades y permisos de Azure servidor MCP.

De forma predeterminada, la extensión asigna solo el Reader rol al ámbito del grupo de recursos. Asigne roles adicionales o amplíe el ámbito si el agente necesita más funcionalidades. Ver roles predefinidos.

Por ejemplo, para asignar el rol de Contributor en el ámbito del grupo de recursos:

az role assignment create --assignee <principal-id-or-client-id> --role Contributor --scope /subscriptions/<subscription-id>/resourceGroups/<resource-group-name>

Solución de problemas

En las secciones siguientes se resaltan los problemas comunes que puede experimentar.

No hay ningún remoto de Git configurado

Agregue una credencial remota para que se puedan generar credenciales federadas:

git remote add origin <https://github.com/<your-org>/<your-repo>.git>
git fetch origin

Debe tener derechos de administrador en el repositorio

La configuración de un repositorio de GitHub para Copilot agente en la nube requiere derechos de administrador. Sin estos derechos, no puede actualizar el entorno de Copilot para usar credenciales de identidad administrada ni actualizar la configuración de MCP para el repositorio.

Si ve este error, deberá elevar sus derechos.

(!) An error occurred, see the readme for troubleshooting and prerequisites:
    https://github.com/Azure/azure-dev/blob/main/cli/azd/extensions/azure.coding-agent/README.md
Error: failed to create GitHub environment copilot in repository owner/repository: exit code: 1, stdout: {"message":"Must have admin rights to Repository.","documentation_url":"https://docs.github.com/rest/deployments/environments#create-or-update-an-environment","status":"403"}, stderr: gh: Must have admin rights to Repository. (HTTP 403)

El token de actualización ha expirado

Vuelva a iniciar sesión:

azd auth login

Agregue marcas como --tenant-id <tenant-id> o --use-device-code según sea necesario.

Mejora de la salida de diagnóstico

Usar el modo de depuración:

azd coding-agent config --debug

Todos los comandos internos y su salida se imprimen en la consola.

Pasos siguientes

• Expansión de los permisos de identidad (solo según sea necesario) mediante asignaciones de roles
• Integración de automatización adicional mediante la extensión del flujo de trabajo en .github/workflows/
• Exploración de otras funcionalidades de extensión: Introducción a las extensiones
• Revisión de los conceptos de RBAC de Azure

Contributing

Para contribuir a los recursos de la CLI para desarrolladores de Azure, consulte la guía de contribución. Las pull requests pueden requerir la firma de un contrato de licencia de colaborador.

Código de conducta

Este proyecto sigue el código de conducta de código abierto de Microsoft.