Construa um agente Agent 365 implantado na Amazon Web Services (AWS)

Aprenda a construir, hospedar, registrar e publicar um agente Agent 365 que roda no AWS Elastic Beanstalk, usando a CLI do Agent 365. Microsoft Entra e Graph fornecem a identidade do agente, permissões e blueprint, enquanto o AWS Elastic Beanstalk fornece o runtime.

Se você quiser apontar seu agente para o código que reside por trás de um endpoint AWS, só precisa do seguinte passo: Configurar para hospedagem fora do Azure. Depois, siga todos os outros passos do Ciclo de Vida do Desenvolvimento do Agente 365.

Objetivos

Saiba como usar o Agente 365 e Microsoft 365 como o plano de controle e:

• Implantar runtime do agente no AWS Elastic Beanstalk
• Configurar a365.config.json para hospedagem não Azure
• Criar Blueprint do Agente no Entra ID
• Configurar OAuth2 + permissões herdadas
• Registrar o endpoint de mensagens do Bot Framework que aponta para a AWS
• Criar Identidade de Agente + Usuário de Agente
• (Opcional) Publicar em ambientes de aplicativos do Microsoft 365
• Testar interações de ponta a ponta

Pré-requisitos

Antes de começar, verifique se os seguintes pré-requisitos de Azure/Microsoft 365, AWS e ambiente local são atendidos.

pré-requisitos de Azure/Microsoft 365

Confirme seu acesso ao cliente do Microsoft Entra e instale as seguintes ferramentas para criar identidades, planos e registrar o seu agente.

• Um inquilino do Microsoft Entra com:

  • Permissão ou função para criar aplicativos e modelos de agente (Administrador Global ou equivalente)
  • Participação no programa Frontier preview para obter acesso antecipado ao Microsoft Agent 365.
  • Pelo menos uma licença de Microsoft 365 disponível para o usuário do Agente

• Azure CLI instalado e conectado.

• CLI do Agente 365 instalado

Pré-requisitos da Amazon Web Services (AWS)

Garanta que os seguintes serviços e ferramentas AWS estejam configurados para implantar e gerenciar seu ambiente Elastic Beanstalk.

• Conta AWS com permissões apropriadas
• Acesso ao AWS Elastic Beanstalk habilitado
• AWS CLI instalada e configurada
• Elastic Beanstalk CLI instalado

Pré-requisitos do ambiente de desenvolvimento local

Instale e configure as seguintes ferramentas localmente para construir, executar e implantar o agente.

• Code Editor: use Visual Studio Code ou Visual Studio

• .NET SDK: use .NET SDK 8.0 ou posterior

• AWS Toolkit: instale essa extensão de Visual Studio ou Visual Studio Code. Faça login usando suas credenciais AWS Identity and Access Management (IAM ).

• Acesso à API LLM: Escolha o serviço apropriado com base na configuração do seu agente ou no seu provedor de modelo preferido:

  • Chave da API OpenAI: Obtenha sua chave API OpenAI
  • Azure OpenAI: Criar e implantar um recurso Azure OpenAI para obter a chave e o ponto de extremidade da API

Criar e implantar um agente de .NET

As instruções a seguir descrevem como criar um agente mínimo que:

• Responde ao GET /
• Aceita atividades do Bot Framework no POST /api/messages

Criar diretório de projeto

mkdir aws-a365-agent
cd aws-a365-agent

Inicializar .NET projeto

Para simplificar sua experiência, este artigo utiliza um exemplo já preparado. Clone o repositório Agent365 Samples e vá para o exemplo dotnet\semantic-kernel\sample-agent.

O exemplo Semantic Kernel Sample Agent – C#/.NET inclui:

• Uma API Web de ASP.NET Core mínima
• Manipulador de mensagens do Bot Framework em /api/messages
• Endpoint de verificação de saúde em /
• Integração do Semantic Kernel para capacidades de IA

Vá para dotnet\semantic-kernel\sample-agent e verifique se o projeto foi compilado com sucesso.

dotnet restore
dotnet build

Configurar modelo

Siga as instruções no Passo 2: Configuração do LLM para configurar o projeto usando sua chave Open API.

Teste localmente (opcional)

