Planejar uma frota de agentes em um runtime compartilhado

Uma frota de agentes é um conjunto de agentes que rodam em um runtime de nuvem compartilhado. Por exemplo, uma plataforma que permite que equipes ou clientes implantem seus próprios agentes hospeda cada novo agente na mesma base de computação e código. Cada agente da frota obtém sua própria identidade de agente, portanto, suas entradas, permissões e registros de auditoria permanecem separados dos outros agentes.

O runtime contém uma credencial de blueprint de identidade de agente único e a usa para adquirir tokens para qualquer identidade de agente criada a partir desse blueprint. O runtime escolhe qual identidade de agente usar em cada solicitação de token.

Escolher entre um único agente e uma frota

Consideration Agente único Frota de agentes
Número de agentes por implantação Um Muitos são adicionados e removidos em tempo de execução
Quando as identidades do agente são criadas Antes que o agente seja implantado, por um desenvolvedor ou administrador Quando cada agente é implantado, pelo runtime ou pelo Agente 365
De onde vem a ID de identidade do agente Configuration Uma pesquisa em cada solicitação
Como o acesso é concedido Para a identidade do agente, antes que o agente seja implantado Para cada identidade do agente, quando o agente é provisionado
Guidance Criar agentes de nuvem com ASP.NET Core ou sidecar do SDK de Autenticação Este artigo e os artigos da frota que o seguem

O runtime da frota seleciona a identidade de um agente para cada operação. Siga os exemplos de frota ao longo deste percurso: os tutoriais do agente de nuvem usam uma identidade configurada e omitem a seleção de identidade por solicitação exigida por uma frota.

Components

Componente Purpose Cardinalidade
Esquema de identidade de agente Define as permissões da frota, o escopo de entrada e as funções do aplicativo. Cria e exclui identidades de agente. Um por frota ou um por tipo de agente
Credencial do blueprint Autentica o runtime como o blueprint. Use uma credencial federada de identidade gerenciada na produção. Um por blueprint
Identidade do agente Representa um agente. Recebe os tokens de acesso usados para chamar APIs. Um por agente
Conta de usuário do agente Fornece a um agente um objeto de usuário para cargas de trabalho Microsoft 365, como uma caixa de correio ou associação ao Teams. Opcional, no máximo uma por identidade de agente
Diretório do agente O repositório do runtime que mapeia cada agente para a identidade do agente e a conta de usuário do agente. Um por frota
Serviço de provisionamento Cria e exclui identidades quando os agentes são implantados e desativados. Um por frota
Intermediário de tokens Adquire tokens para uma determinada identidade de agente. Microsoft.Identity.Web no processo de runtime ou no sidecar do SDK de Autenticação. Um ou mais por runtime

Ciclo de vida do agente

  1. Implantar. Um usuário ou pipeline implanta um novo agente no runtime.
  2. Provisionamento O serviço de provisionamento cria uma identidade de agente a partir do blueprint. Se o agente precisar de recursos de usuário do Microsoft 365, ele também criará a conta de usuário de um agente. Ele registra ambas as IDs no diretório do agente e a identidade do agente recebe o acesso necessário para esse agente.
  3. Executar. Para cada operação, o runtime pesquisa a identidade do agente no diretório do agente e a passa para o agente de token.
  4. Aposentar. O serviço de provisionamento exclui a conta de usuário do agente e, em seguida, a identidade do agente e remove a entrada do diretório do agente.

Escolher como os agentes são provisionados

Option Como funciona Use-o quando
O runtime provisiona identidades O serviço de provisionamento é autenticado como o blueprint e chama Microsoft Graph para criar e excluir identidades de agente e contas de usuário do agente. O runtime controla a implantação do agente.
O Agent 365 provisiona identidades O agente 365 cria a identidade do agente quando um agente é provisionado. O runtime escuta eventos de provisionamento de agente, que incluem a ID de identidade do agente, e a registra no diretório do agente. Os agentes são criados por meio de experiências do Microsoft 365. Para obter detalhes, consulte a documentação do desenvolvedor do Agent 365.

