Identidades de agentes: padrões de agentes autónomos e interativos

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

Para orientações detalhadas sobre identidades de agentes, consulte a documentação da plataforma de identidade de agente Microsoft.

Visão geral

As identidades dos agentes suportam dois padrões principais:

  • Agente Autónomo: O agente opera no seu próprio contexto de aplicação.
  • Agente Interativo: Um agente interativo opera em nome do utilizador.

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

  • AgentIdentity - GUID da identidade do agente.
  • AgentUsername - Nome principal de utilizador (UPN) para utilizador específico.
  • AgentUserId - ID de objeto de utilizador (OID) para utilizador específico, como alternativa ao UPN.

Regras de precedência

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

Configuração do Microsoft Entra ID

Antes de configurar as identidades dos agentes na sua aplicação, configure os componentes necessários no Microsoft Entra ID. Para registar uma nova aplicação no locatário Microsoft Entra ID, consulte Registar uma aplicação.

Pré-requisitos para identidades de agentes

  1. Registo da candidatura ao agente:

    • Registe a aplicação do agente principal no Microsoft Entra ID.
    • Configure permissões para APIs de fluxo descendente.
    • Configurar as credenciais do cliente (FIC+MSI, certificado ou segredo).

  2. Configuração da identidade do agente:

    • Crie identidades de agentes usando o modelo de agente.
    • Atribuir as permissões necessárias às identidades dos agentes.

  3. Permissões de aplicação:

    • Conceder permissões de aplicação para cenários autónomos.
    • Conceder permissões delegadas para cenários de delegação de utilizadores.
    • Garanta que o consentimento do administrador é fornecido quando necessário.

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

Regras semânticas

Para autenticar com sucesso, deve usar corretamente os parâmetros de identidade do agente. As seguintes regras regem o uso de AgentIdentity, AgentUsername, e AgentUserId parâmetros. Siga estas regras para evitar erros de validação que o SDK devolve.

Regra 1: Requisito de Identidade de Agente

AgentUsername ou AgentUserId deve ser emparelhado com AgentIdentity.

Se especificar AgentUsername ou AgentUserId sem AgentIdentity, o pedido falha 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.

Não podes especificar tanto AgentUsername como AgentUserId em um mesmo pedido. Se fornecer ambos os parâmetros, o pedido falha 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 vs interativo

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

Parâmetros Padrão Description
AgentIdentity apenas Agente Autónomo Adquirir token de aplicação para a identidade de agente
AgentIdentity + AgentUsername Agente Interativo Adquire token de utilizador para o utilizador especificado (por UPN)
AgentIdentity + AgentUserId Agente Interativo Adquire token de utilizador para o utilizador especificado (por ID de 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 utilização

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

A aplicação agente corre de forma independente no seu próprio contexto de aplicação e recebe tokens de aplicação.

Cenário: Um serviço de processamento em lote que processa ficheiros por si só.

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

Características dos tokens:

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

Casos de uso:

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

Padrão 2: Agente de utilizador autónomo (por nome de utilizador)

O agente é executado em nome de um utilizador específico identificado pelo seu UPN.

Cenário: Um assistente de IA que atua em nome de um utilizador numa aplicação 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 nas reivindicações de token
  • Permissões: permissões interativas limitadas ao utilizador

Casos de uso:

  • Aplicativos de agente interativos
  • Assistentes de IA com delegação pelo utilizador
  • Automação com escopo de utilizador
  • Fluxos de trabalho personalizados

Padrão 3: Agente de utilizador autónomo (por ID de Objeto)

O agente trabalha em nome de um utilizador específico identificado pelo seu ID de Objeto.

Cenário: Um motor de fluxo de trabalho que processa tarefas específicas do utilizador utilizando IDs de utilizador armazenados.

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 nas reivindicações de token
  • Permissões: permissões interativas limitadas ao utilizador

Casos de uso:

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

Padrão 4: Agente interativo (atuando em nome do utilizador que o chama)

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

Cenário: Uma API da Web atuando como um agente interativo validando tokens de usuário de entrada e fazendo chamadas delegadas para serviços downstream.

Fluxo:

  1. A API do agente web recebe o token de utilizador da aplicação que chama.
  2. Valida o token através do /Validate endpoint.
  3. Adquira tokens para APIs downstream chamando /AuthorizationHeader apenas com 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 utilizador (fluxo OBO)
  • Assunto (sub): ID do objeto do usuário original
  • Agente atua como intermediário para o usuário
  • Permissões: permissões interativas com escopo definido para o usuário

Casos de uso:

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

Padrão 5: Pedido regular (sem agente)

Quando não fornece parâmetros do agente, o SDK usa a identidade do token recebido.

Cenário: fluxo padrão em substituição a (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
  • Utiliza o fluxo padrão OBO ou o fluxo de credenciais do cliente
  • Sem facetas de identidade do agente

Exemplos de código

Os trechos 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 gerir chamadas externas ao processo para o SDK com o objetivo de adquirir cabeçalhos de autorização para chamadas subsequentes de API.

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 de utilizador

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 configura mal os parâmetros de identidade do agente ou os usa incorretamente, o SDK devolve erros de validação. As secções seguintes descrevem cenários de erro comuns e as respetivas respostas. Para obter mais detalhes sobre o tratamento de erros, consulte o Guia de solução de problemas.

Ausente AgentIdentity e AgentUsername

Pedido:

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"
}

Tanto o nome de utilizador do agente como o ID do utilizador do agente foram especificados.

Pedido:

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 inválido de AgentUserId

Pedido:

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"
}

Melhores práticas

  1. Validar entrada: Valide sempre os parâmetros de identidade do agente antes de fazer pedidos.
  2. Use IDs de objetos quando disponíveis: Os IDs de objetos são mais estáveis.
  3. Implemente o tratamento adequado de erros: Trate os erros de validação da identidade do agente de forma elegante.
  4. Proteger as credenciais do agente: Proteja a identidade do agente, os IDs do cliente e as credenciais.
  5. Operações de auditoria de agentes: Registar e monitorizar o uso da identidade do agente para garantir segurança e conformidade.
  6. Teste ambos os padrões: Valide ambos os cenários autónomos e delegados nos seus testes.
  7. Intenção do documento: Documente claramente qual o padrão de agente apropriado para cada caso de uso.

Conteúdo relacionado

  • Last updated on