1. Antes de implantar na AWS, teste seu agente localmente:

   # Run the application
   dotnet run
   

2. Teste os endpoints em outro terminal:

   # Test agent endpoint locally
   curl http://localhost:3978
   

3. Pressione Ctrl+C para parar o servidor local.

Criar e implantar

Escolha a opção que preferir para construir e implante esta aplicação de exemplo:

• Opção A: compilar e implantar a partir do Visual Studio
• Opção B: Construir e Implantar no AWS Elastic Beanstalk com CLI

Opção A: compilar e implantar do Visual Studio

Utilize o AWS Toolkit para Visual Studio para publicar o aplicativo no Elastic Beanstalk por meio de um assistente guiado.

1. Em Solution Explorer, clique com o botão direito do mouse no projeto.

2. Selecione Publicar no AWS Elastic Beanstalk.

3. Siga o Assistente de Implantação do Beanstalk:

   • Escolha seu perfil de credenciais AWS.
   • Selecione Região (Por exemplo, us-east-1).
   • Selecione Plataforma (.NET Core on Linux).
   • Configurar as definições do ambiente.

4. Selecione Implantar.

O assistente constrói, empacota e implanta sua aplicação na AWS.

Opção B: Construir e implantar no AWS Elastic Beanstalk com CLI

Use a CLI do Elastic Beanstalk para empacotar e implantar o agente .NET em um ambiente do Amazon Linux 2 de 64 bits. Certifique-se de que a CLI da AWS e da EB estejam configuradas. O aplicativo se vincula à variável de ambiente PORT definida pelo Beanstalk.

1. Crie e publique seu aplicativo .NET:

   # Publish for Linux runtime (AWS Elastic Beanstalk uses Amazon Linux)
   dotnet publish -c Release -o ./publish --runtime linux-x64
   

   Crie um arquivo Procfile com o seguinte conteúdo.

   web: dotnet ./SemanticKernelSampleAgent.dll
   

2. Inicializar o Elastic Beanstalk para .NET. Você é orientado a escolher Região e Plataforma:

   eb init
   

3. Selecione:

   • Plataforma: 64bit-amazon-linux-2023-v3.7.0-running-.net-8
   • Região: Sua região AWS preferida (por exemplo: us-east-1)

4. Crie um pacote de implantação e implemente:

   cd publish
   zip -r ../deploy.zip .
   cd ..
   eb create aws-a365-agent-env
   eb deploy
   

   Esse comando:

   • Cria uma aplicação Elastic Beanstalk.
   • Cria um ambiente com um balanceador de carga.
   • Implementa sua aplicação.
   • Provisiona os recursos necessários da AWS.

5. Quando terminar, pegue seu endpoint do Elastic Beanstalk.

   eb status
   

   Anote seu ponto final. O resultado deve ser algo como:

   http://aws-a365-agent-env.us-east-1.elasticbeanstalk.com
   

   Esse endpoint é o messagingEndpoint usado pela CLI do Agent 365 Dev Tools.

Configurar para hospedagem fora do Azure

Crie a365.config.json na sua pasta de projeto Elastic Beanstalk executando a365 config init:

O a365.config.json arquivo deve ficar mais ou menos assim:

{
  "tenantId": "YOUR_TENANT_ID",
  "subscriptionId": "YOUR_AZURE_SUBSCRIPTION_ID",
  "resourceGroup": "a365-aws-demo",
  "location": "westus",
  "environment": "prod",

  "messagingEndpoint": "http://aws-a365-agent-env.us-east-1.elasticbeanstalk.com/api/messages",
  "needDeployment": false,

  "agentIdentityDisplayName": "MyAwsAgent Identity",
  "agentBlueprintDisplayName": "MyAwsAgent Blueprint",
  "agentUserDisplayName": "MyAwsAgent User",
  "agentUserPrincipalName": "myawsagent@testTenant.onmicrosoft.com",
  "agentUserUsageLocation": "US",
  "managerEmail": "myManager@testTenant.onmicrosoft.com",

  "deploymentProjectPath": ".",
  "agentDescription": "AWS-hosted Agent 365 Agent"
}

A tabela a seguir resume campos de configuração importantes e seu propósito.

