Compartilhar via

Identidades do agente: padrões de agente autônomo e interativo

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. O uso de identidades de agente com o SDK do Microsoft Entra para o AgentID permite que agentes autônomos, que operam em seu próprio contexto, e agentes interativos, que atuam em nome dos usuários, possam operar de forma eficaz. 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 da 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 Principal de Usuário (UPN) para um usuário específico
  • AgentUserId - ID de objeto de usuário (OID) para um usuário específico, como alternativa ao UPN

Regras de precedência

Se AgentUsername e AgentUserId estiverem presentes, embora a validação impeça isso, a implementação dará precedência ao nome de usuário:

AgentUsername > AgentUserId

No entanto, fornecer ambos AgentUsername e AgentUserId deve ser evitado e resultará em um erro de validação no modo de validação estrita.

Configuração da ID do Microsoft Entra

Antes de configurar as identidades do agente em seu aplicativo, você deve configurar os componentes necessários na ID do Microsoft Entra. Para registrar um novo aplicativo no locatário do Microsoft Entra ID, consulte Registrar um aplicativo para obter mais detalhes.

Pré-requisitos para identidades de agente

  1. Registro de aplicativo do agente:

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

  2. Configuração de identidade do agente:

    • Criar identidades de agente usando o blueprint do agente
    • Atribuir as permissões necessárias às identidades de agentes

  3. Permissões de aplicativo:

    • Conceder permissões de aplicativo para cenários autônomos
    • Conceder 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 na ID do Microsoft Entra, consulte a documentação da plataforma de identidade do agente da Microsoft

Regras semânticas

Garantir o uso correto dos parâmetros de identidade do agente é crucial para a autenticação bem-sucedida. As regras a seguir regem o uso dos parâmetros AgentIdentity, AgentUsername e AgentUserId e devem ser seguidas 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 ambos forem fornecidos, 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 opera de forma independente em seu próprio contexto de aplicativo, adquirindo tokens de aplicativo.

Cenário: um serviço de processamento em lote que processa arquivos de forma autônoma.

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

Características do token:

  • Tipo de token: token de aplicativo
  • Assunto (sub): ID do objeto do aplicativo do agente
  • Token emitido 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 opera em nome de um usuário específico identificado por seu UPN.

Cenário: um assistente de IA agindo 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 do 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 opera 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 do 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 /Validate endpoint
  3. Adquira tokens para APIs downstream chamando /AuthorizationHeader usando apenas o AgentIdentity e o cabeçalho de Autorização de entrada.
# 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 do 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 nenhum parâmetro de agente é fornecido, 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 do 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 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: Agente com Identidade de 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 os parâmetros de identidade do agente são configurados incorretamente ou usados incorretamente, o SDK retorna erros de validação. Abaixo estão 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"
}

"O AgentUsername e o 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. Usar IDs de objeto quando disponível: as IDs de objeto são mais estáveis
  3. Implementar tratamento de erro adequado: manipular erros de validação de identidade do agente de forma elegante
  4. Credenciais do Agente Seguro: proteger as IDs e credenciais do cliente de identidade do agente
  5. Operações do Agente de Auditoria: Registrar e monitorar o uso de identidade do agente para segurança e conformidade
  6. Testar ambos os padrões: validar 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

Consulte Também

  • Last updated on