Rakenna Agent 365 -agentti, joka on otettu käyttöön Amazon Web Servicesissä (AWS)

Opi rakentamaan, isännöimään, rekisteröimään ja julkaisemaan Agent 365 -agentti, joka toimii AWS Elastic Beanstalk -ympäristössä, käyttäen Agent 365 CLI:n avulla. Microsoft Entra ja Graph tarjoavat agentin identiteetin, käyttöoikeudet ja blueprintin, kun taas AWS Elastic Beanstalk tarjoaa ajonaikaisen ympäristön.

Jos haluat suunnata agenttisi koodiisi, joka sijaitsee AWS-päätepisteen takana, tarvitset vain seuraavan vaiheen: Konfiguroi muulle kuin Azure-isännöinnille. Seuraa sitten kaikkia muita vaiheita kohdasta Agent 365 -kehityksen aloitus.

Tavoitteet

Opi käyttämään Agent 365:tä ja Microsoft 365:ttä hallintatasona ja:

• Ota käyttöön agentin suorituksenaikainen ympäristö AWS Elastic Beanstalkissa
• Määritä a365.config.json muulle kuin Azure-isännöinnille
• Luo agentin blueprint Entra ID -tunnus:ssä
• Määritä OAuth2 + periytyvät käyttöoikeudet
• Rekisteröi Bot Frameworkin viestintäpäätepiste, joka on osoitettu AWS:hen
• Luo agentin identiteetti + agentin käyttäjä
• (Valinnainen) Julkaise Microsoft 365 -sovelluspintoihin
• Testaa vuorovaikutukset kaikenkattavasti

Edellytykset

Ennen kuin aloitat, varmista, että seuraavat Azure-, Microsoft 365-, AWS- ja paikallisympäristövaatimukset täyttyvät.

Azuren/Microsoft 365:n edellytykset

Varmista, että sinulla on pääsy Microsoft Entra -vuokraajaan ja asenna seuraavat työkalut identiteettien, blueprintien luomista sekä agentin rekisteröintiä varten.

• Microsoft Entra -vuokraaja, jolla on:

  • Käyttöoikeus tai rooli sovellusten ja agentti-blueprintien luomiseen (Global Administrator tai muu vastaava rooli)
  • Jäsenyys Frontier-esiversio-ohjelmaan saadaksesi varhaisen pääsyn Microsoft Agent 365:een.
  • Agentti-käyttäjälle on oltava vähintään yksi Microsoft 365 -lisenssi saatavilla

• Azure CLI asennettuna ja sisäänkirjautuneena.

• Agent 365 CLI asennettuna

Amazon Web Services (AWS):n vaatimukset

Varmista, että seuraavat AWS-palvelut ja työkalut ovat käytössä käyttöönottoa ja hallintaa varten Elastic Beanstalk -ympäristössäsi.

• AWS-tili asianmukaisilla käyttöoikeuksilla
• AWS Elastic Beanstalkin käyttöoikeus käytössä
• AWS CLI asennettu ja määritetty
• Elastic Beanstalk CLI asennettu

Paikallisen kehitysympäristön vaatimukset

Asenna ja määritä seuraavat työkalut paikallisesti agentin rakentamista, suorittamista ja käyttöönottoa varten.

• Editori: Käytä Visual Studio Codea tai Visual Studiota

• .NET SDK: Käytä .NET 8.0 SDK:ta tai uudempaa

• AWS Toolkit: Asenna tämä laajennus Visual Studiosta tai Visual Studio Codesta. Kirjaudu sisään käyttämällä AWS Identity and Access Management (IAM) -valtuustietojasi.

• LLM API -yhteys: Valitse sopiva palvelu agentin määritysten tai haluamasi mallitoimittajan mukaan.

  • OpenAI API-avain: Hanki OpenAI API-avain
  • Azure OpenAI: Luo ja ota käyttöön Azure OpenAI-resurssi saadaksesi API-avaimen ja päätepisteen

.NET-agentin luominen ja käyttöönotto

Seuraavat ohjeet kuvaavat, miten luodaan minimaalinen agentti, joka:

• Vastaa GET:iin /
• Hyväksyy Bot Framework -aktiviteetit POST-pyynnössä /api/messages

Luo projektihakemiston

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

Alustaa .NET-projektin

