Compartilhar via

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

Importante

Você precisa fazer parte do programa de prévia Frontier para obter acesso antecipado ao Microsoft Agent 365. A Frontier conecta você diretamente às mais recentes inovações de IA da Microsoft. Prévias da Frontier estão sujeitas aos termos de pré-visualização existentes dos seus contratos com clientes. Como esses recursos ainda estão em desenvolvimento, sua disponibilidade e capacidades podem mudar ao longo do tempo.

Aqui você pode aprender a construir, hospedar, registrar e publicar um agente Agent 365 rodando no AWS Elastic Beanstalk, usando a CLI do Agent 365. O Microsoft Entra & Graph fornece a identidade do agente, permissões e blueprint, enquanto o AWS Elastic Beanstalk fornece o tempo de execução.

Se tudo o que você quer fazer é apontar seu agente para seu código que está atrás de um endpoint AWS, você só precisa deste passo: configure para hospedagem não Azure e siga todos os outros passos do Ciclo de Vida do Desenvolvimento do Agente 365.

Objetivos

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

  • Deploy agent runtime no AWS Elastic Beanstalk
  • Configure 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 apontando para a AWS
  • Criar Identidade de Agente + Usuário de Agente
  • (Opcional) Publicar para as superfícies de aplicativos do Microsoft 365
  • Interações de teste de ponta a ponta

Pré-requisitos

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

Azure / Microsoft 365 prerequisites

Confirme o acesso ao seu tenant Microsoft Entra e instale as seguintes ferramentas para criar identidades, projetos e registrar seu agente.

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.

Pré-requisitos do ambiente de desenvolvimento local

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

Crie e implante um agente .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 projeto .NET

Para agilizar sua experiência, usamos uma amostra já preparada. Clone o repositório Agent365 Samples e navegue até o dotnet\semantic-kernel\sample-agent sample.

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

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

Navegue e dotnet\semantic-kernel\sample-agent verifique se o projeto se desenvolve com sucesso:

dotnet restore
dotnet build

Configurar modelo

Siga as instruções do 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: Construir e implantar a partir do Visual Studio

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

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

  2. Selecione Publicar no AWS Elastic Beanstalk

  3. Siga o Feio de Implantação do Feijão:

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

  4. Selecionar 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 Elastic Beanstalk para empacotar e implantar o agente .NET em um ambiente Amazon Linux 2 de 64 bits; Certifique-se de que a AWS CLI/EB CLI esteja configurada e que o app seja vinculado à PORT variável de ambiente definida pelo Beanstalk.

  1. Construa e publique sua aplicação .NET:

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

    Criar Procfile com o conteúdo abaixo

    web: dotnet ./SemanticKernelSampleAgent.dll

  2. Inicialize 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

    Isso vai:

    • Criar uma aplicação Elastic Beanstalk
    • Crie um ambiente com um balanceador de carga
    • Implantar seu aplicativo
    • Providencie recursos necessários da AWS

  5. Quando terminar, pegue seu endpoint do Elastic Beanstal:

    eb status

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

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

    Essa é a messagingEndpoint interface usada pela CLI do Agent 365 Dev Tools.

Observação

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

Configure para hospedagem não-Azure

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

Importante

Para hospedagem não Azure, você deve:

  • Defina messagingEndpoint para a URL do seu Elastic Beanstalk (com /api/messages caminho)
  • Definir needDeployment como false

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.

Campo Meaning
messagingEndpoint Sua URL do Pé de Feijão Elástico + /api/messages
"needDeployment": false Diz ao CLI: 'Eu hospedo meu próprio servidor; não deploy para Azure'
deploymentProjectPath Onde .env ocorre o carimbo

Build Agent 365

Depois que você tiver o código do seu agente rodando 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 pé de feijão elástico

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 logging do Elastic Beanstalk para verificar se seu agente está recebendo 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 chegar ao seu agente, você vai ver:

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

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

Dependendo do seu ambiente:

  • Playground de agentes
  • Times (se publicados)
  • Agente Shell
  • Superfícies federadas

Agora você pode enviar mensagens e verificar seus registros do Elastic Beanstal. 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 via superfícies do Agente 365 e monitore os logs do pé de feijão elástico:

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

Sua identidade, blueprint, endpoint do bot e permissões NÃO precisam ser recriados.

Resolução de problemas

Use esta seção para diagnosticar e resolver problemas comuns ao implantar e executar 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.

Endpoint de mensagens que não recebe requisições

Confira os seguintes detalhes:

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

Questões de saúde da aplicação

Verifique a saúde ambiental:

eb health --refresh

Veja registros detalhados:

eb logs

Problemas com a vinculação de portas

Garanta que sua aplicação escute na porta especificada pela PORT variável ambiente (o Elastic Beanstalk define isso automaticamente).

Problemas de compilação ou runtime do .NET

Verifique erros de compilação usando estes comandos:

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

Verificar a versão do .NET:

dotnet --version
dotnet --list-sdks

Verifique se há problemas com a embalagem:

# List installed packages
dotnet list package

# Update packages
dotnet restore --force

Falha na cessão da licença

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

Obtendo ajuda

Mais opções de ajuda

Considere o seguinte para encontrar ajuda:

  • Last updated on