Identidades do agente: padrões de agente autônomos e interativos

As identidades do agente permitem cenários de autenticação sofisticados em que um aplicativo de agente age de forma autônoma ou em nome dos usuários. Usando identidades de agente com o SDK do Microsoft Entra para AgentID, você pode criar agentes autônomos que operam em seu próprio contexto e agentes interativos que atuam em nome dos usuários. Para facilitar esses cenários, o SDK dá suporte a parâmetros de consulta específicos para especificar identidades de agente e contextos de usuário.

Para obter diretrizes detalhadas sobre identidades de agente, consulte a documentação da plataforma de identidade do agente Microsoft.

Visão geral

As identidades do agente dão suporte a dois padrões primários:

  • Agente Autônomo: o agente opera em seu próprio contexto de aplicativo.
  • Agente Interativo: um agente interativo opera em nome de um usuário.

O SDK aceita três parâmetros de consulta opcionais:

  • AgentIdentity - GUID da identidade do agente.
  • AgentUsername - Nome UPN para um usuário específico.
  • AgentUserId - ID de objeto de usuário (OID) para um usuário específico, como uma alternativa ao UPN.

Regras de precedência

AgentUsername e AgentUserId são mutuamente exclusivos. Solicitações que incluem ambos os parâmetros falham na validação, conforme descrito na Regra 2: exclusividade mútua. Forneça apenas um desses parâmetros por solicitação.

configuração de Microsoft Entra ID

Antes de configurar as identidades do agente em seu aplicativo, configure os componentes necessários no Microsoft Entra ID. Para registrar um novo aplicativo no locatário do Microsoft Entra ID, consulte Registrar um aplicativo.

Pré-requisitos para identidades de agente

  1. Registro de aplicativo do agente:

    • Registre o aplicativo do agente pai no Microsoft Entra ID.
    • Configurar permissões de API para APIs downstream.
    • Configurar credenciais de cliente (FIC+MSI, certificado ou segredo).

  2. Configuração de identidade do agente:

    • Crie identidades de agente usando o modelo do agente.
    • Atribua permissões necessárias às identidades do agente.

  3. Permissões de aplicativo:

    • Conceda permissões de aplicativo para cenários autônomos.
    • Conceda permissões delegadas para cenários de delegação de usuário.
    • Verifique se o consentimento do administrador é fornecido quando necessário.

Para obter instruções detalhadas passo a passo sobre como configurar identidades de agente no Microsoft Entra ID, consulte a documentação da plataforma de identidade do agente Microsoft.

Regras semânticas

Para autenticar com êxito, você deve usar os parâmetros de identidade do agente corretamente. As regras a seguir regem o uso dos parâmetros AgentIdentity, AgentUsername e AgentUserId. Siga estas regras para evitar erros de validação retornados pelo SDK.

Regra 1: Requisito AgentIdentity

AgentUsername ou AgentUserId deve ser emparelhado com AgentIdentity.

Se você especificar AgentUsername ou AgentUserId não AgentIdentity, a solicitação falhará com um erro de validação.

# 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

Regra 2: exclusividade mútua

AgentUsername e AgentUserId são parâmetros mutuamente exclusivos.

Você não pode especificar ambos AgentUsername e AgentUserId na mesma solicitação. Se você fornecer os dois parâmetros, a solicitação falhará com um erro de validação.

# 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

Regra 3: autônomo versus interativo

A combinação de parâmetros determina o padrão de autenticação:

Parâmetros Padrão Description
Somente AgentIdentity Agente Autônomo Adquire o token de aplicativo para a identidade do agente
AgentIdentity + AgentUsername Agente Interativo Adquire o token de usuário para o usuário especificado (por UPN)
AgentIdentity + AgentUserId Agente Interativo Adquire o token de usuário para o usuário especificado (por ID do objeto)

Exemplos:

# 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

Padrões de uso

Para cada padrão de uso, a combinação de parâmetros determina o fluxo de autenticação e o tipo de token adquirido.

Padrão 1: agente autônomo

O aplicativo de agente é executado independentemente em seu próprio contexto de aplicativo e obtém tokens de aplicativo.

Cenário: um serviço de processamento em lote que processa arquivos por conta própria.

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

Características de token:

  • Tipo de token: token de aplicativo
  • Assunto (sub): ID do objeto do aplicativo do agente
  • Token criado para a identidade do agente
  • Permissões: permissões de aplicativo atribuídas à identidade do agente

Casos de uso:

  • Processamento em lote automatizado
  • Tarefas em segundo plano
  • Operações sistema a sistema
  • Trabalhos agendados sem contexto de usuário

