Azure Bot Framework SDK:n siirtymisohjeet Microsoft 365 -agenttien SDK:hen Node.js:lle

Tässä artikkelissa kuvataan tarvittavat muutokset siirtymiseksi Bot Framework SDK:sta Node.jsvarten.

Vaatimukset

  • Node.js versio 20 tai uudempi
  • Aiemmin luotu Bot Framework SDK -projekti
  • Azure Bot Service -resurssi (pysyy samana siirron aikana)

NodeJS SDK -koodin muutokset

Tämän osion muutokset johtuvat Azure Bot Framework SDK :n ja Microsoft 365 -agenttien SDK JavaScriptin välisistä eroista.

Azure-resurssit

Azure-resurssisi pysyvät muuttumattomina. Sinun on viitattava appsettings-ominaisuuksiin kohteille MicrosoftAppType, MicrosoftAppId, MicrosoftAppPasswordja MicrosoftAppTenantId. Näitä asetusten nimiä ei kuitenkaan enää käytetä, ja ne voidaan poistaa myöhemmin. Lue lisätietoja ympäristön määrityksestä

Ensimmäiset vaiheet

Ota seuraavat muutokset käyttöön ensin, jotta voit ottaa useimmat erot huomioon. Sinun täytyy silti korjata virheenkorjaus ja tarkistaa muut erot, kun olet ensin ottaa nämä muutokset käyttöön.

Pakettien riippuvuuksien päivittäminen

Tämä muutos ei saat kaikkia vaadittuja nimitiloja selvitetyiksi, mutta se kattaa suurimman osan niistä.

Skenaario Bot Framework SDK Agentit SDK
Ydinisännöinti botbuilder @microsoft/agents-hosting
Toimintorakenne botframework-schema @microsoft/agents-activity
Valintaikkunat botbuilder-dialogs @microsoft/agents-hosting-dialogs
Azure Cosmos DB botbuilder-azure @microsoft/agents-hosting-storage-cosmos
Azure Blob -säilö botbuilder-azure-blobs @microsoft/agents-hosting-storage-blob
Pikapalvelinapuohjelmat Manuaalinen määritys @microsoft/agents-hosting-express

Botit käyttäen Teamsia

Jos bottisi käyttää Teamsia, lisää pakettiriippuvuus @microsoft/agents-hosting-extensions-teams

Päivitä tuonnit/edellytä

Tee seuraavat muutokset Etsi ja korvaa -kohteella:

Bot Framework Agentit SDK
require('botframework-schema'); require('@microsoft/agents-activity')
require('botbuilder'); require('@microsoft/agents-hosting')
require('botbuilder-dialogs'); require('@microsoft/agents-hosting-dialogs')

Agenttien SDK-toimintaluokka

Paketti @microsoft/agents-activity sisältää Activity-luokan , joka suorittaa jäsennystä zod-kohteen perusteella. Voit jäsentää ja vahvistaa mukautettuja toimintoja JSON:stä literaalin JavaScript-objektien kanssa Activity.fromJson() tai literaalista käyttäen Activity.fromObject().

Lisäksi Activity luokka keskittää kaikki toimintokuormaan liittyvät toiminnot, kuten getConversationReference. Seuraavan taulukon menetelmät ovat siirtyneet nykyisestä TurnContext toimintoesiintymästä ja toimivat nyt nykyisessä toimintoesiintymässä:

Bot Frameworkin staattinen menetelmä Agenttien SDK-esiintymämenetelmä
TurnContext.applyConversationReference activity.applyConversationReference
TurnContext.getConversationReference activity.getConversationReference
TurnContext.getReplyConversationReference activity.getReplyConversationReference
TurnContext.removeRecipientMention activity.removeRecipientMention
TurnContext.getMentions activity.getMentions
TurnContext.removeMentionText activity.removeMentionText

Käynnistys ja määritys

Agents SDK -määritysjärjestelmä korvaa luokan - ConfigurationBotFrameworkAuthentication liittymällä AuthConfiguration .

Jos haluat ladata määrityksen oletustiedostosta.env, käytä .loadAuthConfigFromEnv

Tärkeää

Määritysmuuttujat on kuvattu artikkelissa Todentamisen määrittäminen JavaScriptissä.

Ympäristön määritys

Luo tiedosto, jossa .env on seuraavat muuttujat:

# Required for Azure Bot Service
clientId=your-app-id
clientSecret=your-app-secret  
tenantId=your-tenant-id

# Optional - for local debugging
PORT=3978
DEBUG=true

Siirron huomautus: päivitä ympäristömuuttujien nimet seuraavassa taulukossa esitetyllä tavalla:

Bot Framework SDK Agentit SDK
MicrosoftAppId clientId
MicrosoftAppPassword clientSecret
MicrosoftAppTenantId tenantId

Todennus ja suojaus

