Sviluppare un agente Agent 365 distribuito in Amazon Web Services (AWS)

Impara a creare, ospitare, registrare e pubblicare un agente di Agent 365 che viene eseguito su AWS Elastic Beanstalk, usando l'interfaccia della riga di comando di Agent 365. Microsoft Entra e Graph forniscono l'identità, le autorizzazioni e il progetto dell'agente, mentre in AWS Elastic Beanstalk avviene la fase di esecuzione.

Se vuoi puntare l'agente al codice che risiede dietro all'endpoint AWS, ti basta seguire il passaggio: Configurare per l'hosting non Azure. Successivamente, segui tutti gli altri passaggi che trovi in Introduzione allo sviluppo con Agent 365.

Obiettivi

Impara a usare Agent 365 e Microsoft 365 come piano di controllo e:

  • Distribuire il runtime dell'agente su AWS Elastic Beanstalk
  • Configurare a365.config.json per l'hosting non Azure
  • Creare un Blueprint agente in Entra ID
  • Configurare OAuth2 + autorizzazioni ereditabili
  • Registrare l'endpoint di messaggistica del Bot Framework indirizzato a AWS
  • Creare Identità agente + Utente agente
  • (Facoltativo) Pubblicare sulle app di Microsoft 365
  • Test di interazioni end-to-end

Prerequisiti

Prima di iniziare, assicurati che i seguenti prerequisiti di Azure/Microsoft 365, AWS e dell'ambiente locale siano soddisfatti.

Prerequisiti di Azure/Microsoft 365

Conferma l'accesso al tenant Microsoft Entra e installa i seguenti strumenti per creare identità, progetti e per registrare l'agente.

Prerequisiti di Amazon Web Services (AWS)

Assicurati che i seguenti servizi e strumenti AWS siano configurati per distribuire e gestire l'ambiente Elastic Beanstalk.

Prerequisiti dell'ambiente di sviluppo locale

Installa e configura in locale i seguenti strumenti per compilare, eseguire e distribuire l'agente.

Creare e distribuire un agente .NET

Le seguenti istruzioni descrivono come creare un agente minimo che:

  • Risponda a GET /
  • Accetti attività di Bot Framework su POST /api/messages

Creare la directory del progetto

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

Inizializzare il progetto .NET

Per semplificare la tua esperienza, in questo articolo si utilizza un esempio già preparato. Clona il repository Agent365 Samples e vai all'esempio dotnet\semantic-kernel\sample-agent.

L'esempio Kernel semantico Sample Agent - C#/.NET include:

  • Un'API Web ASP.NET Core minima
  • Gestore di messaggi Bot Framework su /api/messages
  • Endpoint di verifica delle condizioni in /
  • Integrazione del kernel semantico per le funzionalità di IA

Vai a dotnet\semantic-kernel\sample-agent e verifica che il progetto venga compilato correttamente:

dotnet restore
dotnet build

Configura il modello

Segui le istruzioni in Passaggio 2: configurazione di LLM per configurare il progetto usando la chiave API aperta.

Testa localmente (facoltativo)

  1. Prima di distribuire il progetto in AWS, testa l'agente localmente:

    # Run the application
dotnet run

  2. Testa gli endpoint in un altro terminale:

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

  3. Premi Ctrl+C per arrestare il server locale.

Crea e distribuisci

Scegli l'opzione che preferisci per compilare e distribuire l'applicazione di esempio:

Opzione A: compila e distribuisci da Visual Studio

Usa AWS Toolkit for Visual Studio per pubblicare l'app su Elastic Beanstalk usando una procedura guidata.

  1. In Esplora soluzioni fai clic con il pulsante destro del mouse sul progetto.

  2. Seleziona Pubblica su AWS Elastic Beanstalk.

  3. Segui le istruzioni indicata dalla Distribuzione guidata di Beanstalk:

    • Scegli il profilo delle credenziali AWS.
    • Seleziona la regione, ad esempio, us-east-1.
    • Seleziona la piattaforma (.NET Core on Linux).
    • Configura le impostazioni dell'ambiente.

  4. Seleziona Distribuisci.

La procedura guidata compila, crea il pacchetto dell'applicazione e lo distribuisce su AWS.

Opzione B: compila e distribuisci in AWS Elastic Beanstalk con l'interfaccia della riga di comando

Usa l'interfaccia a riga di comando di Elastic Beanstalk per creare il pacchetto dell'agente .NET e distribuirlo in un ambiente Amazon Linux 2 a 64 bit. Assicurati che le interfacce della riga di comando di AWS e di EB siano configurate. L'applicazione si associa alla variabile di ambiente PORT impostata da Beanstalk.

  1. Compila e pubblica l'applicazione .NET:

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

    Crea Procfile con il seguente contenuto.

    web: dotnet ./SemanticKernelSampleAgent.dll

  2. Inizializza Elastic Beanstalk per .NET. Ti viene chiesto di scegliere una Regione e una Piattaforma:

    eb init

  3. Selezionare:

    • Piattaforma: 64bit-amazon-linux-2023-v3.7.0-running-.net-8
    • Regione: la regione AWS che preferisci, ad esempio us-east-1

  4. Crea il pacchetto per la distribuzione e distribuiscilo:

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

    Questo comando:

    • Crea un'applicazione Elastic Beanstalk.
    • Crea un ambiente con un servizio di bilanciamento del carico.
    • Distribuisce l'applicazione.
    • Effettua il provisioning delle risorse AWS necessarie.

  5. Al termine, ottieni l'endpoint Elastic Beanstalk:

    eb status

    Prendi nota dell'endpoint. L'aspetto dell'anteprima dovrebbe essere simile al seguente:

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

    Questo endpoint è l'oggetto messagingEndpoint usato dall'interfaccia della riga di comando degli strumenti di sviluppo di Agent 365.