Kokemuksesi sujuvoittamiseksi tässä artikkelissa käytetään jo valmiiksi valmistettua esimerkkiä. Kloonaa Agent365 Samples -arkisto ja siirry dotnet\semantic-kernel\sample-agent-otokseen.

Semantic Kernel Sample agentti - C#/.NET -otos sisältää:

• Yksinkertainen ASP.NET Core Web API
• Bot Framework -viestinkäsittelijä osoitteessa /api/messages
• Terveystarkistuksen päätepiste osoitteessa /
• Semantic Kernel -integraatio tekoälyominaisuuksiin

Siirry kohtaan dotnet\semantic-kernel\sample-agent ja varmista, että projekti rakentuu onnistuneesti:

dotnet restore
dotnet build

Konfiguroi malli

Seuraa ohjeita kohdassa Vaihe 2: LLM:n konfigurointi ja konfiguroi projekti käyttämällä OpenAPI-avainta.

Testaa paikallisesti (tarvittaessa)

1. Ennen AWS:ään käyttöönottoa, testaa agenttisi paikallisesti:

   # Run the application
   dotnet run
   

2. Testaa päätepisteet toisessa terminaalissa:

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

3. Paina Ctrl+C pysäyttääksesi paikallisen palvelimen.

Koonti ja käyttöönotto

Valitse vaihtoehto, jolla haluat rakentaa ja ottaa tämän esimerkkisovelluksen käyttöön:

• Vaihtoehto A: Rakenna ja ota käyttöön Visual Studiosta
• Vaihtoehto B: Rakenna ja ota käyttöön AWS Elastic Beanstalk CLI:n avulla

Vaihtoehto A: Rakenna ja ota käyttöön Visual Studiosta

Käytä AWS Toolkit for Visual Studiota julkaistaksesi sovelluksen Elastic Beanstalkiin ohjatun toiminnon avulla.

1. ratkaisunhallintaissa, napsauta projektia hiiren oikealla painikkeella.

2. Valitse Publish to AWS Elastic Beanstalk.

3. Seuraa Beanstalk Deployment Wizard:

   • Valitse AWS-profiili.
   • Valitse alue (esimerkiksi us-east-1).
   • Valitse alusta (.NET Core on Linux).
   • Ympäristön asetusten määrittäminen.

4. Valitse Ota käyttöön.

Ohjain rakentaa, paketoi ja ottaa käyttöön sovelluksesi AWS:lle.

Vaihtoehto B: Rakenna ja ota käyttöön AWS Elastic Beanstalk CLI:n avulla

Käytä Elastic Beanstalk CLI:tä .NET-agentin pakkaamiseen ja käyttöönottoon 64-bittisessä Amazon Linux 2 -ympäristössä. Varmista, että AWS CLI ja EB CLI ovat konfiguroituja. Sovellus käyttää Beanstalkin asettamaa PORT-ympäristömuuttujaa.

1. Rakenna ja julkaise .NET-sovelluksesi:

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

   Luo profiili, jonka sisältö on seuraava.

   web: dotnet ./SemanticKernelSampleAgent.dll
   

2. Alusta Elastic Beanstalk .NET-sovellukselle. Sinua pyydetään valitsemaan alue ja ympäristö:

   eb init
   

3. Valitse:

   • Ympäristö: 64bit-amazon-linux-2023-v3.7.0-running-.net-8
   • Alue: Suosimasi AWS-alue (esimerkiksi: us-east-1)

4. Luo käyttöönottopaketti ja ota käyttöön:

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

   Tämä komento:

   • Luo Elastic Beanstalk -sovelluksen.
   • Luo ympäristön, jossa on kuormantasapainotin.
   • Ottaa sovelluksesi käyttöön.
   • Ottaa käyttöön tarvittavat AWS-resurssit.

5. Kun olet valmis, ota selvää Elastic Beanstalk -päätepisteestäsi:

   eb status
   

   Kirjaa päätepisteesi ylös. Sen pitäisi näyttää suunnilleen tällaiselta:

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

   Tätä päätepistettä messagingEndpoint käyttää Agent 365 Dev Tools CLI.

Konfigurointi muuta kuin Azure-isännöintiä varten

Luo a365.config.json manuaalisesti Elastic Beanstalk -projektikansioon:

a365.config.json-tiedostosi pitäisi näyttää suunnilleen tämänkaltaiselta:

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

Seuraava taulukko tiivistää tärkeät määrityskentät ja niiden tarkoituksen.

