Usando a Identidade Gerenciada do Azure com o SDK do Copilot

Use a Identidade Gerenciada do Azure (ID do Entra) para autenticar SDK do GitHub Copilot com modelos do Azure AI Foundry em vez de chaves de API estáticas.

Quem pode usar esse recurso?

SDK do GitHub Copilot está disponível com todos os Copilot planos.

Neste artigo

Observação

SDK do Copilot está em versão prévia técnica no momento. A funcionalidade e a disponibilidade estão sujeitas a alterações.

Como as implantações do Azure geralmente usam a Identidade Gerenciada (ID do Entra) em vez de chaves de longa duração, você precisa executar etapas extras para usar o modo BYOK no SDK do Copilot. Como o SDK não dá suporte nativo à autenticação de ID do Entra, você pode usar um token de acesso de curta duração através do campo de token de acesso da configuração do provedor (bearer_token em Python, bearerToken em Node.js/TypeScript e .NET).

Este guia mostra como usar DefaultAzureCredential da biblioteca Identidade do Azure para autenticar com modelos do Azure AI Foundry por meio de SDK do Copilot.

Como funciona

O endpoint compatível com OpenAI do Azure AI Foundry aceita tokens bearer do Entra Id em vez de chaves de API estáticas. O padrão é:

  1. Use DefaultAzureCredential para obter um token para o escopo https://cognitiveservices.azure.com/.default.
  2. Passe o token usando o campo de token de portador na configuração do provedor BYOK (bearer_token em Python, bearerToken em Node.js/TypeScript e .NET).
  3. Atualize o token antes de expirar. Os tokens normalmente são válidos por cerca de uma hora.

Diagrama mostrando o fluxo de autenticação para a Identidade Gerenciada do Azure com o SDK do Copilot.

Pré-requisitos

  • Uma assinatura do Azure com um recurso do Azure AI Foundry implantado.
  • A biblioteca de Identidade do Azure instalada (azure-identity para Python, @azure/identity para Node.jsou Azure.Identity para .NET).
  • SDK do Copilot Instalado. Para obter mais informações, consulte Introdução ao SDK do Copilot.

Exemplo de Python

Instalar dependências

pip install github-copilot-sdk azure-identity

Uso Básico

import asyncio
import os

from azure.identity import DefaultAzureCredential
from copilot import CopilotClient, PermissionHandler

COGNITIVE_SERVICES_SCOPE = "https://cognitiveservices.azure.com/.default"

async def main():
    # Get a token using Managed Identity, Azure CLI, or other credential chain
    credential = DefaultAzureCredential()
    token = credential.get_token(COGNITIVE_SERVICES_SCOPE).token

    foundry_url = os.environ["AZURE_AI_FOUNDRY_RESOURCE_URL"]

    client = CopilotClient()
    await client.start()

    session = await client.create_session(
        on_permission_request=PermissionHandler.approve_all,
        model="gpt-4.1",
        provider={
            "type": "openai",
            "base_url": f"{foundry_url.rstrip('/')}/openai/v1/",
            "bearer_token": token,  # Short-lived bearer token
            "wire_api": "responses",
        },
    )

    response = await session.send_and_wait({"prompt": "Hello from Managed Identity!"})
    print(response.data.content)

    await client.stop()

asyncio.run(main())

