Bouw een Agent 365-agent die wordt geïmplementeerd in Amazon Web Services (AWS)

Ontdek hoe u een Agent 365-agent bouwt, host, registreert en publiceert, die wordt uitgevoerd op AWS Elastic Beanstalk, met behulp van de Agent 365 CLI. Microsoft Entra en Graph leveren de agentidentiteit, machtigingen en blueprint, terwijl AWS Elastic Beanstalk de runtime verzorgt.

Als u uw agent wilt wijzen op de code die zich achter een AWS-eindpunt bevindt, hebt u alleen de volgende stap nodig: Configureren voor niet-Azure-hosting. Volg vervolgens alle andere stappen van Aan de slag met de ontwikkeling van Agent 365.

Doelstellingen

Ontdek hoe u Agent 365 en Microsoft 365 als besturingsvlak gebruikt en:

  • Implementeer agentruntime op AWS Elastic Beanstalk
  • Configure a365.config.json voor niet-Azure-hosting
  • Maak Agent Blueprint aan in Entra ID
  • Configureer OAuth2 + erfelijke machtigingen
  • Registreer Bot Framework-berichteneindpunt dat verwijst naar AWS
  • Maak Agentidentiteit + Agentgebruiker
  • (Optioneel) Publiceren op Microsoft 365 app-locaties
  • Test interacties end-to-end

Vereisten

Controleer of er aan de volgende vereisten voor Azure/Microsoft 365, AWS en lokale omgevingen wordt voldaan.

Azure/vereisten van Microsoft 365

Bevestig uw Microsoft Entra-tenanttoegang en installeer de volgende tools om identiteiten en blueprints te maken en uw agent te registreren.

Vereisten voor Amazon Web Services (AWS)

Controleer of de volgende AWS-services en -tools zijn ingesteld om uw Elastic Beanstalk-omgeving te implementeren en te beheren.

Vereisten voor lokale ontwikkelingsomgevingen

Installeer en configureer lokaal de volgende tools om de agent te bouwen, uit te voeren en te implementeren.

Een .NET-agent maken en implementeren

De volgende instructies beschrijven hoe u een minimale agent kunt creëren die:

  • Reageert op GET /
  • Accepteert Bot Framework-activiteiten op POST /api/messages

Projectmap aanmaken

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

.NET-project initialiseren

Om uw ervaring te stroomlijnen, toont dit artikel een voorbeeld dat al is voorbereid. Kloon de Agent365 Samples-opslagplaats en ga naar de sample dotnet\semantic-kernel\sample-agent.

De Semantic Kernel Sample Agent - C#/.NET-sample bevat:

  • Een minimale ASP.NET Core Web API
  • Bot Framework berichtenhandler op /api/messages
  • Statuscontrole-eindpunt op /
  • Semantic Kernel-integratie voor AI-mogelijkheden

Ga naar dotnet\semantic-kernel\sample-agent en verifieer of het project succesvol is gemaakt:

dotnet restore
dotnet build

Model configureren

Volg de instructies in Stap 2: LLM-configuratie om het project te configureren met uw Open API-sleutel.

Test lokaal (optioneel)

  1. Test uw agent lokaal voordat u in AWS implementeert:

    # Run the application
dotnet run

  2. Test de eindpunten in een andere terminal:

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

  3. Druk op Ctrl+C om de lokale server te stoppen.

Bouwen en implementeren

Kies de optie die u het liefst wilt maken en implementeer deze sample-toepassing:

Optie A: maak en implementeer vanuit Visual Studio

Gebruik de AWS Toolkit voor Visual Studio om de app te publiceren op Elastic Beanstalk met behulp van een begeleide wizard.

  1. Klik in Solution Explorer met de rechtermuisknop op uw project.

  2. Selecteer Publiceren op AWS Elastic Beanstalk.

  3. Volg de Beanstalk-implementatiewizard:

    • Kies uw AWS-inloggegevensprofiel.
    • Selecteer Regio (bijvoorbeeld us-east-1).
    • Selecteer Platform (.NET Core on Linux).
    • Configureer omgevingsinstellingen.

  4. Selecteer Implementeren.

De wizard maakt, verpakt en implementeert uw toepassing in AWS.

Optie B: maak en implementeer in AWS Elastic Beanstalk met CLI

Gebruik de Elastic Beanstalk CLI om de .NET-agent te verpakken en implementeren in een 64-bits Amazon Linux 2-omgeving. Controleer of AWS CLI en EB CLI zijn geconfigureerd. De app bindt aan de omgevingsvariabele PORT die door Beanstalk is ingesteld.

  1. Maak en publiceer uw .NET-toepassing:

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

    Maak een Proc-bestand aan met de volgende content:

    web: dotnet ./SemanticKernelSampleAgent.dll

  2. Initialiseer Elastic Beanstalk voor .NET. U wordt gevraagd om Regio en Platform te kiezen:

    eb init

  3. Selecteer:

    • Platform: 64bit-amazon-linux-2023-v3.7.0-running-.net-8
    • Regio: uw voorkeur AWS-regio (bijvoorbeeld: us-east-1)

  4. Maak een implementatiepakket en implementeer:

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

    Deze opdracht:

    • Maakt een Elastic Beanstalk-toepassing.
    • Maakt een omgeving met een load balancer.
    • Zet uw toepassing uit.
    • Voorziet in noodzakelijke AWS-bronnen.

  5. Als u klaar bent, haalt u uw Elastic Beanstalk-eindpunt op:

    eb status

    Noteer uw eindpunt. Het ziet er ongeveer als volgt uit:

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

    Dit eindpunt wordt messagingEndpoint dat wordt gebruikt door de Agent 365 Dev Tools CLI.