Kun Bot Framework SDK valtuuttaa saapuvat pyynnöt, se sisältää pinoon JSON-verkkotunnuksen (JWT). Agentit, joita SDK ei tee. Kun käytät verkkopalvelimen suorituspalvelua, kuten pikasovellusta, sinun täytyy määrittää JWT-väliohjelmisto, jotta saapuva pyyntö voidaan sallia JWT-haltijatunnuksen perusteella, Agents SDK tarjoaa -menetelmän authorizeJWT(AuthConfiguration) .

JWT Middleware (pakollinen tuotantoon):

import { authorizeJWT, loadAuthConfigFromEnv } from '@microsoft/agents-hosting'

const authConfig = loadAuthConfigFromEnv()
server.use(authorizeJWT(authConfig))

Paikallinen kehitys:

Paikallista virheenkorjausta varten JWT-tarkistus voidaan poistaa käytöstä:

// Only for local development - NEVER in production
if (process.env.NODE_ENV === 'development') {
    // JWT validation disabled for local testing
} else {
    server.use(authorizeJWT(authConfig))
}

Palvelimen asetukset

Agents SDK tarjoaa kaksi tapaa palvelimen määrittämiseen:

StartServer-menetelmän käyttäminen

Käytä tätä yksinkertaistettua lähestymistapaa uusissa projekteissa, kun haluat vähimmäismäärityksen etkä tarvitse mukautettua väliohjelmistoa.

Päivitä alustuskoodisi kohteesta botbuilder:

const { EchoBot } = require('./bot');
const {
    CloudAdapter,
    ConfigurationBotFrameworkAuthentication
} = require('botbuilder');
const botFrameworkAuthentication = new ConfigurationBotFrameworkAuthentication(process.env);
const adapter = new CloudAdapter(botFrameworkAuthentication);
const myBot = new EchoBot();
const server = express();
server.use(express.json());
server.post('/api/messages', async (req, res) => 
    await adapter.process(req, res, (context) => 
      myBot.run(context));
);

Agenteille, joilla on isännöinti startServer():

const { EchoBot } = require('./bot');
const { startServer } = require('@microsoft/agents-hosting-express')
startServer(new EchoBot());

Manuaalinen pika-asennus

Käytä tätä menetelmää siirtyessäsi olemassa olevia botteja, tarvitset mukautetun välitason ohjelmiston, haluat täydet express-määritykset hallintaa varten

const { EchoBot } = require('./bot');
const {
    CloudAdapter,
    loadAuthConfigFromEnv, // Update
    authorizeJWT // Update
} = require('@microsoft/agents-hosting'); // Update
const authConfig = loadAuthConfigFromEnv(); // Update
const adapter = new CloudAdapter(authConfig); // Update
const myBot = new EchoBot();
const server = express();
server.use(express.json());
server.use(authorizeJWT(authConfig)); // Update
server.post('/api/messages', async (req, res) => 
    await adapter.process(req, res, (context) => 
      myBot.run(context));
);

const port = process.env.PORT || 3978;
server.listen(port, () => {
    console.log(`Server listening on port ${port}`);
}).on('error', (err) => {
    console.error('Server failed to start:', err);
    process.exit(1);
});

ActivityHandler-tuki

Useimmat Bot Framework SDK:n avulla luodut botit perustuvat botbuilder-core.ActivityHandler perusluokkaan.

Agents SDK tarjoaa yhteensopivan agents-hosting.ActivityHandler , joka ylläpitää samaa ohjelmointirajapintaa helpottaakseen siirtoa.

Tärkeimmät erot

Bot Framework SDK:n ja Agents SDK:n välisiä merkittäviä eroja ovat muun muassa seuraavat:

Käsittelijän parametrit:

SDK Käsittelijän tyyppi
Bot Framework SDK BotHandler
Agentit SDK AgentHandler

Lisämenetelmät agenttien SDK:ssa:

Tapa Kuvaus
onMessageDelete Käsittelee viestin poistotoimia
onMessageUpdate Käsittelee sanoman päivitystoiminnot
onSignInInvoke Käsittelee kirjautumiskutsutoiminnot

Puuttuvat menetelmät agenttien SDK:ssa:

Tapa Syy
onCommand Komentotoimintoja ei tueta
onCommandResult Komentotulostoimintoja ei tueta
onEvent Yleinen tapahtumien käsittely (tietyt tapahtumatyypit, kuten onTokenResponseEvent ovat edelleen tuettuja)
onTokenResponseEvent OAuth-tunnuksen vastaustapahtumat

Menetelmän allekirjoituksen muutokset:

Kaikki käsittelijän menetelmät palaavat ActivityHandler menetelmän this ketjutuksen sijaan. Käsittelijän funktiot käyttävät -tyyppiä AgentHandler , jolla on sama allekirjoitus kuin BotHandler

Siirtoesimerkki:

Bot Framework SDK:

const { ActivityHandler } = require('botbuilder');

class MyBot extends ActivityHandler {
    constructor() {
        super();
        this.onMessage(async (context, next) => {
            await context.sendActivity('Hello!');
            await next();
        });
    }
}

