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

Aprenda a construir, hospedar, registrar e publicar um agente Agent 365 que é executado no AWS Elastic Beanstalk, usando o Agent 365 CLI. O Microsoft Entra e o Microsoft Graph fornecem a identidade do agente, permissões e blueprint, enquanto AWS Elastic Beanstalk fornece o tempo de execução.

Se você quiser direcionar seu agente para seu código que está por trás de um ponto de extremidade da AWS, só precisa da seguinte etapa: Configurar para hospedagem fora do Azure. Em seguida, siga todas as demais etapas de Introdução ao desenvolvimento do Agent 365.

Metas

Aprenda a usar o Agent 365 e o Microsoft 365 como o painel de controle e:

  • Implantar o tempo de execução do agente no AWS Elastic Beanstalk
  • Configure a365.config.json para hospedagem fora do Azure
  • Criar Blueprint de Agente no Entra ID
  • Configurar OAuth2 + permissões herdadas
  • Registrar o ponto de extremidade do sistema de mensagens do Bot Framework apontando para o AWS
  • Criar Identidade de Agente + Usuário de Agente
  • (Opcional) Publicar nas áreas de aplicativos do Microsoft 365
  • Testar interações de ponta a ponta

Pré-requisitos

Antes de começar, assegure-se de que os seguintes pré-requisitos de Azure / Microsoft 365, AWS e ambiente local estejam atendidos.

Pré-requisitos do Azure / Microsoft 365

Confirme o acesso ao locatário do Microsoft Entra e instale as ferramentas a seguir para criar identidades, blueprints e registrar o agente.

Pré-requisitos da Amazon Web Services (AWS)

Certifique-se de que os seguintes serviços e ferramentas da AWS estejam configurados para implantar e gerenciar seu ambiente Elastic Beanstalk.

Pré-requisitos do ambiente de desenvolvimento local

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

Criar e implantar um agente .NET

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

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

Crie o diretório do projeto

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

Inicialize o projeto .NET

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

O agente de exemplo Kernel semântico - C#/.NET inclui:

Acesse dotnet\semantic-kernel\sample-agent e verifique se o projeto foi criado com sucesso:

dotnet restore
dotnet build

Configurar modelo

Siga as instruções em Etapa 2: Configuração do LLM para configurar o projeto usando sua chave de API da OpenAI.

Teste localmente (opcional)

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

    # Run the application
dotnet run

  2. Teste os pontos de extremidade em outro terminal:

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

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

Criar e implantar

Escolha a opção de sua preferência para construir e implantar esta aplicação de exemplo:

Opção A: Construir e implantar no Visual Studio

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

  1. Clique com o botão direito do mouse no seu projeto no Gerenciador de Soluções.

  2. Selecione Publicar no AWS Elastic Beanstalk.

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

    • Selecione seu perfil de credenciais da AWS.
    • Selecione a região (por exemplo, us-east-1).
    • Selecione a plataforma (.NET Core on Linux).
    • Defina as configurações de 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 o Elastic Beanstalk CLI para empacotar e implantar o agente .NET em um ambiente Amazon Linux 2 de 64 bits. Certifique-se de que a AWS CLI e a EB CLI estejam configuradas. O aplicativo vincula à variável de ambiente PORT definida pelo Beanstalk.

  1. Compile 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 o Procfile com o conteúdo a seguir.

    web: dotnet ./SemanticKernelSampleAgent.dll

  2. Inicialize o Elastic Beanstalk para .NET. Você será solicitado a escolher região e plataforma:

    eb init

  3. Selecione:

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

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

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

    Esse comando:

    • Cria um aplicativo Elastic Beanstalk.
    • Cria um ambiente com um balanceador de carga.
    • Implanta seu aplicativo.
    • Provisiona os recursos necessários da AWS.

  5. Quando terminar, pegue seu ponto de extremidade do Elastic Beanstalk.

    eb status

    Anote seu ponto de extremidade. O resultado deve ser algo como:

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

    Este ponto de extremidade é o messagingEndpoint usado pela CLI do Agent 365 Dev Tools.

Observação

Em ambientes de produção, configure o HTTPS instalando um certificado SSL/TLS na plataforma Elastic Beanstalk. O Bot Framework requer HTTPS para pontos de extremidade de produção.

Configure para hospedagem fora do Azure

Crie o arquivo a365.config.json manualmente na pasta do projeto Elastic Beanstalk.

Importante

Para hospedagem que não seja do Azure, defina o valor messagingEndpoint para a URL do Elastic Beanstalk com o caminho /api/messages.

O arquivo a365.config.json deve ser semelhante a este:

{
  "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 a seguir apresenta os principais campos de configuração e seus respectivos propósitos.

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

Compilar agente do Agent 365

Depois que o código do seu agente rodar em um ponto de extremidade da AWS, siga os passos restantes de Comece o desenvolvimento do Agent 365 para configurar seu agente do Agent 365.

Verificar o agente de ponta a ponta

Use estas verificações para confirmar que seu agente hospedado na AWS está acessível, recebe atividades do Bot Framework e responde corretamente nas superfícies do Agent 365.

Verificar a conectividade do Elastic Beanstalk

Envie uma solicitação GET para seu ponto de extremidade 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 os logs do Elastic Beanstalk para verificar se seu agente está recebendo atividades do Bot Framework e respondendo corretamente.

eb logs

Ou transmita logs em tempo real:

eb logs --stream

Depois que uma mensagem é recebida pelo seu agente, você vê:

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

Testar agente a partir de superfícies do Agent 365

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

  • Playground de agentes
  • Teams (se publicado)
  • Shell do agente
  • Superfícies federadas

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

Fluxo de trabalho do desenvolvedor

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

Desenvolver e testar localmente

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

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

Compile e faça a implantação novamente para o AWS Elastic Beanstalk

Quando estiver pronto para implantar 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 as superfícies do Agent 365 e monitore os logs do Elastic Beanstalk:

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

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

Solução de Problemas

Utilize esta seção para diagnosticar e solucionar problemas comuns para implantar e executar o agente Agent 365 no AWS Elastic Beanstalk. Esta seção aborda conectividade e verificações de integridade. Também trata da vinculação de portas, erros de compilação e problemas de licenciamento.

Dica

O Guia de Solução de Problemas do Agent 365 contém recomendações de solução de problemas de alto nível, melhores práticas e links para conteúdo de solução de problemas para cada parte do ciclo de vida de desenvolvimento do Agent 365.

O ponto de extremidade de mensagens não está recebendo solicitações

Verifique os detalhes a seguir:

  • Seu ponto de extremidade é exatamente:
    http://<your-app>.elasticbeanstalk.com/api/messages
  • Seu ambiente Elastic Beanstalk está íntegro. Use a verificação utilizando 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 integridade do aplicativo

Verifique a integridade do ambiente:

eb health --refresh

Exibir logs detalhados:

eb logs

Problemas com a associação da porta

Certifique-se de que seu aplicativo esteja ouvindo na porta especificada pela variável de ambiente PORT. O Elastic Beanstalk define esse valor automaticamente.

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

Verifique erros de compilação usando 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ça falha

Atribua manualmente uma licença válida do Microsoft 365 ou utilize um fluxo para usuários não licenciados, se suportado.

  • Last updated on