Sviluppa un agente 365 distribuito in Amazon Web Services (AWS)

Impara a costruire, ospitare, registrare e pubblicare un agente Agent 365 che giri su AWS Elastic Beanstalk, utilizzando la CLI di Agent 365. Microsoft Entra e Graph forniscono l'identità, le autorizzazioni e il progetto dell'agente, mentre AWS Elastic Beanstalk fornisce il runtime.

Se vuoi indirizzare il tuo agente al codice che risiede dietro un endpoint AWS, ti basta il seguente passaggio: configura per hosting non Azure. Poi, segui tutti gli altri passaggi del ciclo di vita di sviluppo dell'Agente 365.

Obiettivi

Informazioni su come usare Agent 365 e Microsoft 365 come piano di controllo e:

• Distribuire l'runtime dell'agente su AWS Elastic Beanstalk
• Configurare a365.config.json per l'hosting non-Azure
• Crea il Blueprint dell'agente in Entra ID
• Configura OAuth2 + permessi ereditabili
• Registra l'endpoint di messaggistica del Bot Framework con destinazione AWS
• Crea Identità dell'Agente + Utente dell'Agente
• (Facoltativo) Pubblicare nelle superfici dell'app Microsoft 365
• Testare le interazioni end-to-end

Prerequisiti

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

prerequisiti di Azure/Microsoft 365

Verificare l'accesso Microsoft Entra tenant e installare gli strumenti seguenti per creare identità, progetti e registrare l'agente.

• Un tenant Microsoft Entra con:

  • Permesso o ruolo per creare applicazioni e schemi di progetto per agenti (Amministratore Globale o equivalente)
  • Iscrizione al programma di anteprima Frontier per ottenere accesso anticipato a Microsoft Agent 365.
  • Almeno una licenza Microsoft 365 disponibile per l'utente di Agent

• Azure CLI installato e accesso effettuato.

• Agente 365 CLI installato

Prerequisiti Amazon Web Services (AWS)

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

• Account AWS con permessi appropriati
• L'accesso AWS Elastic Beanstalk attivato
• AWS CLI installata e configurata
• CLI di Elastic Beanstalk installato

Prerequisiti per lo sviluppo locale dell'ambiente

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

• Editor di codice: usare Visual Studio Code o Visual Studio

• .NET SDK: usare .NET 8.0 SDK o versione successiva

• AWS Toolkit: installare questa estensione da Visual Studio o Visual Studio Code. Accedi utilizzando le tue credenziali AWS Identity and Access Management (IAM ).

• Accesso API LLM: Scegli il servizio appropriato in base alla configurazione del tuo agente o al fornitore di modelli preferito:

  • Chiave API OpenAI: ottieni la chiave API OpenAI
  • Azure OpenAI: Creare e distribuire una risorsa OpenAI Azure per ottenere la chiave API e l'endpoint

Creare e distribuire un agente .NET

Le seguenti istruzioni descrivono come creare un agente minimale che:

• Risponde a GET /
• Accetta attività del Bot Framework su POST /api/messages

Crea la directory del progetto

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

Inizializzare .NET progetto

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

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

• Una API Web ASP.NET Core minimale
• Gestore di messaggi del Bot Framework su /api/messages
• Endpoint di verifica delle condizioni a /
• integrazione Semantic Kernel per le funzionalità di intelligenza artificiale

Vai su dotnet\semantic-kernel\sample-agent e verifica se il progetto si costruisce con successo:

dotnet restore
dotnet build

Configura il modello

Segui le istruzioni nel Passo 2: Configurazione LLM per configurare il progetto usando la tua chiave API aperta.

Testare localmente (opzionale)

1. Prima di schierare su AWS, testa il tuo agente localmente:

   # Run the application
   dotnet run
   

2. Testa gli endpoint in un altro terminal:

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

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

Compilare e distribuire

Scegli l'opzione che preferisci per costruire e distribuisci questa applicazione di esempio:

• Opzioni A: Compilare e distribuire da Visual Studio
• Opzione B: Compilare e distribuire su AWS Elastic Beanstalk con CLI

Opzione A: Compilare e distribuire da Visual Studio

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

1. In Solution Explorer fare clic con il pulsante destro del mouse sul progetto.

2. Seleziona Pubblica su AWS Elastic Beanstalk.

3. Segui il Wizard di Distribuzione Beanstalk:

   • Scegli il tuo profilo credenziali AWS.
   • Seleziona Regione (ad esempio, us-east-1).
   • Selezionare Piattaforma (.NET Core on Linux).
   • Configura le impostazioni dell'ambiente.

4. Seleziona Distribuisci.

La procedura guidata compila, impacchetta e distribuisce la tua applicazione su AWS.

Opzione B: Compilare e distribuire su AWS Elastic Beanstalk con CLI