Ambas as opções produzem a mesma entrada de diretório do agente. O restante das diretrizes da frota se aplica a qualquer opção.

Selecione a identidade do agente em cada solicitação

A credencial de blueprint pode adquirir tokens para cada identidade de agente criada a partir do blueprint. O código de runtime que escolhe a identidade do agente é, portanto, um limite de segurança.

  • Resolva a identidade do agente do diretório do agente usando uma chave que o runtime controla, como sua própria ID do agente.
  • Não aceite uma ID do cliente de identidade do agente ou a ID da conta de usuário do agente de uma solicitação, prompt ou saída da ferramenta.
  • Confirme se o chamador tem permissão para usar o agente de destino antes de solicitar um token para ele.

Planeje os limites de confiança

  • Mantenha a credencial longe do código do agente. Mantenha a credencial de blueprint no runtime ou no sidecar, nunca no código que um autor ou modelo de agente controla.
  • Isole o broker de token. Se os agentes executarem código não confiável ou fornecido pelo cliente, não deixe que esse código chame o broker de token diretamente. Um processo que pode alcançar o broker pode solicitar um token para qualquer agente na frota.
  • Separar o provisionamento da aquisição de token. O serviço de provisionamento usa tokens de blueprint que podem criar e excluir identidades. Execute-o com seu próprio caminho de acesso para que o código do agente não possa solicitar esses tokens.
  • Limite o alcance do impacto. Use mais de um blueprint quando grupos de agentes forem executados em diferentes zonas de confiança ou pertencerem a clientes diferentes.

Planejamento de limites

Um principal de blueprint pode criar no máximo 250 identidades de agente. Para uma frota maior, crie mais blueprints e atribua cada agente a um blueprint quando ele for provisionado. Registre o blueprint na entrada do diretório do agente. Para obter detalhes, consulte os principais de blueprint de identidade do Agente.

Os artigos de implementação que seguem usam um blueprint por configuração de runtime. Se você estendê-los a vários blueprints, também resolva a configuração de blueprint correspondente e a credencial para cada agente; selecionar uma ID de agente sozinha não seleciona um blueprint diferente. O registro de diretório de exemplo precisa ser estendido para esse design.

Conceder acesso a cada agente

Dê a cada identidade do agente apenas o acesso de que seu agente precisa. Conceda permissões de aplicativo, permissões delegadas, Azure atribuições de função e acesso a outros recursos diretamente à identidade do agente, como parte do provisionamento ou logo depois. As concessões por agente mantêm o acesso de cada agente separado, para que você possa examinar, alterar ou revogar o acesso de um agente sem afetar o restante da frota. Para obter as maneiras de conceder acesso, consulte Conceder permissões de aplicativo e conceder permissões delegadas.

Para permissões que todos os agentes da frota precisam, você pode usar permissões herdáveis como uma conveniência. Um administrador concede essas permissões uma vez na entidade de blueprint e cada identidade de agente criada a partir do blueprint as recebe em seus tokens. As permissões herdadas não aparecem na identidade do agente, portanto, as concessões por agente são mais fáceis de auditar.

Rotear solicitações de usuário para agentes

Os usuários chamam um agente de frota com um token de acesso para o escopo do access_agent blueprint. Todos os agentes da frota compartilham esse público-alvo, portanto, o token prova quem é o usuário, mas não identifica o agente. O runtime deve:

  1. Determine o agente de destino da solicitação, como de um segmento de rota.
  2. Confirme se o usuário tem permissão para usar esse agente. As funções de aplicativo no blueprint se aplicam a toda a frota, portanto, imponha o acesso por agente no runtime.
  3. Use a identidade do agente de destino para qualquer solicitação de token OBO (On-Behalf-Of).

Próxima etapa

Configurar um blueprint de identidade do agente para uma frota