Crea un agente Agent 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à dell'agente, i permessi e il blueprint, mentre AWS Elastic Beanstalk fornisce l'esecuzione in tempo reale.

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

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

• Distribuire l'runtime dell'agente su AWS Elastic Beanstalk
• Configure a365.config.json for non-Azure hosting
• Crea Blueprint Agente in Entra ID
• Configura OAuth2 + permessi ereditabili
• Registra l'endpoint di messaggistica del Bot Framework puntando ad AWS
• Crea Identità Agente + Utente Agente
• (Opzionale) Pubblica su Microsoft 365 app surface
• Interazioni di test end-to-end

Prerequisiti

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

Azure / Microsoft 365 prerequisites

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

• Un tenant Microsoft Entra con:

  • Permesso o ruolo per creare applicazioni e blueprint di agente (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 dell'Agent

• Azure CLI installata e logata.

• 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
• Accesso AWS Elastic Beanstalk abilitato
• AWS CLI installata e configurata
• Installazione di CLI elastico di fagioli

Prerequisiti per lo sviluppo locale dell'ambiente

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

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

• .NET SDK: Usa .NET 8.0 SDK o successivo

• AWS Toolkit: installa 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: crea e distribuisci una risorsa Azure OpenAI per ottenere l'endpoint e la chiave API

Crea e distribuisci 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 directory progetto

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

Inizializza il progetto .NET

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.

Il campione Semantic Kernel Sample Agent - C#/.NET include:

• Una ASP.NET minima API Core Web
• Gestore di messaggi del Bot Framework su /api/messages
• endpoint di controllo della salute a/
• Integrazione del Kernel Semantico per le capacità dell'IA

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:

• Opzione 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

Usa AWS Toolkit per Visual Studio per pubblicare l'app su Elastic Beanstalk utilizzando un assistente guidato.

1. In Esplora soluzioni, clicca con il tasto destro sul tuo progetto.

2. Seleziona Pubblica su AWS Elastic Beanstalk.

3. Segui il Wizard per l'Installazione dei Fagioli:

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

4. Seleziona Distribuisci.

Il wizard compila, impacchetterebbe e distribuisce la tua applicazione su AWS.

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

Usa la CLI di Elastic Beanstalk per impacchettare e distribuire l'agente .NET su 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. Costruisci e pubblica la tua applicazione .NET:

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

   Crea un file con i seguenti contenuti.

   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 Beanstal.
   • 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 Beanstal:

   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.

Configure for non-Azure hosting

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 Agent 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à del fagiolo elastico

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 dalle superfici dell'Agente 365

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 dei tuoi fagioli elastici. 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 superfici Agent 365 e monitorare i log di Elastic Beansham:

# 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 del tuo fagiolo elastico è 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 con il binding delle porte

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

Problemi di compilazione o runtime di .NET

Controlla eventuali errori di compilazione usando questi comandi:

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

Verifica la versione .NET:

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

Assegna manualmente una licenza valida di Microsoft 365, oppure usa un percorso utente non autorizzato se supportato.