Notitie

Voor productieomgevingen configureert u HTTPS, door een SSL/TLS-certificaat toe te voegen in Elastic Beanstalk. Het Bot Framework vereist HTTPS voor productie-eindpunten.

Configure voor niet-Azure-hosting

Maak a365.config.json handmatig aan in uw Elastic Beanstalk-projectmap:

Belangrijk

Voor niet-Azure-hosting stelt u de waarde messagingEndpoint in op uw Elastic Beanstalk-URL met het pad /api/messages.

Het bestand a365.config.json zou er ongeveer als volgt uit moeten zien:

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

De volgende tabel vat belangrijke configuratievelden en hun doel samen.

Veld Betekenis
messagingEndpoint Uw Elastic Beanstalk-URL + /api/messages
deploymentProjectPath Waar .env-stempelen plaatsvindt

Agent 365 agent maken

Nadat uw agentcode is uitgevoerd op een AWS-endpoint, volgt u de resterende stappen van Aan de slag met Agent 365-ontwikkeling om uw Agent 365-agent in te stellen.

Controleer de agent end-to-end

Gebruik deze controles om te bevestigen dat uw op AWS gehoste agent bereikbaar is, Bot Framework-activiteiten ontvangt en correct reageert op alle Agent 365-locaties.

Verifieer de connectiviteit van Elastic Beanstalk

Stuur een GET-verzoek naar uw Elastic Beanstalk-eindpunt.

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

Het verzoek zou dit bericht moeten teruggeven:

AWS Agent is running.

Controleer de logboeken van Elastic Beanstalk op binnenkomende berichten van Bot Framework

Gebruik Elastic Beanstalk-logboekregistratie om te verifiëren dat uw agent Bot Framework-activiteiten ontvangt en correct reageert.

eb logs

Of stream logboeken in realtime:

eb logs --stream

Nadat een bericht uw agent bereikt, ziet u:

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

Test de agent vanaf Agent 365-locaties

Afhankelijk van uw omgeving kunt u uw agent op verschillende locaties testen:

  • Agenten van testomgeving
  • Teams (indien gepubliceerd)
  • Agent Shell
  • Gefedereerde locaties

U kunt berichten sturen en uw Elastic Beanstalk-logboeken verifiëren. Ontdek hoe u agenten test met de SDK voor Microsoft 365-agenten en valideer de functionaliteit van uw agent met de Agents Playground-testtool.

Ontwikkelaarswerkstroom

Zodra de installatie voltooid is, volgt u deze werkstroom voor iteratieve ontwikkeling:

Ontwikkel en test lokaal

Gebruik de watch-modus voor een snelle ontwikkeling met automatisch herladen:

# Automatically rebuild and restart on file changes
dotnet watch run

Wijzig uw code, sla op en test lokaal voordat u deze implementeert.

Maak en implementeer opnieuw in AWS Elastic Beanstalk

Wanneer u klaar bent om uw wijzigingen te implementeren:

# 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

Testen en monitoren

Test met Agent 365-locaties en monitor de Elastic Beanstalk-logboeken:

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

U hoeft uw identiteit, blueprint, bot-eindpunt of machtigingen niet opnieuw aan te maken.

Probleemoplossing

Gebruik deze sectie om veelvoorkomende problemen te diagnosticeren en op te lossen bij het implementeren en uitvoeren van een Agent 365-agent op AWS Elastic Beanstalk. Het dekt connectiviteit en statuscontroles. Het behandelt ook poortbinding, maakfouten en licentieproblemen.

Fooi

De Gids voor probleemoplossing in Agent 365 bevat aanbevelingen voor probleemoplossing op hoog niveau, best practices en links naar relevante probleemoplossingsinformatie voor elk onderdeel van de Agent 365-ontwikkelingscyclus.

Het berichteneindpunt ontvangt geen verzoeken

Controleer de volgende gegevens:

  • Uw eindpunt is precies:
    http://<your-app>.elasticbeanstalk.com/api/messages
  • Uw omgeving bij Elastic Beanstalk is in orde. Gebruik de controle door eb health te gebruiken.
  • Uw beveiligingsgroep staat inkomend HTTP- of HTTPS-verkeer toe.
  • Er zijn geen firewallregels of VPC-beperkingen.

Problemen met toepassingstatus

Controleer de omgevingsstatus:

eb health --refresh

Weergave van gedetailleerde logbestanden:

eb logs

Poortbindingsproblemen

Controleer of uw toepassing luistert op de poort die door de omgevingsvariabele PORT wordt gespecificeerd. Elastic Beanstalk stelt deze waarde automatisch in.

Creatie- of runtimeproblemen in .NET

Controleer op maakfouten met behulp van deze opdrachten:

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

Verifieer de .NET-versie:

dotnet --version
dotnet --list-sdks

Controleer op pakketproblemen:

# List installed packages
dotnet list package

# Update packages
dotnet restore --force

Licentietoewijzing mislukt

Wijs handmatig een geldige Microsoft 365-licentie toe, of gebruik een niet-gelicentieerd gebruikerspad als dat ondersteund wordt.

  • Last updated on