에이전트 ID: 자율 및 대화형 에이전트 패턴

에이전트 ID를 사용하면 에이전트 애플리케이션이 자율적으로 또는 사용자를 대신하여 동작하는 정교한 인증 시나리오를 사용할 수 있습니다. AgentID용 Microsoft Entra SDK와 함께 에이전트 ID를 사용하면 자체 컨텍스트에서 작동하는 자율 에이전트와 사용자를 대신하여 작동하는 대화형 에이전트를 모두 만들 수 있습니다. 이러한 시나리오를 용이하게 하기 위해 SDK는 에이전트 ID 및 사용자 컨텍스트를 지정하는 특정 쿼리 매개 변수를 지원합니다.

에이전트 ID에 대한 자세한 지침은 Microsoft 에이전트 ID 플랫폼 설명서 참조하세요.

개요

에이전트 ID는 다음 두 가지 기본 패턴을 지원합니다.

자치 에이전트: 에이전트는 자체 애플리케이션 컨텍스트에서 작동합니다.
대화형 에이전트: 대화형 에이전트는 사용자를 대신하여 작동합니다.

SDK는 다음 세 가지 선택적 쿼리 매개 변수를 허용합니다.

AgentIdentity - 에이전트 ID의 GUID입니다.
AgentUsername - 특정 사용자의 UPN(사용자 계정 이름)입니다.
AgentUserId - UPN 대신 특정 사용자의 OID(사용자 개체 ID)입니다.

우선 순위 규칙

AgentUsername 는 AgentUserId 상호 배타적입니다. 두 매개 변수를 모두 포함하는 요청은 규칙 2: 상호 독점성에 설명된 대로 유효성 검사에 실패합니다. 요청당 이러한 매개 변수 중 하나만 제공합니다.

Microsoft Entra ID 구성

애플리케이션에서 에이전트 ID를 구성하기 전에 Microsoft Entra ID 필요한 구성 요소를 설정합니다. Microsoft Entra ID 테넌트에 새 애플리케이션을 등록하려면 애플리케이션 등록을 참조하세요.

에이전트 ID에 대한 필수 구성 요소

에이전트 애플리케이션 등록:
- Microsoft Entra ID 부모 에이전트 애플리케이션을 등록합니다.
- 다운스트림 API에 대한 API 권한을 구성합니다.
- 클라이언트 자격 증명(FIC+MSI, 인증서 또는 비밀)을 설정합니다.
에이전트 ID 구성:
- 에이전트 청사진을 사용하여 에이전트 ID를 만듭니다.
- 에이전트 ID에 필요한 권한을 할당합니다.
애플리케이션 권한:
- 자율 시나리오에 대한 애플리케이션 권한을 부여합니다.
- 사용자 위임 시나리오에 대해 위임된 권한을 부여합니다.
- 필요한 경우 관리자 동의가 제공되었는지 확인합니다.

Microsoft Entra ID 에이전트 ID를 구성하는 방법에 대한 자세한 단계별 지침은 Microsoft 에이전트 ID 플랫폼 설명서 참조하세요.

의미 체계 규칙

성공적으로 인증하려면 에이전트 ID 매개 변수를 올바르게 사용해야 합니다. 다음 규칙은 AgentIdentity, AgentUsername, AgentUserId 매개 변수의 사용을 관리합니다. SDK가 반환하는 유효성 검사 오류를 방지하려면 다음 규칙을 따릅니다.

규칙 1: 에이전트 식별자 요구 사항

AgentUsername 또는 AgentUserId는 AgentIdentity와 쌍을 이루어야 합니다.

AgentUsername 또는 AgentUserId을(를) AgentIdentity 없이 지정하면, 요청이 유효성 검사 오류로 실패합니다.

# INVALID - AgentUsername without AgentIdentity
GET /AuthorizationHeader/Graph?AgentUsername=user@contoso.com

# VALID - AgentUsername with AgentIdentity
GET /AuthorizationHeader/Graph?AgentIdentity=agent-client-id&AgentUsername=user@contoso.com

규칙 2: 상호 독점

AgentUsername 는 AgentUserId 상호 배타적인 매개 변수입니다.

