Criar um agente Agent 365 implementado no Amazon Web Services (AWS)

Saiba como compilar, alojar, registar e publicar um agente Agent 365 que é executado no AWS Elastic Beanstalk, utilizando a CLI do Agent 365. O Microsoft Entra e o Graph fornecem a identidade do agente, permissões e esquema, enquanto o AWS Elastic Beanstalk fornece o runtime.

Se pretender direcionar o seu agente para o seu código que reside atrás de um ponto final do AWS, só precisa do seguinte passo: Configurar para alojamento fora do Azure. Em seguida, siga todos os outros passos a partir de Introdução ao desenvolvimento do Agent 365.

Objetivos

Saber como utilizar o Agent 365 e o Microsoft 365 como plano de controlo e:

  • Implementar o runtime do agente no AWS Elastic Beanstalk
  • Configurar o a365.config.json para alojamento fora do Azure
  • Criar o Esquema de Agente no Entra ID
  • Configurar o OAuth2 + permissões herdáveis
  • Registar o ponto final de mensagens do Bot Framework direcionado para o AWS
  • Criar Identidade de Agente + Utilizador de Agente
  • (Opcional) Publicar nas superfícies de aplicação do Microsoft 365
  • Testar interações ponto a ponto

Pré-requisitos

Antes de começar, certifique-se de que os seguintes pré-requisitos do Azure/Microsoft 365, do AWS e do ambiente local foram satisfeitos.

Pré-requisitos do Azure/Microsoft 365

Confirme o acesso ao seu inquilino do Microsoft Entra e instale as seguintes ferramentas para criar identidades, esquemas e registar o seu agente.

Pré-requisitos do Amazon Web Services (AWS)

Certifique-se de que os seguintes serviços e ferramentas do AWS estão configurados para implementar e gerir o seu ambiente Elastic Beanstalk.

Pré-requisitos para o ambiente de desenvolvimento local

Instale e configure as seguintes ferramentas localmente para criar, executar e implementar o agente.

Criar e implementar um agente do .NET

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

  • Responde a GET /
  • Aceita atividades do Bot Framework em POST /api/messages

Criar o diretório do projeto

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

Inicializar o projeto do .NET

Para simplificar a sua experiência, este artigo utiliza um exemplo já preparado. Clone o Repositório de Exemplos do Agent365 e aceda ao exemplo dotnet\semantic-kernel\sample-agent.

O Agente de Exemplo do Kernel Semântico: C#/.NET inclui:

Aceda a dotnet\semantic-kernel\sample-agent e verifique se o projeto é compilado com sucesso:

dotnet restore
dotnet build

Configurar o modelo

Siga as instruções em Passo 2: Configuração do LLM para configurar o projeto utilizando a sua chave da API Aberta.

Testar localmente (Opcional)

  1. Antes de implementar no AWS, teste o seu agente localmente:

    # Run the application
dotnet run

  2. Teste os pontos finais noutro terminal:

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

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

Compilar e implementar

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

Opção A: Criar e implementar a partir do Visual Studio

Utilize o Toolkit do AWS para Visual Studio para publicar a aplicação no Elastic Beanstalk utilizando um assistente guiado.

  1. No Explorador de Soluções, clique com o botão direito do rato no projeto.

  2. Selecione Publicar no AWS Elastic Beanstalk.

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

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

  4. Selecione Implementar.

O assistente cria, empacota e implementa a sua aplicação no AWS.

Opção B: Criar e implementar no AWS Elastic Beanstalk com a CLI

Utilize a CLI do Elastic Beanstalk para empacotar e implementar o agente do .NET num ambiente Amazon Linux 2 de 64 bits. Certifique-se de que a CLI do AWS e a CLI do EB estão configuradas. A aplicação associa-se à variável de ambiente PORT definida pelo Beanstalk.

  1. Crie e publique a sua aplicação do .NET:

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

    Crie o Perfil com o seguinte conteúdo.

    web: dotnet ./SemanticKernelSampleAgent.dll

  2. Inicialize o Elastic Beanstalk para o .NET. Será solicitado a escolher a Região e a Plataforma:

    eb init

  3. Selecione:

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

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

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

    Este comando:

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

  5. Quando terminar, obtenha o ponto final do seu Elastic Beanstalk:

    eb status

    Anote o seu ponto final. Deve ter um aspeto semelhante a:

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

    Este ponto final é o messagingEndpoint utilizado pela CLI do Agent 365 Dev Tools.

Nota