Siirtyminen on pääosin yksinkertaista, ja tärkein muutos on tuontilauseke ja käsittelijän tyyppi. Useimmat olemassa olevat ActivityHandler-pohjaiset botit toimivat mahdollisimman vähäisin muutoksin.

Tärkeää

On ActivityHandler syrjäytetty uuden AgentApplication luokan hyväksi.

Siirtyminen kohteesta ActivityHandler kohteeseen AgentApplication

Yhteensopivuus ActivityHandler aiempien versioiden kanssa on tuettua, mutta suosittelemme käyttämään AgentApplicationseuraavaa menetelmää:

:n käyttäminen ActivityHandler

import { ActivityHandler } from '@microsoft/agents-hosting'

class MyBot extends ActivityHandler {
    constructor() {
        super()
        this.onMessage(async (context, next) => {
            await context.sendActivity('Hello!')
            await next()
        })
        
        this.onMembersAdded(async (context, next) => {
            await context.sendActivity('Welcome!')
            await next()
        })
    }
}

Tärkeimmät erot

Seuraavassa taulukossa kuvataan - ja ActivityHandler-ominaisuuksien väliset AgentApplication tärkeimmät ominaisuuksien erot:

Ominaisuus ActivityHandler AgentApplication
Osavaltion hallinta Manuaalinen tilanhallinta vaaditaan Sisäänrakennettu tilanhallinta tarjolla
Tapahtuman käsittely Yleiset tapahtumakäsittelijät (esimerkiksi onMembersAdded) Tarkempia tapahtumakäsittelijöitä (esimerkiksi membersAdded)
Next Function Käsittelijöiden tulee kutsua next() Käsittelijät eivät vaadi kutsumista next()
Tallennus Manuaalinen tallennustilan määritys Sisäinen tallennustuki ja automaattinen tilan pysyvyys

Yleiset siirtotavat

Yleisiä siirtomalleja ovat:

Yksinkertainen Echo-botti

Bot Framework

const { ActivityHandler } = require('botbuilder')

class EchoBot extends ActivityHandler {
    constructor() {
        super()
        this.onMessage(async (context, next) => {
            await context.sendActivity(`You said: ${context.activity.text}`)
            await next()
        })
    }
}

Osavaltion hallinta

:n käyttäminen AgentApplication

import { AgentApplication, MemoryStorage } from '@microsoft/agents-hosting'

const agent = new AgentApplication({
    storage: new MemoryStorage()
})

agent.onMessage('/count', async (context, state) => {
    const count = state.conversation.count ?? 0
    state.conversation.count = count + 1
    await context.sendActivity(`Count: ${state.conversation.count}`)
})

Periytyminen AgentApplication-kohteesta

Monimutkaisempia skenaarioita varten voit luoda luokan, joka perii kohteesta AgentApplication:

import { AgentApplication, MemoryStorage, MessageFactory } from '@microsoft/agents-hosting'

class MyAgent extends AgentApplication {
    constructor() {
        super({
            storage: new MemoryStorage()
        })
        this.setupRoutes()
    }
    
    setupRoutes() {
        this.onMessage('/help', this.handleHelp)
        this.onMessage('/status', this.handleStatus)
        this.onMessage('/reset', this.handleReset)
        
        this.onActivity('message', this.handleDefault)
        this.onConversationUpdate('membersAdded', this.handleWelcome)
    }
    
    handleHelp = async (context, state) => {
        const helpText = `
                Available commands:
                - /help - Show this help message
                - /status - Show current status
                - /reset - Reset conversation state
        `
        await context.sendActivity(MessageFactory.text(helpText))
    }
    
    handleStatus = async (context, state) => {
        const messageCount = state.conversation.messageCount ?? 0
        await context.sendActivity(`Messages processed: ${messageCount}`)
    }
    
    handleReset = async (context, state) => {
        state.deleteConversationState()
        await context.sendActivity('Conversation state has been reset.')
    }
    
    handleWelcome = async (context, state) => {
        const welcomeText = 'Welcome! Type /help to see available commands.'
        await context.sendActivity(MessageFactory.text(welcomeText))
    }
    
    handleDefault = async (context, state) => {
        // Increment message counter
        const messageCount = (state.conversation.messageCount ?? 0) + 1
        state.conversation.messageCount = messageCount
        
        const replyText = `Echo: ${context.activity.text} (Message #${messageCount})`
        await context.sendActivity(MessageFactory.text(replyText))
    }
}

export default new MyAgent()

Tämän mallin edut

Etu Kuvaus
Parempi organisaatio Erilliset menetelmät eri käsittelijöille
Uudelleenkäytettävyys Voidaan helposti laajentaa tai periä edelleen
Koeteltavuus Yksittäisiä menetelmiä voidaan testata yksittäin
Ylläpidettävyyttä Monimutkaisten bottien siistimpi koodirakenne
Nuolifunktiot Kontekstin automaattinen sitominen this ilman tarvetta .bind()

Liittyvä sisältö

  • Last updated on