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

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

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

개요

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

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

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

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

우선 순위 규칙

둘 다 AgentUsernameAgentUserId 있는 경우 유효성 검사에서 이를 방지하지만 구현은 사용자 이름보다 우선합니다.

AgentUsername > AgentUserId

그러나 AgentUsername와 AgentUserId를 둘 다 제공하는 것은 피해야 하며, 엄격한 유효성 검사 모드에서 유효성 검사 오류가 발생할 것입니다.

Microsoft Entra ID 구성

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

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

에이전트 애플리케이션 등록:
- Microsoft Entra ID에 부모 에이전트 애플리케이션 등록
- 다운스트림 API에 대한 API 권한 구성
- 클라이언트 자격 증명 설정(FIC+MSI 또는 인증서 또는 비밀)
에이전트 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
/AuthorizationHeader을(를) AgentIdentity 및 들어오는 권한 부여 헤더와 함께 호출하여 다운스트림 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 agentId = "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 2025-11-14

다음을 통해 공유

에이전트 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 형식이 잘못되었습니다.

모범 사례

또한 참조하십시오

피드백

추가 리소스