Usare l'interfaccia della riga di comando di Elastic Beanstalk per creare un pacchetto e distribuire l'agente .NET in un ambiente Amazon Linux 2 a 64 bit. Assicurati che le CLI AWS ed EB siano configurate. L'app si collega alla PORT variabile ambiente impostata da Beanstalk.

1. Compilare e pubblicare l'applicazione .NET:

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

   Crea un Procfile con il seguente contenuto.

   web: dotnet ./SemanticKernelSampleAgent.dll
   

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

   eb init
   

3. Selezionare:

   • Piattaforma: 64bit-amazon-linux-2023-v3.7.0-running-.net-8
   • Regione: La tua regione AWS preferita (ad esempio: us-east-1)

4. Crea un pacchetto di distribuzione e distribuisci:

   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 bilanciatore di carico.
   • Distribuisce la tua applicazione.
   • Fornisce le risorse AWS necessarie.

5. Quando hai finito, ottieni il tuo endpoint Elastic Beanstalk.

   eb status
   

   Annota il tuo punto finale. Dovrebbe apparire simile a questo:

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

   Questo endpoint è utilizzato messagingEndpoint dalla CLI di Agent 365 Dev Tools.

Configurare per l'hosting non basato su Azure

Crea a365.config.json nella cartella del progetto Elastic Beanstalk eseguendo a365 config init:

Il a365.config.json file dovrebbe apparire più o meno come questo:

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

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

Build Agente 365

Dopo che il codice del tuo agente viene eseguito su un endpoint AWS, segui i passaggi rimanenti del ciclo di sviluppo dell'Agent 365 per configurare il tuo agente Agent 365.

Verifica l'agente end-to-end

Usa questi controlli per confermare che il tuo agente ospitato su AWS sia raggiungibile, riceva le attività del Bot Framework e risponda correttamente sulle superfici dell'Agent 365.

Verifica la connettività di Elastic Beanstalk

Invia una richiesta GET al tuo endpoint Elastic Beanstalk.

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

La richiesta dovrebbe restituire questo messaggio:

AWS Agent is running.

Controlla i log di Elastic Beanstalk per i messaggi in arrivo del Bot Framework

Usa il logging di Elastic Beanstalk per verificare che il tuo agente riceva le attività del Bot Framework e risponda correttamente.

eb logs

O trasmettere i log in tempo reale:

eb logs --stream

Dopo che un messaggio arriva al tuo agente, vedi:

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

Agente di prova di Agent 365 Surfaces

A seconda dell'ambiente, puoi testare il tuo agente da diverse superfici:

• Parco Giochi degli Agenti
• Squadre (se pubblicate)
• Agente Shell
• Superfici federate

Puoi inviare messaggi e verificare i log di Elastic Beanstalk. Impara a testare gli agenti usando l'SDK Microsoft Agent 365 e a convalidare le funzionalità del tuo agente con lo strumento di testing Agents Playground.

Flusso di lavoro degli sviluppatori

Una volta completata la configurazione, segui questo flusso di lavoro per lo sviluppo iterativo:

Sviluppare e testare localmente

Usa la modalità orologio per uno sviluppo rapido con ricarica automatica:

# Automatically rebuild and restart on file changes
dotnet watch run

Modifica il codice, salva e testa localmente prima di distribuire.

Compila e ridistribuisci su AWS Elastic Beanstalk

Quando sei pronto per implementare le tue 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

Testare utilizzando le superfici di Agent 365 e monitorare i log di Elastic Beanstalk.

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

Non è necessario ricreare la tua identità, il blueprint, l'endpoint del bot o i permessi.

Risoluzione dei problemi

Usa questa sezione per diagnosticare e risolvere problemi comuni durante il deployment e l'esecuzione di un agente Agent 365 su AWS Elastic Beanstalk. Copre la connettività e i controlli sanitari. Affronta anche il port binding, gli errori di compilazione e i problemi di licenza.

L'endpoint di messaggistica non riceve richieste

Controlla i seguenti dettagli:

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

Problemi di salute delle applicazioni

Controlla la salute ambientale:

eb health --refresh

Visualizza i registri dettagliati:

eb logs

Problemi di binding delle porte

Assicurati che la tua applicazione ascolti la porta specificata dalla PORT variabile di ambiente (Elastic Beanstalk imposta automaticamente questo valore).

.NET problemi di compilazione o di runtime

Controlla eventuali errori di compilazione usando questi comandi:

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

Verificare .NET versione:

dotnet --version
dotnet --list-sdks

Controlla eventuali problemi di pacchetto:

# List installed packages
dotnet list package

# Update packages
dotnet restore --force

Fallimento della cessione della licenza

Assegnare manualmente una licenza di Microsoft 365 valida o usare un percorso utente senza licenza, se supportato.