Uso de Identidad Administrada de Azure con el SDK de Copilot

Nota:

          SDK de Copilot actualmente está en Versión preliminar técnica. La funcionalidad y la disponibilidad están sujetas a cambios.

Dado que las implementaciones de Azure suelen usar Managed Identity (Entra ID) en lugar de claves de larga duración, debe realizar pasos adicionales para usar el modo BYOK en SDK de Copilot. Dado que el SDK no admite de forma nativa la autenticación Entra ID, puede usar un token portador temporal a través del campo de token de portador de la configuración del proveedor (bearer_token en Python, bearerToken en Node.js / TypeScript y .NET).

En esta guía se muestra cómo usar DefaultAzureCredential desde la biblioteca de identidades de Azure para autenticarse con modelos de Azure AI Foundry mediante SDK de Copilot.

Cómo funciona

El punto de conexión compatible con OpenAI de Azure AI Foundry acepta tokens de portador de Entra ID en lugar de claves de API estáticas. El patrón es:

Use DefaultAzureCredential para obtener un token para el https://cognitiveservices.azure.com/.default ámbito.
Pase el token mediante el campo token de portador en la configuración del proveedor BYOK (bearer_token en Python, bearerToken en Node.js / TypeScript y .NET).
Actualice el token antes de que expire. Los tokens suelen ser válidos durante aproximadamente una hora.

Diagrama que muestra el flujo de autenticación de Identidad Administrada de Azure con el SDK de Copilot.

Prerrequisitos

Una suscripción de Azure con un recurso de Azure AI Foundry implementado.
La biblioteca de identidades de Azure instalada (azure-identity para Python, @azure/identity para Node.jso Azure.Identity para .NET).

        SDK de Copilot instalado. Para obtener más información, vea [AUTOTITLE](/copilot/how-tos/copilot-sdk/sdk-getting-started).

ejemplo de Python

Instalación de dependencias

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

Reemplace por AZURE_AI_FOUNDRY_RESOURCE_URL la variable de entorno que contiene la dirección URL del recurso de Azure AI Foundry (por ejemplo, https://myresource.openai.azure.com).

Actualización de tokens para aplicaciones de ejecución prolongada

Los tokens de portador expiran después de aproximadamente una hora. En el caso de los servidores o agentes de ejecución prolongada, actualice el token antes de crear cada sesión:

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 ""

ejemplo 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();

Ejemplo 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);

Configuración de entorno

Se requiere la siguiente variable de entorno:

Variable	Descripción	Ejemplo
`AZURE_AI_FOUNDRY_RESOURCE_URL`	Dirección URL del recurso de Azure AI Foundry	`https://myresource.openai.azure.com`

No se necesita ninguna variable de entorno de clave de API: la autenticación se controla mediante DefaultAzureCredential, que admite automáticamente:

        **Identidad administrada** (asignada por el sistema o asignada por el usuario) para aplicaciones hospedadas en Azure.

        **CLI de Azure** (`az login`) para el desarrollo local.

        **Variables de entorno** (`AZURE_CLIENT_ID`, `AZURE_TENANT_ID`, `AZURE_CLIENT_SECRET`) para entidades de servicio.

        **Identidad de carga de trabajo** para Kubernetes.

Para obtener la cadena de credenciales completa, consulte la documentación de DefaultAzureCredential.

Cuándo usar este patrón

Escenario	Recomendación
Aplicación hospedada en Azure con identidad administrada	Use este patrón.
Aplicación con una entidad de servicio de Azure AD existente	Use este patrón.
Desarrollo local con `az login`	Use este patrón.
Entorno que no es de Azure con clave de API estática	Utilice BYOK estándar. Para obtener más información, consulte BYOK en el `github/copilot-sdk` repositorio.

          GitHub Copilot suscripción disponible | Use OAuth de GitHub. Para obtener más información, consulte [GitHub OAuth](https://github.com/github/copilot-sdk/blob/main/docs/setup/github-oauth.md) en el `github/copilot-sdk` repositorio. |

Lectura adicional

Para la configuración de claves de API estáticas, consulte BYOK en el github/copilot-sdk repositorio.
Para la implementación del lado servidor, consulte Configuración del SDK de Copilot para los servicios de back-end.
Para obtener documentación sobre la biblioteca de identidades de Azure, consulte Introducción a la biblioteca cliente de Identidad de Azure.