Condividi tramite

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

Importante

Devi far parte del programma di anteprima Frontier per ottenere l'accesso in anteprima a Microsoft Agent 365. Frontier ti mette in contatto diretto con le ultime innovazioni di Microsoft nell'IA. Le anteprime Frontier sono soggette alle condizioni di anteprima esistenti dei tuoi contratti del cliente. Poiché queste funzionalità sono ancora in fase di sviluppo, la disponibilità e le funzionalità possono cambiare nel tempo.

Qui puoi imparare a costruire, ospitare, registrare e pubblicare un agente Agent 365 che gira su AWS Elastic Beanstalk, utilizzando la CLI di Agent 365. Microsoft Entra & Graph fornisce l'identità dell'agente, i permessi e il blueprint, mentre AWS Elastic Beanstalk fornisce il runtime.

Se tutto ciò che vuoi fare è indirizzare il tuo agente al codice che si trova dietro un endpoint AWS, ti serve solo questo passaggio: configura per l'hosting non Azure e poi segui tutti gli altri passaggi del ciclo di sviluppo dell'Agent 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.

Prerequisiti Amazon Web Services (AWS)

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

Prerequisiti per lo sviluppo locale dell'ambiente

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

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, utilizziamo un campione già preparato. Clona il repository Agent365 Samples e naviga fino al campione dotnet\semantic-kernel\sample-agent .

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

Naviga e dotnet\semantic-kernel\sample-agent verifica che il progetto si sviluppi 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 Open API.

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

Usa AWS Toolkit per Visual Studio per pubblicare l'app su Elastic Beanstalk con un wizard 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 la regione (ad esempio, us-east-1)
    • Seleziona Piattaforma (.NET Core on Linux)
    • Configura le impostazioni dell'ambiente

  4. Seleziona Distribuire

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 la CLI AWS/EB sia configurata e che l'app si associ alla PORT variabile di 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 procfile con i contenuti qui sotto

    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

    In questo modo:

    • Crea un'applicazione Elastic Beanstalk
    • Crea un ambiente con un bilanciatore di carico
    • Distribuire la tua applicazione
    • Fornire 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

    Questa è la messagingEndpoint CLI di Agent 365 Dev Tools.

Annotazioni

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

Configure for non-Azure hosting

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

Importante

Per hosting non Azure, devi:

  • Imposta messagingEndpoint sull'URL del tuo Elastic Beanstalk (con /api/messages percorso)
  • Impostare needDeployment su false

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.

Campo Meaning
messagingEndpoint Il tuo URL di Elastic Beanstalk + /api/messages
"needDeployment": false Dice a CLI: 'Ospito un mio server; non distribuire su Azure'
deploymentProjectPath Dove .env avviene la stampa

Build Agent 365

Una volta che il codice dell'agente è in esecuzione su un endpoint AWS, segui i passaggi rimanenti del ciclo di sviluppo di 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, vedrai:

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

Agente di prova dalle superfici dell'Agente 365

A seconda del tuo ambiente:

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

Ora puoi inviare messaggi e verificare i tuoi log di Elastic Beanstal. Impara a testare gli agenti usando l'SDK Microsoft Agent 365 e a validare la 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 tramite superfici Agent 365 e monitorare i log di Elastic Beansham:

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

La tua identità, il blueprint, l'endpoint del bot e i permessi NON devono essere ricreati.

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.

Endpoint di messaggistica che 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 con eb health
  • Il tuo gruppo di sicurezza consente il traffico HTTP/HTTPS in entrata
  • Non ci sono regole firewall o restrizioni VPC

Problemi di salute dell'applicazione

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 questo automaticamente).

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 con il pacchetto:

# List installed packages
dotnet list package

# Update packages
dotnet restore --force

Fallimento della cessione della licenza

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

Ottenere assistenza

Più opzioni di aiuto

Considera quanto segue per trovare aiuto:

  • Last updated on