Liga o agente cloud do GitHub Copilot ao Azure MCP Server usando extensões azd

Utilize a extensão (azure.coding-agent) do Azure Developer CLI (azd) para dar ao agente de cloud do GitHub Copilot acesso ao Azure seguro e delimitado, com uma identidade gerida. A extensão cria a identidade gerenciada, configura a credencial federada e configura o fluxo de trabalho de Ações do GitHub em seu repositório.

Consulte Visão geral de extensões para saber como as extensões adicionam recursos ao azd.

Pré-requisitos

Instale a CLI do Azure Developer (azd). Consulte as instruções de instalação.
Subscrição do Azure que lhe permite criar grupos de recursos e identidades geridas.
Clone local do repositório GitHub que ativas para o agente cloud do Copilot.
Permissões do repositório para:
- Atualize o ambiente copilot GitHub.
- Configurar as definições do agente de nuvem do Copilot.
- Envie alterações por push para a .github/workflows pasta.
Pelo menos um Git remoto configurado para o repositório (necessário para credenciais federadas).

Instale ou atualize a extensão Copilot Cloud Agent

Instalar pela primeira vez

azd extension install azure.coding-agent

Atualize para a versão mais recente

azd extension upgrade azure.coding-agent

Verifique se está instalado:
```
azd extension list --installed
```
Você deve ver azure.coding-agent na lista.

Use a extensão do agente Copilot na cloud

A extensão do agente cloud Copilot automatiza a configuração do acesso ao Azure através de uma identidade gerida para o agente cloud do Copilot. Você também precisa executar algumas etapas manuais para concluir a configuração.

Habilitar o acesso do Azure

Dentro da raiz do diretório do repositório local, execute o seguinte comando:
```
azd coding-agent config
```
Siga as instruções na tela para concluir o fluxo de trabalho de extensão.

Durante a configuração, a extensão:
- Cria (ou reutiliza) um grupo de recursos.
- Cria uma identidade gerenciada do Azure.
- Atribui a função Leitor a essa identidade com escopo para o grupo de recursos.
- Estabelece credenciais federadas vinculando o repositório GitHub à identidade gerenciada.
- Adiciona (ou atualiza) um fluxo de copilot-setup-steps.yml trabalho e ativos relacionados.
- Guia-te a finalizar as definições do ambiente GitHub para o ambiente copilot.

Verificar a configuração (opcional)

Liste a identidade gerenciada no grupo de recursos criado (ou atualizado):
```
az identity list --resource-group <resource-group-name>
```
No GitHub, abra as Configurações>Ambientes>copilot e confirme a entrada da credencial federada que faz referência à identidade gerida (o emissor do tema deve refletir o GitHub).

Configurar o Azure MCP Server para o agente de cloud do Copilot

A azd coding-agent extensão cria uma solicitação pull para uma ramificação com o novo arquivo de fluxo de trabalho do GitHub em origin/azd-enable-copilot-coding-agent-with-azure. Se você quiser usar a conexão do Servidor MCP do Azure em sua main ramificação, mescle esta RP.

A descrição do pull request e os logs de saída da extensão na consola incluem ambos um excerto de configuração JSON que pode usar para configurar o Azure MCP Server para o agente cloud do Copilot:
```
{
    "mcpServers": {
        "Azure": {
            "type": "local",
            "command": "npx",
            "args": [
                "-y",
                "@azure/mcp@latest",
                "server",
                "start"
            ],
            "tools": [
                "*"
            ]
        }
    }
}
```
Para configurar o Servidor MCP do Azure, vá para a página Configurações do repositório.
Selecione Copilot>agente de cloud na navegação à esquerda.
Cole o trecho JSON do PR na caixa de configuração MCP e selecione Salvar configuração MCP.

Teste a extensão do agente cloud Copilot

Navegue até o repositório no GitHub.
Selecione o ícone Abrir painéis de agentes na barra de navegação superior direita.
No painel suspenso, selecione o repositório e a ramificação que utilizou para o comando azd. Se você mesclou a solicitação pull gerada no main, selecione main.
Insira um prompt que instrui especificamente o agente cloud do Copilot a usar o servidor Azure MCP que configurou, 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.
```
Pressione Enter para executar o prompt e instrua o agente cloud do Copilot a criar e executar uma nova tarefa.

Observação

Também podes executar tarefas do agente de cloud do Copilot num ramo diferente de main, selecionando esse ramo no painel destacado.
Selecione a tarefa que aparece na parte inferior do painel para navegar até a página de detalhes da tarefa.
Analise a saída para ver o agente cloud do Copilot:
- Inicie o Servidor MCP do Azure:
- Chame várias ferramentas para coletar informações sobre seus recursos do Azure:
- Exiba o grupo de recursos na saída final:

Configurar permissões na identidade gerenciada

A azd coding-agent extensão cria uma identidade gerenciada do Azure que o Servidor MCP do Azure usa para acessar seus recursos. Esta configuração permite-lhe atribuir diferentes funções à identidade gerida para controlar as capacidades e permissões do Azure MCP Server.

Por padrão, a extensão atribui apenas a Reader função ao escopo do grupo de recursos. Atribua funções adicionais ou amplie o escopo se o agente precisar de mais recursos. Consulte as funções incorporadas.

Por exemplo, para atribuir a Contributor função no escopo do grupo de recursos:

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

Solução de problemas

As seções a seguir destacam problemas comuns que você pode enfrentar.

Sem controles remotos git configurados

Adicione um controle remoto para que as credenciais federadas possam ser geradas:

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

Deve ter direitos de administrador para o Repositório

Configurar um repositório GitHub para o agente cloud Copilot requer direitos de administrador. Sem estes direitos, não pode atualizar o ambiente Copilot para usar credenciais de identidade geridas, nem atualizar a configuração do MCP para o repositório.

Se vir este erro, terá de elevar os seus direitos.

(!) 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)

O token de atualização expirou

Inicie sessão novamente:

azd auth login

Adicione sinalizadores como --tenant-id <tenant-id> ou --use-device-code conforme necessário.

Melhorar os resultados de diagnóstico

Utilize o modo de depuração:

azd coding-agent config --debug

Todos os comandos internos e sua saída são impressos no console.

Próximos passos

Expandir permissões de identidade (somente conforme necessário) usando atribuições de função
Integre automação adicional estendendo o fluxo de trabalho em .github/workflows/
Explore outros recursos de extensão: Visão geral das extensões
Reveja os conceitos de RBAC do Azure

Contributing

Para contribuir com os recursos da CLI do Azure Developer, consulte o guia de contribuição. As solicitações pull podem exigir a assinatura de um Contrato de Licença de Colaborador.

Código de conduta

Este projeto segue o Código de Conduta de Código Aberto da Microsoft.

Comentários

Esta página foi útil?

Última atualização a 2026-07-18