같은 요청에서 AgentUsername와 AgentUserId를 둘 다 지정할 수 없습니다. 두 매개 변수를 모두 제공하면 유효성 검사 오류와 함께 요청이 실패합니다.

# INVALID - Both AgentUsername and AgentUserId specified
GET /AuthorizationHeader/Graph?AgentIdentity=agent-id&AgentUsername=user@contoso.com&AgentUserId=user-oid

# VALID - Only AgentUsername
GET /AuthorizationHeader/Graph?AgentIdentity=agent-id&AgentUsername=user@contoso.com

# VALID - Only AgentUserId
GET /AuthorizationHeader/Graph?AgentIdentity=agent-id&AgentUserId=user-object-id

규칙 3: 자율 및 대화형

매개 변수의 조합은 인증 패턴을 결정합니다.

매개 변수	패턴	Description
`AgentIdentity`만	자율 에이전트	에이전트 ID에 대한 애플리케이션 토큰을 획득합니다.
`AgentIdentity` + `AgentUsername`	대화형 에이전트	지정된 사용자에 대한 사용자 토큰을 획득합니다(UPN별).
`AgentIdentity` + `AgentUserId`	대화형 에이전트	지정된 사용자에 대한 사용자 토큰을 획득합니다(개체 ID별).

예시들:

# Autonomous agent - application context
GET /AuthorizationHeader/Graph?AgentIdentity=agent-id

# Interactive agent - user context by username
GET /AuthorizationHeader/Graph?AgentIdentity=agent-id&AgentUsername=user@contoso.com

# Interactive agent - user context by user ID
GET /AuthorizationHeader/Graph?AgentIdentity=agent-id&AgentUserId=user-object-id

사용 패턴

각 사용 패턴에 대해 매개 변수 조합은 인증 흐름과 획득한 토큰 유형을 결정합니다.

패턴 1: 자율 에이전트

에이전트 애플리케이션은 자체 애플리케이션 컨텍스트에서 독립적으로 실행되며 애플리케이션 토큰을 가져옵니다.

시나리오: 파일을 자체적으로 처리하는 일괄 처리 서비스입니다.

GET /AuthorizationHeader/Graph?AgentIdentity=12345678-1234-1234-1234-123456789012

토큰 특성:

토큰 유형: 애플리케이션 토큰
제목(sub): 에이전트 애플리케이션의 개체 ID
에이전트의 ID에 대해 만들어진 토큰
사용 권한: 에이전트 ID에 할당된 애플리케이션 권한

사용 사례:

자동화된 일괄 처리
백그라운드 작업
시스템 간 작업
사용자 컨텍스트가 없는 예약된 작업

패턴 2: 자치 사용자 에이전트(사용자 이름별)

에이전트는 UPN으로 식별된 특정 사용자를 대신하여 실행됩니다.

시나리오: 채팅 애플리케이션에서 사용자를 대신하여 작동하는 AI 도우미입니다.

GET /AuthorizationHeader/Graph?AgentIdentity=12345678-1234-1234-1234-123456789012&AgentUsername=alice@contoso.com

토큰 특성:

토큰 유형: 사용자 토큰
제목(sub): 사용자의 개체 ID
토큰 클레임에 포함된 에이전트 ID 패싯
사용 권한: 사용자로 범위가 지정된 대화형 권한

사용 사례:

대화형 에이전트 애플리케이션
사용자 위임을 사용하는 AI 도우미
사용자 단위 자동화
개인 설정된 워크플로

패턴 3: 자치 사용자 에이전트(개체 ID별)

에이전트는 해당 개체 ID로 식별된 특정 사용자를 대신하여 작동합니다.

시나리오: 저장된 사용자 ID를 사용하여 사용자별 작업을 처리하는 워크플로 엔진입니다.

GET /AuthorizationHeader/Graph?AgentIdentity=12345678-1234-1234-1234-123456789012&AgentUserId=87654321-4321-4321-4321-210987654321

토큰 특성:

토큰 유형: 사용자 토큰
제목(sub): 사용자의 개체 ID
토큰 클레임에 포함된 에이전트 ID 패싯
사용 권한: 사용자로 범위가 지정된 대화형 권한

사용 사례:

저장된 사용자 식별자를 사용하는 장기 실행 워크플로
여러 사용자를 대신하여 일괄 처리 작업
사용자 참조에 개체 ID를 사용하는 시스템

