에이전트 ID 청사진을 만든 후 다음 단계는 테스트 테넌트에서 AI 에이전트를 나타내는 하나 이상의 에이전트 ID를 만드는 것입니다. 에이전트 ID 생성은 일반적으로 새 AI 에이전트를 프로비전할 때 수행됩니다.
이 문서에서는 Microsoft Graph API를 통해 에이전트 ID를 만드는 간단한 웹 서비스를 빌드하는 프로세스를 안내합니다.
테스트 목적으로 에이전트 ID를 빠르게 만들려면 이 PowerShell 모듈을 사용하여 에이전트 ID를 만들고 사용하는 것이 좋습니다.
필수 조건
에이전트 ID를 만들기 전에 다음이 있는지 확인합니다.
-
에이전트 ID 이해
- 구성된 에이전트 ID 청사진( 에이전트 청사진 만들기 참조). 만들기 프로세스에서 에이전트 ID 설계 앱 ID를 기록하십시오.
- 에이전트 ID 만들기 논리를 호스트하는 웹 서비스 또는 애플리케이션(로컬로 실행되거나 Azure에 배포됨)
에이전트 ID 설계도를 통해 액세스 토큰 가져오기
에이전트 신원 청사진을 사용하여 각 에이전트 신원을 만듭니다. 에이전트 ID 설계를 사용하여 Microsoft Entra에서 액세스 토큰을 요청합니다.
관리 ID를 자격 증명으로 사용하는 경우 먼저 관리 ID를 사용하여 액세스 토큰을 가져와야 합니다. 관리 ID 토큰은 컴퓨팅 환경에 로컬로 노출되는 IP 주소에서 요청할 수 있습니다.
자세한 내용은 관리 ID 설명서를 참조하세요.
GET http://169.254.169.254/metadata/identity/oauth2/token?api-version=2019-08-01&resource=api://AzureADTokenExchange/.default
Metadata: True
관리 ID에 대한 토큰을 얻은 후 에이전트 정체성 설계도에 대한 토큰을 요청합니다.
POST https://login.microsoftonline.com/<my-test-tenant>/oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded
client_id=<agent-blueprint-id>
scope=https://graph.microsoft.com/.default
client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer
client_assertion=<msi-token>
grant_type=client_credentials
client_secret 클라이언트 암호가 로컬 개발에서 사용되는 경우 매개 변수 대신 client_assertionclient_assertion_type매개 변수를 사용할 수도 있습니다.
Microsoft.Identity.Web을 설치하려면:
dotnet add package Microsoft.Identity.Web
Microsoft.Identity.Web 에는 액세스 토큰을 자동으로 요청하고 아웃바운드 HTTP 요청에 연결하는 인터페이스가 포함되어 있습니다.
Microsoft.Identity.Web을 사용하는 경우 다음 단계로 건너뛸 수 있습니다.
에이전트 ID 만들기
이전 단계에서 획득한 액세스 토큰을 사용하여 이제 테스트 테넌트에서 에이전트 ID를 만들 수 있습니다. 에이전트 ID 생성은 새 에이전트를 만드는 단추를 선택하는 사용자와 같은 다양한 이벤트 또는 트리거에 대한 응답으로 발생할 수 있습니다.
각 에이전트에 대해 하나의 에이전트 ID를 만드는 것이 좋지만 필요에 따라 다른 방법을 선택할 수 있습니다.
를 사용할 때 항상 OData-Version 헤더를 @odata.type포함합니다.
POST https://graph.microsoft.com/beta/serviceprincipals/Microsoft.Graph.AgentIdentity
OData-Version: 4.0
Content-Type: application/json
Authorization: Bearer <token>
{
"displayName": "My Agent Identity",
"agentIdentityBlueprintId": "<my-agent-blueprint-id>",
"sponsors@odata.bind": [
"https://graph.microsoft.com/v1.0/users/<id>",
"https://graph.microsoft.com/v1.0/groups/<id>"
],
}
Microsoft.Identity.Web을 사용하여 Microsoft Graph API 요청을 실행하여 에이전트 ID를 만들려면 다음 MISE 구성 파일을 추가합니다.
경고
클라이언트 비밀은 보안 위험으로 인해 에이전트 ID 청사진에 대한 프로덕션 환경에서 클라이언트 자격 증명으로 사용해서는 안 됩니다. 대신 관리 ID 또는 클라이언트 인증서와 함께 FIC(페더레이션 ID 자격 증명)와 같은 보다 안전한 인증 방법을 사용합니다. 이러한 메서드는 애플리케이션 구성 내에서 직접 중요한 비밀을 저장할 필요가 없도록 하여 향상된 보안을 제공합니다.
{
"AzureAd": {
"Instance": "https://login.microsoftonline.com/",
"TenantId": "<my-test-tenant>",
"ClientId": "<my-agent-blueprint-id>",
"Scopes": "access_agent",
"ClientCredentials": [
{
"SourceType": "ClientSecret",
"ClientSecret": "your-client-secret"
}
]
},
"DownstreamApis": {
"agent-identity": {
"BaseUrl": "https://graph.microsoft.com",
"RelativePath": "/beta/serviceprincipals/Microsoft.Graph.AgentIdentity",
"Scopes": ["00000003-0000-0000-c000-000000000000/.default"],
"RequestAppToken": true
}
}
}
ASP.NET Core 앱(Program.cs)에 대한 코드는 다음 예제입니다.
using Microsoft.Identity.Abstractions;
using Microsoft.Identity.Web.Resource;
using Microsoft.IdentityModel.S2S.Extensions.AspNetCore;
using MyAgent;
var builder = WebApplication.CreateBuilder(args);
// Add services to the container.
builder.Services.AddMicrosoftIdentityWebApiAuthentication(builder.Configuration)
.EnableTokenAcquisitionToCallDownstreamApi();
builder.Services.AddInMemoryTokenCaches();
var app = builder.Build();
app.UseHttpsRedirection();
app.UseAuthentication();
app.UseAuthorization();
public class AgentIdentity
{
[JsonPropertyName("@odata.type")]
public string @odata_type { get; set; } = "#Microsoft.Graph.AgentIdentity";
[JsonPropertyName("displayName")]
public string? displayName { get; set; }
[JsonPropertyName("agentIdentityBlueprintId")]
public string? agentIdentityBlueprintId { get; set; }
[JsonPropertyName("id")]
public string? id { get; set; }
[JsonPropertyName("sponsors@odata.bind")]
public string[]? sponsorsOdataBind { get; set; }
[JsonPropertyName("owners@odata.bind")]
public string[]? ownersOdataBind { get; set; }
}
// Create an Agent identity
app.MapGet("/create-agent-identity", async (HttpContext httpContext) =>
{
try
{
// Get the service to call the downstream API (preconfigured in the appsettings.json file)
IDownstreamApi downstreamApi = httpContext.RequestServices.GetRequiredService<IDownstreamApi>();
// Call the downstream API with a POST request to create an Agent Identity
var jsonResult = await downstreamApi.PostForAppAsync<AgentIdentity, AgentIdentity>(
"agent-identity",
new AgentIdentity {
displayName = "My agent identity",
agentIdentityBlueprintId = "<my-agent-blueprint-id>",
sponsorsOdataBind = new [] { "https://graph.microsoft.com/v1.0/users/<id>" }
}
);
return jsonResult?.id;
}
catch (Exception ex)
{
return ex.Message;
}
})
app.Run();
에이전트 ID 삭제
에이전트가 할당 취소되거나 제거되면 서비스에서 연결된 에이전트 ID도 삭제해야 합니다.
DELETE https://graph.microsoft.com/beta/serviceprincipals/<agent-identity-id>
OData-Version: 4.0
Content-Type: application/json
Authorization: Bearer <token>
// Delete an Agent identity
app.MapGet("/delete-agent-identity", async (HttpContext httpContext, string id) =>
{
// Get the service to call the downstream API (preconfigured in the appsettings.json file)
IDownstreamApi downstreamApi = httpContext.RequestServices.GetRequiredService<IDownstreamApi>();
// Call the downstream API with a DELETE request to remove an Agent Identity
var jsonResult = await downstreamApi.DeleteForAppAsync<string, string>(
"agent-identity",
null!,
options =>
{
options.RelativePath += $"/{id}"; // Specify the ID of the agent identity to delete
});
return jsonResult;
})