Para ambientes de produção, configure o HTTPS adicionando um certificado de SSL/TLS no Elastic Beanstalk. O Bot Framework requer o HTTPS para pontos finais de produção.

Configurar para alojamento fora do Azure

Crie o a365.config.json manualmente na sua pasta de projeto do Elastic Beanstalk:

Importante

Para alojamento fora do Azure, defina o valor de messagingEndpoint para o URL do Elastic Beanstalk com o caminho /api/messages.

O ficheiro a365.config.json deve ter um aspeto semelhante ao seguinte:

{
  "tenantId": "YOUR_TENANT_ID",
  "environment": "prod",

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

  "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 seguinte resume campos de configuração importantes e o seu propósito.

Campo Significado
messagingEndpoint O seu URL do Elastic Beanstalk + /api/messages
deploymentProjectPath Onde ocorre o carimbo de .env

Criar o agente do Agent 365

Depois de o código do seu agente ser executado para um ponto final do AWS, siga os passos restantes de Introdução ao desenvolvimento do Agent 365 para configurar o seu agente do Agent 365.

Verificar o agente ponto a ponto

Faça estas verificações para confirmar que o seu agente alojado no AWS está acessível, recebe atividades do Bot Framework e responde corretamente nas interfaces do Agent 365.

Verificar a conectividade do Elastic Beanstalk

Envie uma pedido GET ao seu ponto final do Elastic Beanstalk.

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

O pedido deve devolver esta mensagem:

AWS Agent is running.

Verifique os registos do Elastic Beanstalk para as mensagens recebidas do Bot Framework

Utilize o Registos do Elastic Beanstalk para verificar se o seu agente está a receber atividades do Bot Framework e a responder corretamente.

eb logs

Ou transmita registos em tempo real:

eb logs --stream

Depois de mensagem chegar ao seu agente, vê:

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

Agente de teste a partir de superfícies do Agent 365

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

  • Ambiente de Demonstração de Agentes
  • Teams (se publicado)
  • Shell do Agente
  • Superfícies federadas

Pode enviar mensagens e verificar os seus registos do Elastic Beanstalk. Saber como testar agentes utilizando o SDK do Microsoft Agent 365 e validando a funcionalidade do seu agente com a ferramenta de teste Ambiente de Demonstração de Agentes.

Fluxo de trabalho do programador

Depois de concluir a configuração, siga este fluxo de trabalho para desenvolvimento iterativo:

Desenvolver e testar localmente

Utilize o modo de observação para desenvolvimento rápido com recarregamento automático:

# Automatically rebuild and restart on file changes
dotnet watch run

Faça as alterações ao seu código, guarde e teste localmente antes de implementar.

Criar e reimplantar no AWS Elastic Beanstalk

Quando estiver pronto para implementar as suas alterações:

# 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 monitorizar

Teste utilizando as interfaces do Agent 365 e monitorize os registos do Elastic Beanstalk:

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

Não precisa de recriar a sua identidade, esquema, ponto final do bot ou permissões.

Resolução de Problemas

Utilize esta secção para diagnosticar e resolver problemas comuns ao implementar e executar um Agent 365 no AWS Elastic Beanstalk. Abrange a conectividade e as verificações de estado de funcionamento. Também aborda o enlace de portas, erros de compilação e problemas de licenciamento.

Sugestão

O Guia de Resolução de Problemas do Agent 365 inclui recomendações de resolução de problemas de alto nível, melhores práticas e ligações para conteúdo de resolução de problemas para cada parte do ciclo de vida de desenvolvimento do Agent 365.

O ponto final de mensagens não está a receber pedidos

Verifique os detalhes seguintes:

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

Problemas de estado de funcionamento da aplicação

Verifique o estado de funcionamento do ambiente:

eb health --refresh

Ver registos detalhados:

eb logs

Problemas de enlace de portas

Certifique-se de que a sua aplicação escuta na porta especificada pela variável de ambiente PORT. O Elastic Beanstalk define este valor automaticamente.

Problemas de compilação ou de runtime do .NET

Verifique se existem erros de compilação utilizando estes comandos:

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

Verifique a versão do .NET:

dotnet --version
dotnet --list-sdks

Verifique se há problemas com os pacotes:

# List installed packages
dotnet list package

# Update packages
dotnet restore --force

A atribuição de licenças falha

Atribua manualmente uma licença válida do Microsoft 365 ou utilize um caminho de utilizador não licenciado, se for suportado.

  • Last updated on