Nota

Per gli ambienti di produzione, configura il protocollo HTTPS aggiungendo un certificato SSL/TLS in Elastic Beanstalk. Il Bot Framework richiede l'uso di HTTPS per gli endpoint di produzione.

Configurare per l'hosting non Azure

Crea il file a365.config.json manualmente nella cartella del progetto Elastic Beanstalk:

Importante

Per l'hosting non Azure, imposta il valore sull'URL Elastic Beanstalk messagingEndpoint incluso il percorso /api/messages.

Il file a365.config.json deve essere simile al seguente:

{
  "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"
}

La tabella seguente riepiloga i campi di configurazione importanti e il loro scopo.

Campo Significato
messagingEndpoint URL di Elastic Beanstalk + /api/messages
deploymentProjectPath Dove avviene il contrassegno di .env

Creare l'agente Agent 365

Dopo che il codice dell'agente è stato eseguito su un endpoint AWS, segui i passaggi successivi della guida Introduzione allo sviluppo con Agent 365 per configurare l'agente Agent 365.

Verificare l'agente end-to-end

Usa questi controlli per verificare che l'agente ospitato da AWS sia raggiungibile, riceva attività del Bot Framework e risponda correttamente su tutte le superfici di Agent 365.

Verificare la connettività di Elastic Beanstalk

Invia una richiesta GET all'endpoint Elastic Beanstalk.

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

La richiesta dovrebbe restituire questo messaggio:

AWS Agent is running.

Controllare i log di Elastic Beanstalk per vedere se ci sono messaggi in arrivo del Bot Framework

Usa la funzionalità di registrazione di Elastic Beanstalk per verificare che l'agente riceva le attività di Bot Framework e risponda correttamente.

eb logs

In alternativa, monitora i log in tempo reale:

eb logs --stream

Dopo che un messaggio viene ricevuto dall'agente, vedi:

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

Agente di test da Agent 365

A seconda dell'ambiente, puoi testare l'agente da diverse interfacce:

  • Agents Playground
  • Teams (se pubblicato)
  • La shell dell'agente
  • Interfacce federate

Puoi inviare messaggi e verificare i log di Elastic Beanstalk. Scopri come testare gli agenti usando l'SDK di Microsoft Agent 365 e convalidando il funzionamento dell'agente con lo strumento di test del playground per gli agenti.

Flusso di lavoro dello sviluppatore

dopo aver completato la configurazione, segui questo flusso di lavoro per lo sviluppo iterativo:

Sviluppare e testare localmente

Usa la modalità di controllo per uno sviluppo rapido con ricaricamento automatico:

# Automatically rebuild and restart on file changes
dotnet watch run

Modifica il codice, salvalo e testalo localmente prima di distribuire.

Compilare e ridistribuire su AWS Elastic Beanstalk

Quando intendi distribuire le modifiche:

# 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

Testare e monitorare

Testa usando le interfacce di Agent 365 e monitora i log di Elastic Beansham:

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

Non è necessario ricreare la tua identità, il progetto, l'endpoint del bot o le autorizzazioni.

Risoluzione dei problemi

Usa questa sezione per diagnosticare e risolvere i problemi più comuni che si verificano durante la distribuzione e l'esecuzione di un agente di Agent 365 su AWS Elastic Beanstalk. Copre la connettività e i controlli di integrità. Affronta anche il binding di porta, gli errori di build e i problemi di licenza.

Suggerimento

Guida alla risoluzione dei problemi di Agent 365 contiene raccomandazioni di alto livello per la risoluzione dei problemi, procedure consigliate e collegamenti a contenuti di risoluzione dei problemi per ogni fase del ciclo di vita dello sviluppo di Agent 365.

L'endpoint di messaggistica non riceve richieste

Controlla i dettagli seguenti:

  • L'endpoint è esattamente:
    http://<your-app>.elasticbeanstalk.com/api/messages
  • L'ambiente Elastic Beanstalk è integro. Usa il controllo tramite eb health.
  • Il gruppo di sicurezza consente il traffico HTTP o HTTPS in entrata.
  • Non ci sono regole del firewall o restrizioni VPC.

Problemi di integrità dell'applicazione

Verifica l'integrità dell'ambiente:

eb health --refresh

Visualizza i log dettagliati:

eb logs

Problemi di binding delle porte

Assicurati che l'applicazione sia in ascolto sulla porta specificata dalla variabile di ambiente PORT. Elastic Beanstalk imposta questo valore automaticamente.

Problemi di build o di runtime di .NET

Controlla eventuali errori di compilazione usando questi comandi:

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

Verifica la versione di .NET:

dotnet --version
dotnet --list-sdks

Controlla eventuali problemi di pacchetto:

# List installed packages
dotnet list package

# Update packages
dotnet restore --force

Problemi di assegnazione della licenza

Assegna manualmente una licenza di Microsoft 365 valida oppure usa un percorso per utenti senza licenza, se supportato.

  • Last updated on