Copilot SDK에서 Azure 관리 ID 사용

정적 API 키 대신 Azure 관리 ID(Entra ID)를 사용하여 Azure AI Foundry 모델로 인증 GitHub Copilot SDK 합니다.

누가 이 기능을 사용할 수 있나요?

GitHub Copilot SDK 는 모든 Copilot 계획에서 사용할 수 있습니다.

이 기사에서

참고

          코필로트 SDK가 현재 기술 미리 보기에 있습니다. 기능 및 가용성은 변경될 수 있습니다.

Azure 배포는 수명이 긴 키 대신 관리 ID (Entra ID)를 사용하는 경우가 많으므로 BYOK 모드 코필로트 SDK를 사용하려면 추가 단계를 수행해야 합니다. SDK는 기본적으로 Entra ID 인증을 지원하지 않으므로 공급자 구성의 전달자 토큰 필드(bearer_token Python, bearerToken Node.js/TypeScript 및 .NET)를 통해 단기 전달자 토큰을 사용할 수 있습니다.

이 가이드에서는 Azure Identity 라이브러리를 사용하여 Azure AI Foundry 모델에 통해 인증하는 방법을 보여 줍니다.

작동 방식

Azure AI Foundry의 OpenAI 호환 엔드포인트는 정적 API 키 대신 Entra ID의 전달자 토큰을 허용합니다. 패턴은 다음과 같습니다.

  1.        `DefaultAzureCredential`을(를) 사용하여 `https://cognitiveservices.azure.com/.default` 범위의 토큰을 가져옵니다.
  2. BYOK 공급자 구성에서 Bearer 토큰 필드를 사용하여 토큰을 전달하세요 (Python의 경우에는 bearer_token, Node.js / TypeScript 및 .NET의 경우에는 bearerToken).
  3. 만료되기 전에 토큰을 새로 고칩니다. 토큰은 일반적으로 약 1시간 동안 유효합니다.

Copilot SDK를 사용하여 Azure 관리 ID에 대한 인증 흐름을 보여 주는 다이어그램

사전 요구 사항

  • Azure AI Foundry 리소스가 배포되어 있는 Azure 구독
  • 설치된 Azure ID 라이브러리(azure-identity Python, @azure/identity Node.js또는 Azure.Identity .NET용).
  • 코필로트 SDK 설치되었습니다. 자세한 내용은 Copilot SDK 사용 시작하기을(를) 참조하세요.

Python 예제

종속성 설치

pip install github-copilot-sdk azure-identity

기본 사용법

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

"AZURE_AI_FOUNDRY_RESOURCE_URL을 https://myresource.openai.azure.com 등과 같이 Azure AI Foundry 리소스 URL을 포함하는 환경 변수로 바꾸십시오."

장기 실행 애플리케이션에 대한 토큰 새로 고침

전달자 토큰은 약 1시간 후에 만료됩니다. 서버 또는 장기 실행 에이전트의 경우 각 세션을 만들기 전에 토큰을 새로 고칩니다.

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

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

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

환경 구성

다음 환경 변수가 필요합니다.

변수설명예시
AZURE_AI_FOUNDRY_RESOURCE_URLAzure AI Foundry 리소스 URLhttps://myresource.openai.azure.com

API 키 환경 변수가 필요하지 않습니다. 인증은 자동으로 지원하는 다음을 DefaultAzureCredential통해 처리됩니다.

  • Azure 호스팅 앱에 대한 관리 ID(시스템 할당 또는 사용자 할당)입니다.
  • 로컬 개발을 위한 Azure CLI(az login).
  • 서비스 주체에 대한 환경 변수(AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_CLIENT_SECRET)입니다.
  • Kubernetes용 워크로드 아이덴티티.

전체 자격 증명 체인은 DefaultAzureCredential 설명서를 참조하세요.

이 패턴을 사용하는 경우

시나리오권장 사항
관리 ID를 사용하는 Azure 호스팅 앱이 패턴을 사용합니다.
기존 Azure AD 서비스 주체가 있는 앱이 패턴을 사용합니다.
az login를 사용한 로컬 개발이 패턴을 사용합니다.
정적 API 키를 사용하는 비 Azure 환경표준 BYOK를 사용합니다. 자세한 내용은 리포지토리의 BYOK 를 github/copilot-sdk 참조하세요.
GitHub Copilot 구독 사용 가능GitHub OAuth를 사용합니다. 자세한 내용은 리포지토리의 GitHub OAuth 를 github/copilot-sdk 참조하세요.

추가 읽기