Substitua AZURE_AI_FOUNDRY_RESOURCE_URL pela variável de ambiente que contém a URL do recurso do Azure AI Foundry (por exemplo, https://myresource.openai.azure.com).

Atualização de token para aplicativos de execução prolongada

Os tokens de portador expiram após aproximadamente uma hora. Para servidores ou agentes de execução longa, atualize o token antes de criar cada sessão:

from azure.identity import DefaultAzureCredential
from copilot import CopilotClient, PermissionHandler

COGNITIVE_SERVICES_SCOPE = "https://cognitiveservices.azure.com/.default"

class ManagedIdentityCopilotAgent:
    """Copilot agent that refreshes Entra ID tokens for Azure AI Foundry."""

    def __init__(self, foundry_url: str, model: str = "gpt-4.1"):
        self.foundry_url = foundry_url.rstrip("/")
        self.model = model
        self.credential = DefaultAzureCredential()
        self.client = CopilotClient()

    def _get_provider_config(self) -> dict:
        """Build a provider config dict with a fresh bearer token."""
        token = self.credential.get_token(COGNITIVE_SERVICES_SCOPE).token
        return {
            "type": "openai",
            "base_url": f"{self.foundry_url}/openai/v1/",
            "bearer_token": token,
            "wire_api": "responses",
        }

    async def chat(self, prompt: str) -> str:
        """Send a prompt and return the response text."""
        # Fresh token for each session
        provider = self._get_provider_config()
        session = await self.client.create_session(
            on_permission_request=PermissionHandler.approve_all,
            model=self.model,
            provider=provider,
        )

        response = await session.send_and_wait({"prompt": prompt})
        await session.disconnect()

        return response.data.content if response else ""

exemplo de Node.js/TypeScript

import { DefaultAzureCredential } from "@azure/identity";
import { CopilotClient } from "@github/copilot-sdk";

const credential = new DefaultAzureCredential();
const tokenResponse = await credential.getToken(
    "https://cognitiveservices.azure.com/.default"
);

const client = new CopilotClient();

const session = await client.createSession({
    model: "gpt-4.1",
    provider: {
        type: "openai",
        baseUrl: `${process.env.AZURE_AI_FOUNDRY_RESOURCE_URL}/openai/v1/`,
        bearerToken: tokenResponse.token,
        wireApi: "responses",
    },
});

const response = await session.sendAndWait({ prompt: "Hello!" });
console.log(response?.data.content);

await client.stop();

Exemplo de .NET

using Azure.Identity;
using GitHub.Copilot;

var credential = new DefaultAzureCredential();
var token = await credential.GetTokenAsync(
    new Azure.Core.TokenRequestContext(
        new[] { "https://cognitiveservices.azure.com/.default" }));

await using var client = new CopilotClient();
var foundryUrl = Environment.GetEnvironmentVariable("AZURE_AI_FOUNDRY_RESOURCE_URL");

await using var session = await client.CreateSessionAsync(new SessionConfig
{
    Model = "gpt-4.1",
    Provider = new ProviderConfig
    {
        Type = "openai",
        BaseUrl = $"{foundryUrl!.TrimEnd('/')}/openai/v1/",
        BearerToken = token.Token,
        WireApi = "responses",
    },
});

var response = await session.SendAndWaitAsync(
    new MessageOptions { Prompt = "Hello from Managed Identity!" });
Console.WriteLine(response?.Data.Content);

Configuração do ambiente

A variável de ambiente a seguir é necessária:

VariableDescriçãoExemplo
AZURE_AI_FOUNDRY_RESOURCE_URLSua URL de recurso do Azure AI Foundryhttps://myresource.openai.azure.com

Nenhuma variável de ambiente de chave de API é necessária– a autenticação é tratada por DefaultAzureCredential, que dá suporte automaticamente a:

  • Identidade Gerenciada (atribuída pelo sistema ou atribuída pelo usuário) para aplicativos hospedados no Azure.
  • CLI do Azure (az login) para desenvolvimento local.
  • Variáveis de ambiente (AZURE_CLIENT_ID, AZURE_TENANT_ID, ) AZURE_CLIENT_SECRETpara entidades de serviço.
  • Identidade da carga de trabalho para Kubernetes.

Para ver a cadeia completa de credenciais, consulte a documentação do DefaultAzureCredential.

Quando usar esse padrão

ScenarioRecomendação
Aplicativo hospedado no Azure com Identidade GerenciadaUse esse padrão.
App com serviço principal existente do Azure ADUse esse padrão.
Desenvolvimento local com az loginUse esse padrão.
Ambiente não Azure com chave de API estáticaUse o padrão BYOK. Para obter mais informações, consulte BYOK no github/copilot-sdk repositório.
GitHub Copilot assinatura disponívelUse GitHub OAuth. Para obter mais informações, consulte GitHub OAuth no github/copilot-sdk repositório.

Leitura adicional