패턴 4: 대화형 에이전트(호출하는 사용자를 대신하여 작동)

에이전트 웹 API는 사용자 토큰을 수신하고 유효성을 검사하며 해당 사용자를 대신하여 위임된 호출을 수행합니다.

시나리오: 들어오는 사용자 토큰의 유효성을 검사하고 다운스트림 서비스에 위임된 호출을 수행하는 대화형 에이전트 역할을 하는 웹 API입니다.

흐름:

에이전트 웹 API는 호출 애플리케이션에서 사용자 토큰을 받습니다.
엔드포인트를 통해 토큰의 유효성을 검사합니다 /Validate .
들어오는 Authorization 헤더와 AgentIdentity만 사용하여 /AuthorizationHeader를 호출해 다운스트림 API에 대한 토큰을 획득합니다.

# Step 1: Validate incoming user token
GET /Validate
Authorization: Bearer <user-token>

# Step 2: Get authorization header on behalf of the user
GET /AuthorizationHeader/Graph?AgentIdentity=<agent-client-id>
Authorization: Bearer <user-token>

토큰 특성:

토큰 유형: 사용자 토큰(OBO 흐름)
제목(sub): 원래 사용자의 개체 ID
에이전트는 사용자의 중개자 역할을 합니다.
사용 권한: 사용자로 범위가 지정된 대화형 권한

사용 사례:

에이전트 역할을 하는 웹 API
대화형 에이전트 서비스
다운스트림 API에 위임하는 에이전트 기반 미들웨어
사용자 컨텍스트의 유효성을 검사하고 전달하는 서비스

패턴 5: 일반 요청(에이전트 없음)

에이전트 매개 변수를 제공하지 않으면 SDK는 들어오는 토큰의 ID를 사용합니다.

시나리오: 에이전트 ID가 없는 표준 OBO(On-Behalf-of) 흐름입니다.

GET /AuthorizationHeader/Graph
Authorization: Bearer <user-token>

토큰 특성:

토큰 유형: 들어오는 토큰 및 구성에 따라 다름
표준 OBO 또는 클라이언트 자격 증명 흐름 사용
에이전트 ID 패싯 없음

코드 예제

다음 코드 조각에서는 다양한 프로그래밍 언어를 사용하여 다양한 에이전트 ID 패턴을 구현하는 방법과 SDK 엔드포인트와 상호 작용하는 방법을 보여 줍니다. 이 코드는 다운스트림 API 호출에 대한 권한 부여 헤더를 획득하기 위해 SDK에 대한 Out of process 호출을 처리하는 방법을 보여 줍니다.

TypeScript: 자율 에이전트

const sidecarUrl = "http://localhost:5000";
const Agent ID = "12345678-1234-1234-1234-123456789012";

async function runBatchJob() {
  const response = await fetch(
    `${sidecarUrl}/AuthorizationHeader/Graph?AgentIdentity=${agentId}`,
    {
      headers: {
        'Authorization': 'Bearer system-token'
      }
    }
  );
  
  const { authorizationHeader } = await response.json();
  // Use authorizationHeader for downstream API calls
}

Python: 사용자 ID가 있는 에이전트

import requests

sidecar_url = "http://localhost:5000"
agent_id = "12345678-1234-1234-1234-123456789012"
user_email = "alice@contoso.com"

response = requests.get(
    f"{sidecar_url}/AuthorizationHeader/Graph",
    params={
        "AgentIdentity": agent_id,
        "AgentUsername": user_email
    },
    headers={"Authorization": f"Bearer {system_token}"}
)

token = response.json()["authorizationHeader"]

TypeScript: 대화형 에이전트

async function delegateCall(userToken: string) {
  // Validate incoming token
  const validation = await fetch(
    `${sidecarUrl}/Validate`,
    {
      headers: { 'Authorization': `Bearer ${userToken}` }
    }
  );
  
  const claims = await validation.json();
  
  // Call downstream API on behalf of user
  const response = await fetch(
    `${sidecarUrl}/DownstreamApi/Graph`,
    {
      headers: { 'Authorization': `Bearer ${userToken}` }
    }
  );
  
  return await response.json();
}

HttpClient를 사용하여 C#

using System.Net.Http;