Padrão 2: agente de usuário autônomo (por nome de usuário)

O agente é executado em nome de um usuário específico identificado pelo UPN.

Cenário: um assistente de IA que atua em nome de um usuário em um aplicativo de chat.

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

Características de token:

  • Tipo de token: token de usuário
  • Assunto (sub): ID do objeto do usuário
  • Faceta de identidade do agente incluída em declarações do token
  • Permissões: permissões interativas com escopo definido para o usuário

Casos de uso:

  • Aplicativos de agente interativos
  • Assistentes de IA com delegação de usuário
  • Automação com escopo de usuário
  • Fluxos de trabalho personalizados

Padrão 3: agente de usuário autônomo (por ID de objeto)

O agente funciona em nome de um usuário específico identificado pela ID do Objeto.

Cenário: um mecanismo de fluxo de trabalho que processa tarefas específicas do usuário usando IDs de usuário armazenadas.

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

Características de token:

  • Tipo de token: token de usuário
  • Assunto (sub): ID do objeto do usuário
  • Faceta de identidade do agente incluída em declarações do token
  • Permissões: permissões interativas com escopo definido para o usuário

Casos de uso:

  • Fluxos de trabalho de execução longa com identificadores de usuário armazenados
  • Operações em lote em nome de vários usuários
  • Sistemas que usam IDs de objeto para referência de usuário

Padrão 4: agente interativo (agindo em nome do usuário que o chama)

Uma API Web do agente recebe um token de usuário, valida e faz chamadas delegadas em nome desse usuário.

Cenário: uma API web atuando como um agente interativo, validando tokens de usuário recebidos e fazendo chamadas delegadas para serviços downstream.

Fluxo:

  1. A API Web do agente recebe o token de usuário do aplicativo de chamada.
  2. Valida o token por meio do endpoint /Validate.
  3. Adquire tokens para APIs downstream chamando /AuthorizationHeader apenas com o cabeçalho de Autorização de entrada AgentIdentity.
# 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>

Características de token:

  • Tipo de token: token de usuário (fluxo OBO)
  • Assunto (sub): ID do objeto do usuário original
  • O agente atua como intermediário para o usuário
  • Permissões: permissões interativas com escopo para o usuário

Casos de uso:

  • APIs Web que atuam como agentes
  • Serviços de agente interativos
  • Middleware baseado em agente que delega a APIs downstream
  • Serviços que validam e encaminham o contexto do usuário

Padrão 5: solicitação regular (sem agente)

Quando você não fornece parâmetros de agente, o SDK usa a identidade do token de entrada.

Cenário: fluxo padrão em nome de (OBO) sem identidades de agente.

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

Características de token:

  • Tipo de token: depende do token de entrada e da configuração
  • Usa o fluxo de credenciais de cliente ou OBO padrão
  • Nenhuma faceta de identidade do agente

Exemplos de código

Os snippets de código a seguir demonstram como implementar os diferentes padrões de identidade do agente usando várias linguagens de programação e como interagir com os pontos de extremidade do SDK. O código demonstra como gerenciar chamadas de processos externos para o SDK, a fim de adquirir cabeçalhos de autorização para chamadas de API downstream.

TypeScript: agente autônomo

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: Agente com identidade do usuário

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: Agente interativo

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

C# com HttpClient

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

Cenários de erro

Quando você configura incorretamente os parâmetros de identidade do agente ou os usa incorretamente, o SDK retorna erros de validação. As seções a seguir descrevem cenários de erro comuns e suas respostas correspondentes. Para obter mais detalhes sobre o tratamento de erros, consulte o Guia de solução de problemas.

Identidade do Agente faltando junto com o Nome de Usuário do Agente

Solicitação:

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

Resposta:

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

AgentUsername e AgentUserId foram especificados

Solicitação:

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

Resposta:

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

Formato AgentUserId inválido

Solicitação:

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

Resposta:

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

Práticas recomendadas

  1. Validar entrada: sempre valide os parâmetros de identidade do agente antes de fazer solicitações.
  2. Use IDs de objeto quando disponível: as IDs de objeto são mais estáveis.
  3. Implemente o tratamento de erros adequado: manipule os erros de validação de identidade do agente normalmente.
  4. Credenciais do agente seguras: proteger as IDs de identidade do agente e suas credenciais.
  5. Operações do agente de auditoria: registre e monitore o uso de identidade do agente para segurança e conformidade.
  6. Teste ambos os padrões: valide cenários autônomos e delegados em seus testes.
  7. Intenção do documento: documente claramente qual padrão de agente é apropriado para cada caso de uso.

Conteúdo relacionado

  • Last updated on