Cenário: Processamento em lote autônomo do agente

Implemente o processamento em lote autônomo usando identidades de agente para executar operações sem o contexto do usuário. Esse cenário permite o processamento em lote de grandes volumes de dados, tarefas agendadas por meio de trabalhos cron, operações em segundo plano fora de sessões de usuário e fluxos de trabalho seguros de serviço para sistema. Este guia mostra como configurar o SDK do Microsoft Entra para ID do Agente e implementar padrões comuns, como trabalhos agendados e processamento baseado em fila.

Pré-requisitos

  • Uma conta Azure com uma assinatura ativa. Crie uma conta gratuitamente.
  • Microsoft Entra SDK para AgentID implantado em seu ambiente com o suporte à identidade do agente habilitado. Consulte o Guia de Instalação para obter instruções de instalação.
  • Aplicativo registrado no Microsoft Entra ID – registre um novo aplicativo no centro de administração do Microsoft Entra para seu serviço em lote. Consulte Registrar um aplicativo para obter detalhes. Registro:
    • ID do aplicativo (cliente)
    • ID do diretório (locatário)
    • Criar um segredo ou certificado do cliente para autenticação
    • Configurar permissões de aplicativo para as APIs downstream que seu trabalho em lote acessará (por exemplo, permissões de Microsoft Graph)
  • Permissões apropriadas no Microsoft Entra ID - Sua conta deve ter permissões para registrar aplicativos, configurar identidades de agente e conceder permissões de aplicativo.
  • Acesso a APIs downstream - As APIs de destino (como Microsoft Graph) devem estar acessíveis e configuradas com os âmbitos necessários para suas operações em lote.

Configuração de identidade do agente

Para obter detalhes sobre como criar identidades de agente e configurar credenciais de identidade federadas, consulte a documentação da plataforma de identidade do agente Microsoft.

Requisitos principais de configuração

Ao configurar uma identidade de agente para processamento em lote:

  1. Credenciais de identidade federadas: configurar a federação de identidade de carga de trabalho para permitir que seu aplicativo obtenha tokens sem armazenar segredos
  2. Application Permissions: conceda à identidade do agente apenas as permissões do Microsoft API do Graph (ou outras permissões de API downstream) que a operação em lote requer
  3. Environment Variables: defina ENTRA_SDK_URL para apontar para a sua instância do SDK do Microsoft Entra em execução associada à ID do Agente e armazene o agente CLIENT_ID para uso no seu código de processamento em lote
  4. Token Scope: assegure-se de que o SDK do Microsoft Entra para Agent ID está configurado para solicitar tokens no contexto da entidade de serviço, não em nome de um usuário

Implementation

Os snippets de código a seguir demonstram como implementar o processamento em lote autônomo com identidades de agente. O princípio principal é passar a identidade do agente para o SDK do Microsoft Entra para a ID do Agente e solicitar um token de aplicativo em vez de um token delegado pelo usuário.

TypeScript

Solicite um token de aplicativo usando a identidade do agente para processar operações em lote:

async function processBatchWithAgent(
  incomingToken: string,
  agentIdentity: string
) {
  const sdkUrl = process.env.ENTRA_SDK_URL!;
  
  // Get users list using agent identity (autonomous)
  const response = await fetch(
    `${sdkUrl}/DownstreamApi/Graph?` +
    `AgentIdentity=${agentIdentity}&` +
    `optionsOverride.RelativePath=users&` +
    `optionsOverride.RequestAppToken=true`,
    {
      headers: {
        'Authorization': incomingToken
      }
    }
  );
  
  const result = await response.json();
  const users = JSON.parse(result.content);
  
  // Process each user
  for (const user of users.value) {
    await processUser(user);
  }
}

async function scheduledReportGeneration() {
  const agentIdentity = process.env.AGENT_CLIENT_ID!;
  const token = await getSystemToken();
  
  // Generate reports for all departments
  const departments = await getDepartments(token, agentIdentity);
  
  for (const dept of departments) {
    await generateDepartmentReport(token, agentIdentity, dept);
  }
}

Python

Aqui está a implementação equivalente em Python usando a biblioteca de solicitações:

import requests
import os
import json

def process_batch_with_agent(incoming_token: str, agent_identity: str):
    """Process batch using autonomous agent."""
    sdk_url = os.getenv('ENTRA_SDK_URL', 'http://localhost:5000')
    
    # Get users using agent identity
    response = requests.get(
        f"{sdk_url}/DownstreamApi/Graph",
        params={
            'AgentIdentity': agent_identity,
            'optionsOverride.RelativePath': 'users',
            'optionsOverride.RequestAppToken': 'true'
        },
        headers={'Authorization': incoming_token}
    )
    
    result = response.json()
    users = json.loads(result['content'])
    
    # Process each user
    for user in users['value']:
        process_user(user)

Padrões de processamento em lote

Cenários diferentes exigem diferentes abordagens de processamento em lotes. Os snippets de código a seguir fornecem padrões para as implementações mais comuns que aproveitam as identidades do agente.

Trabalho agendado

Use trabalhos agendados quando precisar executar operações em lotes em horários específicos:

// Cron-based batch processor
import cron from 'node-cron';

// Run every day at 2 AM
cron.schedule('0 2 * * *', async () => {
  console.log('Starting nightly batch process');
  
  try {
    await runAutonomousBatch(
      process.env.AGENT_CLIENT_ID!
    );
    console.log('Batch completed successfully');
  } catch (error) {
    console.error('Batch failed:', error);
  }
});

Processamento baseado em fila

Use o processamento baseado em fila quando os itens em lote chegarem de forma assíncrona ou imprevisível:

// Process messages from queue
async function processQueueMessages(queueClient, agentIdentity: string) {
  while (true) {
    const messages = await queueClient.receiveMessages(10);
    
    for (const message of messages) {
      try {
        await processMessage(message, agentIdentity);
        await queueClient.deleteMessage(message);
      } catch (error) {
        console.error('Message processing failed:', error);
      }
    }
    
    await sleep(5000);
  }
}

Práticas recomendadas

  1. Usar permissões de aplicativo: conceda apenas as permissões de aplicativo necessárias para a operação em lote, seguindo o princípio de privilégio mínimo
  2. Implementar lógica de repetição: Gerenciar falhas transitórias com recuo exponencial para melhorar a confiabilidade
  3. Monitorar o progresso: Monitorar o progresso das tarefas em lote e registrar métricas-chave para possibilitar a solução de problemas e a análise de desempenho.
  4. Escopo de limite: solicite apenas as permissões necessárias para cada operação
  5. Operações de auditoria: registrar todas as ações do agente com detalhes sobre o que foi processado e por qual agente
  6. Controle de limitação: respeitar os limites de taxa de API e implementar estratégias de recuo apropriadas

Conteúdo relacionado

  • Last updated on