Identidades de agente: patrones de agente autónomos e interactivos

Las identidades de agente permiten escenarios de autenticación sofisticados en los que una aplicación de agente actúa de forma autónoma o en nombre de los usuarios. Mediante el uso de identidades de agente con el SDK de Microsoft Entra para AgentID, puede crear agentes autónomos que operan en su propio contexto y agentes interactivos que actúan en nombre de los usuarios. Para facilitar estos escenarios, el SDK admite parámetros de consulta específicos para especificar identidades de agente y contextos de usuario.

Para obtener instrucciones detalladas sobre las identidades del agente, consulte la documentación de Microsoft agent identity platform.

Información general

Las identidades del agente admiten dos patrones principales:

  • Agente autónomo: el agente funciona en su propio contexto de aplicación.
  • Agente interactivo: un agente interactivo funciona en nombre de un usuario.

El SDK acepta tres parámetros de consulta opcionales:

  • AgentIdentity - GUID de la identidad del agente.
  • AgentUsername - Nombre principal de usuario (UPN) para un usuario específico.
  • AgentUserId - Identificador de objeto de usuario (OID) para un usuario específico, como alternativa a UPN.

Reglas de precedencia

AgentUsername y AgentUserId son mutuamente excluyentes. Las solicitudes que incluyen ambos parámetros no se validan, como se describe en la regla 2: exclusividad mutua. Proporcione solo uno de estos parámetros por solicitud.

configuración de Microsoft Entra ID

Antes de configurar las identidades de agente en la aplicación, configure los componentes necesarios en Microsoft Entra ID. Para registrar una nueva aplicación en Microsoft Entra ID inquilino, consulte Register an application.

Requisitos previos para las identidades de agente

  1. Registro de la aplicación del agente:

    • Registre la aplicación del agente principal en Microsoft Entra ID.
    • Configure los permisos de API para las API de bajada.
    • Configure las credenciales de cliente (FIC+MSI, certificado o secreto).

  2. Configuración de identidad del agente:

    • Cree identidades de agente mediante el esquema del agente.
    • Asigne los permisos necesarios a las identidades de agentes.

  3. Permisos de aplicación:

    • Conceda permisos de aplicación para escenarios autónomos.
    • Conceda permisos delegados para escenarios de delegación de usuarios.
    • Asegúrese de que se proporcione el consentimiento del administrador cuando sea necesario.

Para obtener instrucciones paso a paso detalladas sobre cómo configurar identidades de agente en Microsoft Entra ID, consulte la documentación de Microsoft agent identity platform.

Reglas semánticas

Para autenticarse correctamente, debe usar correctamente los parámetros de identidad del agente. Las reglas siguientes rigen el uso de los parámetros AgentIdentity, AgentUsername y AgentUserId. Siga estas reglas para evitar errores de validación que devuelve el SDK.

Regla 1: Requisito de identidad del agente (AgentIdentity)

AgentUsername o AgentUserId debe emparejarse con AgentIdentity.

Si especifica AgentUsername o AgentUserId sin AgentIdentity, la solicitud produce un error de validación.

# 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

Regla 2: Exclusividad mutua

AgentUsername y AgentUserId son parámetros mutuamente excluyentes.

No se pueden especificar tanto AgentUsername como AgentUserId en la misma solicitud. Si proporciona ambos parámetros, se produce un error de validación en la solicitud.

# 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

Regla 3: Autónoma frente a interactiva

La combinación de parámetros determina el patrón de autenticación:

Parámetros Modelo Description
Solo AgentIdentity Agente autónomo Obtiene el token de aplicación para la identidad del agente.
AgentIdentity + AgentUsername Agente interactivo Adquiere el token de usuario para el usuario especificado (por UPN)
AgentIdentity + AgentUserId Agente interactivo Adquiere el token de usuario para el usuario especificado (por id. de objeto)

Ejemplos:

# 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

Patrones de uso

Para cada patrón de uso, la combinación de parámetros determina el flujo de autenticación y el tipo de token adquirido.

Patrón 1: Agente autónomo

La aplicación del agente se ejecuta de forma independiente en su propio contexto de aplicación y obtiene tokens de aplicación.

Escenario: un servicio de procesamiento por lotes que procesa archivos por su cuenta.

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

Características del token:

  • Tipo de token: Token de aplicación
  • Asunto (sub): ID de objeto de la aplicación del agente
  • Token creado para la identidad del agente
  • Permisos: permisos de aplicación asignados a la identidad del agente

Casos de uso:

  • Procesamiento por lotes automatizado
  • Tareas en segundo plano
  • Operaciones de sistema a sistema
  • Trabajos programados sin contexto de usuario