Rakenna Agent 365 -agentti

Kun agenttikoodisi on suoritettu AWS-päätepisteessä, seuraa loput vaiheet kohdasta Agent 365 -kehityksen aloitus Agent 365 agentin käyttöönottoon.

Tarkasta agentti perusteellisesti

Käytä näitä tarkistuksia varmistaaksesi, että AWS:ssä isännöity agentti on tavoitettavissa, vastaanottaa Bot Framework -aktiviteetteja ja vastaa oikein Agent 365 -alustoilla.

Varmista Elastic Beanstalkin yhteys

Lähetä GET-pyyntö Elastic Beanstalkin päätepisteellesi.

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

Pyynnön tulisi palauttaa tämä viesti:

AWS Agent is running.

Tarkista Elastic Beanstalkin lokit saapuvien Bot Framework -viestien osalta

Käytä Elastic Beanstalk -lokiin kirjaamista varmistaaksesi, että agenttisi vastaanottaa Bot Frameworkin toiminnot ja reagoi oikein.

eb logs

Tai voit seurata lokitietoja reaaliajassa:

eb logs --stream

Kun viesti saapuu agentillesi, näet:

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

Agent 365 -pinnoilta peräisin oleva testiagentti

Ympäristöstäsi riippuen voit testata agenttiasi eri alustoilla:

• Agenttien testausalusta
• Teams (jos julkaistu)
• Agenttien komentoliittymä
• Organisaation ulkopuoliset alustat

Voit lähettää viestejä ja tarkistaa Elastic Beanstalk -lokejasi. Opi testaamaan agentteja Microsoft Agent 365 SDK:n avulla ja tarkistamaan agentin toiminnallisuus Agents Playground -testaustyökalulla.

Kehittäjän työnkulku

Kun asennus on valmis, seuraa tätä työnkulkua iteratiivisessa kehityksessä:

Kehitä ja testaa paikallisesti

Käytä tarkastelutilaa nopeaan kehitykseen ja automaattiseen uudelleenlataukseen:

# Automatically rebuild and restart on file changes
dotnet watch run

Tee koodimuutokset, tallenna ja testaa paikallisesti ennen käyttöönottoa.

Rakenna ja ota uudelleen käyttöön AWS Elastic Beanstalkiin

Kun olet valmis ottamaan muutokset käyttöön:

# 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

Testaa ja valvo

Testaa käyttämällä Agent 365 -käyttöliittymiä ja seuraa Elastic Beanstalk -lokeja:

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

Sinun ei tarvitse luoda uudelleen identiteettiä, blueprintia, botin päätepistettä tai käyttöoikeuksia.

Vianmääritys

Käytä tätä osiota diagnosointiin ja ratkaisuun yleisille ongelmille Agent 365 -agentin käyttöönotossa ja toiminnassa AWS Elastic Beanstalkilla. Se kattaa yhteydet ja terveystarkastukset. Se käsittelee myös porttisidontaa, rakennusvirheitä ja lisensointiongelmia.

Viestipäätepiste ei vastaanota pyyntöjä

Tarkista seuraavat tiedot:

• Päätepisteesi on täsmälleen:
  http://<your-app>.elasticbeanstalk.com/api/messages
• Elastic Beanstalk -ympäristösi on terve. Tee tarkistus käyttämällä eb health.
• Suojausryhmäsi sallii saapuvan HTTP- tai HTTPS-liikenteen.
• Ei ole palomuurisääntöjä eikä VPC-rajoituksia.

Sovelluksen terveysongelmat

Tarkista ympäristön terveys:

eb health --refresh

Näytä yksityiskohtaiset lokit:

eb logs

Portin sidontaongelmat

Varmista, että sovelluksesi kuuntelee porttia, jonka määrittää ympäristömuuttuja PORT. Elastic Beanstalk asettaa tämän arvon automaattisesti.

.NET-rakennus- tai suorituksenaikaiset ongelmat

Tarkista rakennusvirheet käyttämällä näitä komentoja:

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

Varmista .NET-versio:

dotnet --version
dotnet --list-sdks

Tarkista pakettiongelmat:

# List installed packages
dotnet list package

# Update packages
dotnet restore --force

Käyttöoikeuden määritys epäonnistuu

Määritä manuaalisesti voimassa oleva Microsoft 365 -lisenssi tai käytä lisensoimatonta käyttäjäpolkua, jos se on tuettu.