var httpClient = new HttpClient();

// Autonomous agent
var autonomousUrl = $"http://localhost:5000/AuthorizationHeader/Graph" +
    $"?AgentIdentity={agentClientId}";
var response = await httpClient.GetAsync(autonomousUrl);

// Delegated agent with username
var delegatedUrl = $"http://localhost:5000/AuthorizationHeader/Graph" +
    $"?AgentIdentity={agentClientId}" +
    $"&AgentUsername={Uri.EscapeDataString(userPrincipalName)}";
response = await httpClient.GetAsync(delegatedUrl);

// Delegated agent with user ID
var delegatedByIdUrl = $"http://localhost:5000/AuthorizationHeader/Graph" +
    $"?AgentIdentity={agentClientId}" +
    $"&AgentUserId={userObjectId}";
response = await httpClient.GetAsync(delegatedByIdUrl);

오류 시나리오

에이전트 ID 매개 변수를 잘못 구성하거나 잘못 사용하면 SDK가 유효성 검사 오류를 반환합니다. 다음 섹션에서는 일반적인 오류 시나리오 및 해당 응답에 대해 설명합니다. 오류 처리에 대한 자세한 내용은 문제 해결 가이드를 참조하세요.

AgentUsername이 있는 AgentIdentity 누락

요청:

GET /AuthorizationHeader/Graph?AgentUsername=user@contoso.com

응답:

{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
  "title": "Bad Request",
  "status": 400,
  "detail": "AgentUsername requires AgentIdentity to be specified"
}

AgentUsername 및 AgentUserId가 모두 지정됨

요청:

GET /AuthorizationHeader/Graph?AgentIdentity=agent-id&AgentUsername=user@contoso.com&AgentUserId=user-oid

응답:

{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
  "title": "Bad Request",
  "status": 400,
  "detail": "AgentUsername and AgentUserId are mutually exclusive"
}

AgentUserId 형식이 잘못되었습니다.

요청:

GET /AuthorizationHeader/Graph?AgentIdentity=agent-id&AgentUserId=invalid-guid

응답:

{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
  "title": "Bad Request",
  "status": 400,
  "detail": "AgentUserId must be a valid GUID"
}

모범 사례

입력 유효성 검사: 요청하기 전에 항상 에이전트 ID 매개 변수의 유효성을 검사합니다.
사용 가능한 경우 개체 ID 사용: 개체 ID가 더 안정적입니다.
적절한 오류 처리 구현: 에이전트 ID 유효성 검사 오류를 정상적으로 처리합니다.
보안 에이전트 자격 증명: 에이전트 ID 클라이언트 ID 및 자격 증명을 보호합니다.
감사 에이전트 작업: 보안 및 규정 준수에 대한 에이전트 ID 사용을 기록하고 모니터링합니다.
두 패턴 모두 테스트: 테스트에서 자율 시나리오와 위임된 시나리오의 유효성을 모두 검사합니다.
문서 의도: 각 사용 사례에 적합한 에이전트 패턴을 명확하게 문서화합니다.

피드백

이 페이지가 도움이 되었나요?

Last updated on 2026-04-19

에이전트 ID: 자율 및 대화형 에이전트 패턴

개요

우선 순위 규칙

Microsoft Entra ID 구성

에이전트 ID에 대한 필수 구성 요소

의미 체계 규칙

규칙 1: 에이전트 식별자 요구 사항

규칙 2: 상호 독점

규칙 3: 자율 및 대화형

사용 패턴

패턴 1: 자율 에이전트

패턴 2: 자치 사용자 에이전트(사용자 이름별)

패턴 3: 자치 사용자 에이전트(개체 ID별)

패턴 4: 대화형 에이전트(호출하는 사용자를 대신하여 작동)

패턴 5: 일반 요청(에이전트 없음)

코드 예제

TypeScript: 자율 에이전트

Python: 사용자 ID가 있는 에이전트

TypeScript: 대화형 에이전트

HttpClient를 사용하여 C#

오류 시나리오

AgentUsername이 있는 AgentIdentity 누락

AgentUsername 및 AgentUserId가 모두 지정됨

AgentUserId 형식이 잘못되었습니다.

모범 사례

관련 콘텐츠

피드백

추가 리소스