Patrón 2: Agente de usuario autónomo (por nombre de usuario)

El agente se ejecuta en nombre de un usuario específico identificado por su UPN.

Escenario: asistente de IA que actúa en nombre de un usuario en una aplicación de chat.

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

Características del token:

  • Tipo de token: token de usuario
  • Asunto (sub): ID del objeto de usuario
  • Faceta de identidad del agente incluida en reclamaciones de token
  • Permisos: permisos interactivos limitados al usuario

Casos de uso:

  • Aplicaciones de agente interactivas
  • Asistentes de IA con delegación de usuarios
  • Automatización con ámbito de usuario
  • Flujos de trabajo personalizados

Patrón 3: Agente de usuario autónomo (por id. de objeto)

El agente funciona en nombre de un usuario específico identificado por su identificador de objeto.

Escenario: un motor de flujo de trabajo que procesa tareas específicas del usuario mediante identificadores de usuario almacenados.

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

Características del token:

  • Tipo de token: token de usuario
  • Asunto (sub): ID del objeto de usuario
  • Faceta de identidad del agente incluida en reclamaciones de token
  • Permisos: permisos interactivos limitados al usuario

Casos de uso:

  • Flujos de trabajo de ejecución prolongada con identificadores de usuario almacenados
  • Operaciones por lotes en nombre de varios usuarios
  • Sistemas que usan identificadores de objeto para la referencia del usuario

Patrón 4: Agente interactivo (actuando en nombre del usuario que lo llama)

Una API web del agente recibe un token de usuario, lo valida y realiza llamadas delegadas en nombre de ese usuario.

Escenario: una API web que actúa como agente interactivo que valida los tokens de usuario entrantes y realiza llamadas delegadas a los servicios de bajada.

Flujo:

  1. La API web del agente recibe el token de usuario de la aplicación que llama.
  2. Valida el token a través del endpoint /Validate.
  3. Adquiere tokens para las API descendentes llamando a /AuthorizationHeader solo con el encabezado de autorización entrante 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 del token:

  • Tipo de token: token de usuario (flujo de OBO)
  • Asunto (sub): ID de objeto del usuario original
  • El agente actúa como intermediario para el usuario
  • Permisos: permisos interactivos específicos para el usuario

Casos de uso:

  • API web que actúan como agentes
  • Servicios de agente interactivos
  • Middleware basado en agentes que delega a las API descendentes
  • Servicios que validan el contexto del usuario y lo reenvían

Patrón 5: Solicitud normal (sin agente)

Cuando no se proporcionan parámetros del agente, el SDK usa la identidad del token entrante.

Escenario: flujo estándar en nombre de (OBO) sin identidades de agente.

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

Características del token:

  • Tipo de token: depende del token entrante y la configuración
  • Usa el flujo de credenciales de cliente o OBO estándar
  • Sin facetas de identidad del agente

Ejemplos de código

Los fragmentos de código siguientes muestran cómo implementar los diferentes patrones de identidad del agente mediante varios lenguajes de programación y cómo interactuar con los puntos de conexión del SDK. El código muestra cómo controlar las llamadas fuera del proceso al SDK para adquirir encabezados de autorización para las llamadas API de nivel inferior.

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 con identidad de usuario

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 interactivo

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

Escenarios de error

Cuando se configuran de forma incorrecta los parámetros de identidad del agente o se usan incorrectamente, el SDK devuelve errores de validación. En las secciones siguientes se describen los escenarios de error comunes y sus respuestas correspondientes. Para obtener más información sobre el control de errores, consulte la Guía de solución de problemas.

Falta el AgentIdentity junto con el AgentUsername

Solicitud:

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

Respuesta:

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

AgentUsername y AgentUserId especificados

Solicitud:

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

Respuesta:

{
  "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 no válido

Solicitud:

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

Respuesta:

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

procedimientos recomendados

  1. Validar entrada: valide siempre los parámetros de identidad del agente antes de realizar solicitudes.
  2. Usar identificadores de objeto cuando estén disponibles: los identificadores de objeto son más estables.
  3. Implementar un manejo adecuado de errores: Maneje los errores de validación de identidades del agente de manera adecuada.
  4. Credenciales seguras del agente: Proteja los ID de cliente y las credenciales del agente de identidad.
  5. Operaciones del agente de auditoría: registre y supervise el uso de identidades del agente para la seguridad y el cumplimiento.
  6. Probar ambos patrones: valide escenarios autónomos y delegados en las pruebas.
  7. Intención del documento: documente claramente qué patrón de agente es adecuado para cada caso de uso.

Contenido relacionado

  • Last updated on