Agente Build Agent 365

Depois que o código do seu agente rodar em um endpoint da AWS, siga os passos restantes do Ciclo de Vida de Desenvolvimento do Agente 365 para configurar seu agente do Agente 365.

Verifique o agente de ponta a ponta

Use essas verificações para confirmar que seu agente hospedado na AWS está acessível, recebendo atividades do Bot Framework e respondendo corretamente em superfícies do Agente 365.

Verificar a conectividade do Elastic Beanstalk

Envie uma solicitação GET para seu endpoint do Elastic Beanstalk.

curl http://aws-a365-agent-env.us-east-1.elasticbeanstalk.com/

A solicitação deve retornar esta mensagem:

AWS Agent is running.

Verifique os logs do Elastic Beanstalk para mensagens recebidas do Bot Framework

Use o recurso de logging do Elastic Beanstalk para verificar se seu agente está recebendo as atividades do Bot Framework e respondendo corretamente.

eb logs

Ou faça streaming de logs em tempo real:

eb logs --stream

Depois que uma mensagem chega ao seu agente, você vê:

POST 200 /api/messages
Received activity: { ... }

Agente de teste emerge do Agente 365

Dependendo do seu ambiente, você pode testar seu agente a partir de diferentes superfícies:

• Playground de agentes
• Equipes (caso sejam publicados)
• Agente Shell
• Superfícies federadas

Você pode enviar mensagens e verificar os logs do seu Elastic Beanstalk. Aprenda a testar agentes usando o Microsoft Agent 365 SDK e a validar a funcionalidade do seu agente com a ferramenta de teste Agents Playground.

Fluxo de trabalho do desenvolvedor

Uma vez concluída a configuração, siga este fluxo de trabalho para desenvolvimento iterativo:

Desenvolver e testar localmente

Use o modo relógio para desenvolvimento rápido com recarga automática:

# Automatically rebuild and restart on file changes
dotnet watch run

Faça suas alterações no código, salve e teste localmente antes de implantar.

Construa e reimplante no AWS Elastic Beanstalk

Quando estiver pronto para implementar suas mudanças:

# Clean previous builds (optional but recommended)
dotnet clean

# Publish optimized release build
dotnet publish -c Release -o ./publish --runtime linux-x64

# Create deployment package
cd publish
zip -r ../deploy.zip .
cd ..

# Deploy to AWS
eb deploy

Testar e monitorar.

Teste usando superfícies do Agente 365 e monitore os logs do Elastic Beanstal:

# Stream logs in real-time
eb logs --stream

Você não precisa recriar sua identidade, blueprint, endpoint do bot ou permissões.

Resolução de problemas

Use esta seção para diagnosticar e resolver problemas comuns ao implantar e rodar um agente Agent 365 no AWS Elastic Beanstalk. Ela cobre conectividade e exames de saúde. Também resolve a vinculação de portas, erros de compilação e problemas de licenciamento.

O endpoint de mensagens não está recebendo requisições

Confira os seguintes detalhes:

• Seu ponto final é exatamente:
  http://<your-app>.elasticbeanstalk.com/api/messages
• O ambiente do seu Elastic Beanstalk está saudável. Use a verificação usando eb health.
• Seu grupo de segurança permite tráfego HTTP ou HTTPS de entrada.
• Não existem regras de firewall ou restrições de VPC.

Problemas de saúde da aplicação

Verifique a saúde ambiental:

eb health --refresh

Veja registros detalhados:

eb logs

Problemas com a ligação de portas

Certifique-se de que sua aplicação escute na porta especificada pela PORT variável de ambiente (o Elastic Beanstalk define esse valor automaticamente).

Problemas de build ou de runtime do .NET

Verifique erros de compilação usando estes comandos:

# Clean and rebuild
dotnet clean
dotnet build --verbosity detailed

Verifique .NET versão:

dotnet --version
dotnet --list-sdks

Verifique se há problemas com o pacote:

# List installed packages
dotnet list package

# Update packages
dotnet restore --force

Falha na cessão da licença

Atribua manualmente uma licença de Microsoft 365 válida ou use um caminho de usuário sem licença, se houver suporte.