Aktiviteettiprotokollan ymmärtäminen

Aktiviteettiprotokolla on viestinnän standardiprotokolla, jota Microsoft käyttää monissa Microsoftin SDK:issa, palveluissa ja asiakasohjelmissa. Microsoft 365 Copilot, Microsoft Copilot Studio, Microsoft Teams ja Microsoft 365 -agenttien SDK käyttää aktiviteettiprotokollaa. Aktiviteettiprotokolla määrittää Activity-rakenteen sekä tavan, jolla viestit, tapahtumat ja vuorovaikutukset siirtyvät kanavasta koodiin ja kaikkeen niiden välissä. Agentit voivat muodostaa yhteen tai useaan kanavaan, joissa ne voivat olla vuorovaikutuksessa asiakkaiden kanssa tai joissa niitä voidaan käyttää muiden agenttien kanssa. Aktiviteettiprotokolla standardoi viestintäprotokollan riippumatta siitä, mikä asiakasohjelma on käytössä ja olipa kyseessä Microsoftin tai muiden kuin Microsoft asiakasohjelmat, joten kutakin kanavaa varten eri tarvitse luoda mukautettua logiikkaa.

Mikä on aktiviteetti?

Activity on jäsennetty JSON-objekti, joka edustaa mitä tahansa käyttäjän ja agentin välistä vuorovaikutusta. Aktiviteetit eivät ole vain tekstipohjaisia viestejä. Kyse voi olla monenlaisista vuorovaikutuksista, joita ovat esimerkiksi tapahtumat, kuten käyttäjän liittymien useita käyttäjiä tukeviin asiakasohjelmiin tai niistä poistuminen, kirjoitusilmaisimet, tiedostolataukset, kortin toiminnot sekä kehittäjien suunnittelemat mukautetut tapahtumat.

Jokaisessa toiminnassa on seuraavankaltaisia metatietoja:

• Kuka on lähettänyt (lähettäjä)
• Kuka on vastaanottaja (vastaanottaja)
• Keskustelun konteksti
• Kanava, josta se on peräisin
• Vuorovaikutuksen tyyppi
• Tiedot

Aktiviteetin rakenne – keskeiset ominaisuudet

Tämä määritys määrittää aktiviteettiprotokollan: Aktiviteettiprotokolla – aktiviteetti. Aktiviteettiprotokollassa määritettyjä keskeisiä ominaisuuksia:

Aktiviteettitietojen käyttäminen

Toimintojen suorittaminen TurnContext-objektista edellyttää, että kehittäjät voivat käyttää aktiviteetin tietoja.

TurnContext-luokka löytyy Microsoft 365 -agenttien SDK:n jokaisesta kieliversiosta:

• .NET: TurnContext
• Python: TurnContext
• JavaScript: TurnContext

TurnContext on tärkeä objekti, jota käytetään jokaisessa Microsoft 365 -agenttien SDK:n keskusteluvuorossa. Se mahdollistaa saapuvan aktiviteetin käytön, vastauksen lähettämismenetelmät, keskustelun tilan hallinnan ja kontekstin, joka tarvitaan yhden keskusteluvuoron käsittelyyn. Sen avulla voidaan ylläpitää kontekstia, lähettää sopivia vastauksia ja olla yhteydessä käyttäjiin tehokkaasti asiakasohjelmassa tai kanavassa. Aina kun agentti vastaanottaa kanavasta uuden aktiviteetin, agenttien SDK luo uuden TurnContext-esiintymän ja siirtää sen rekisteröidyille käsittelijöille tai menetelmiin. Tämä kontekstiobjekti on olemassa yhden vuoron ajan, ja se hävitetään vuoron päätyttyä.

Vuoro tarkoittaa asiakasohjelmasta lähetetyn viestin edestakaista siirtymää koodiin. Koodi käsittelee kyseiset tiedot ja voi valinnaisesti lähettää vastauksen takaisin, jolloin vuoro valmistuu. Tuo edestakainen matka voidaan jakaa seuraaviin vaiheisiin:

1. Saapuva aktiviteetti: käyttäjä lähettää viestin tai suorittaa toiminnon, joka luo aktiviteetin.

2. Koodi vastaanottaa aktiviteetin ja agentti käsittelee sen TurnContext-objektissa.

3. Agentti lähettää vähintään yhden aktiviteetin takaisin.

4. Vuoro päättyy ja TurnContext hävitetään.

Esimerkiksi seuraavia TurnContext-tietoja käytetään:

var messageText = turnContext.Activity.Text;
var channelID = turnContext.Activity.ChannelId;

Tässä koodikatkelmassa on esimerkki kokonaisesta vuorosta:

agent.OnActivity(ActivityTypes.Message, async (turnContext, turnState, cancellationToken) =>
{
    var userMessage = turnContext.Activity.Text;
    var response = $"you said: {userMessage}";
    await turnContext.SendActivityAsync(MessageFactory.Text(response), cancellationToken);
});

TurnContext-luokan yleisesti käytettyjä keskeisiä tietoja:

• Aktiviteetti: pääasiallisen tapa saada tietoja aktiviteetista
• Sovitin: aktiviteetin luonut kanavasovitin
• TurnState: Vuoron tila

Toimintatyypit

Aktiviteetin tyyppi määrittää, mitä muuta aktiviteetti tarvitsee tai odottaa asiakasohjelmilta, käyttäjiltä ja agenteilta.

Näitä ovat:

• Sanoma
• ConversationUpdate
• Tapahtuma
• Käynnistä
• Kirjoittaa

Sanoma

Yleinen aktiviteettityyppi on Message-tyyppinen Activity. Activity-tyyppi voi sisältää tekstiä, liitteitä ja ehdotettuja toimintoja.

agent.OnActivity(ActivityTypes.Message, async (turnContext, turnState, cancellationToken) =>
{
    var userMessage = turnContext.Activity.Text;
    var response = $"you said: {userMessage}";
    await turnContext.SendActivityAsync(MessageFactory.Text(response), cancellationToken);
});

ConversationUpdate

ConversationUpdate-tyyppinen Activity ilmoittaa agentille, kun jäseniä liittyy keskusteluun tai poistuu siitä. Vaikka kaikki asiakasohjelmat eivät tue tätä ilmoitusta, Microsoft Teams tukee sitä.

Seuraava koodikatkelma koskee uusien jäsenien tervehtimistä keskustelussa:

agent.OnActivity(ActivityTypes.ConversationUpdate, async (turnContext turnState, cancellationToken) =>
{
    var membersAdded = turnContext.Activity.MembersAdded
    if (membersAdded != null)
    {
        foreach (var member in membersAdded)
        {
            if (member.Id != turnContext.Activity.Recipient.Id)
            {
                await turnContext.SendActivityAsync(MessageFactory.Text($"Welcome {member.Name}!"), cancellationToken);
            }
        }
    }
})

Tapahtumat

Event-tyyppinen Activity on mukautettu tapahtuma, jonka avulla kanavat tai asiakasohjelmat lähettävät jäsennettyjä tietoja agentille. Näitä tietoja ei ole ennalta määritelty Activity-tietorakenteessa.

Tiettyä Event-tyyppiä varten on luotava menetelmä tai reitityskäsittelijä. Toivottua logiikkaa hallintaa sitten seuraavien perusteella:

• Nimi: tapahtuman nimi tai tunniste asiakasohjelmasta
• Arvo: tapahtuman tiedot yleensä JSON-objektina

agent.OnActivity(ActivityTypes.Event, async (turnContext turnState, cancellationToken) =>
{
    var eventName = turnContext.Activity.Name;
    var eventValue = turnContext.Activity.Value;

    // custom event (E.g. a switch on eventName)
});

Käynnistä

Invoke-tyyppinen Activity on tietynlainen aktiviteettityyppi, jonka asiakasohjelma kutsuu agenttiin suorittamaan komennon tai toiminnon. Kyseessä ei ole pelkkä viesti. task/fetch ja task/submit ovat Microsoft Teamsissa yleisiä esimerkkejä tällaisista aktiviteeteista. Kaikki kanavat eivät tue tämäntyyppisiä aktiviteetteja.

Kirjoittaa

Typing-tyyppinen Activity on aktiviteetin luokittelu ilmaisemaan, että joku kirjoittaa keskustelussa. Tämä aktiviteetti esiintyy usein ihmisten välisissä keskusteluissa esimerkiksi Microsoft Teams -asiakasohjelmassa. Kaikki asiakasohjelmat eivät tue Typing-aktiviteetteja. Huomionarvoista on, että Microsoft 365 Copilot ei tue Typing-aktiviteetteja.

await turnContext.SendActivityAsync(new Activity { Type = ActivityTypes.Typing }, cancellationToken); 
await Task.Delay(2000);
await turnContext.SendActivityAsync(MessageFactory.Text("Here is your answer..."), cancellationToken);

Aktiviteettien luonti ja lähettäminen

Vastausten lähettämistä varten TurnContext sisältää useita menetelmiä, joilla vastaus voidaan lähettää takaisin käyttäjälle.

agent.OnActivity(ActivityTypes.Message, async (turnContext, turnState, cancellationToken))
{
    await turnContext.SendActivityAsync("hello!", cancellationToken: CancellationToken); // uses string directly
    await turnContext.SendActivityAsync(MessageFactory.Text("Hello"), cancellationToken); // uses Message Factory
    await turnContext.SendActivitiesAsync(activities, cancellationToken); // send multiple activities in an Activity array
}

Liitteiden käyttäminen

Agentit käsittelevät usein liitteitä, joita käyttäjät (tai jopa muut agentit) lähettävät. Asiakas lähettää liitteen sisältävän Message-aktiviteetin (joka ei ole oma aktiviteettityyppi). Koodin on käsiteltävä liitteen sisältävän viestin vastaanottaminen, luettava metatiedot ja noudettava tiedosto turvallisesti asiakasohjelman ilmoittamasta URL-osoitteesta. Yleensä tiedosto siirretään omaan tallennustilaan.

Liitteen vastaanottaminen

Seuraava koodi näyttää, miten liite vastaanotetaan.

agent.OnActivity(ActivityTypes.Message, async(turnContext, turnState, cancellationToken)) =>
{
    var activity = turnContext.Activity;
    if (activity.Attachments != null && activity.Attachments.Count > 0)
    {
        foreach (var attachment in activity.Attachments)
        {
            // get metadata as required e.g. attachment.ContextType or attachment.ContentUrl
            // use the URL to securely download the attachment and complete your business logic
        };
    }
}

Yleensä liitteen asiakirjan vastaanottaminen mahdollistetaan siten, että asiakasohjelma lähettää todennetun GET-pyynnön noutamaan varsinaisen sisällön. Kullakin sovittimella on oma tapa hakea tiedot. Esimerkkejä ovat vaikkapa Teams ja OneDrive. On myös tärkeää tietää, että kyseiset URL-osoitteet ovat yleensä lyhytikäisiä, joten URL-osoitteiden ei kannata olettaa toimivan pitkään. Tämä rajoitus selittää, miksi omaan tallennustilaan siirtäminen on tärkeää, jos sisältöön halutaan viitata myöhemmin.

Lainaukset

On tärkeää tietää, että Attachment ja Citation ovat eri objektityyppejä. Asiakasohjelmat, kuten Microsoft Teams, käsittelevät lähdeviittauksia omalla tavallaan. He käyttävät Activity-objektin Entities-ominaisuutta . Lähdeviitteitä voidaan lisätä muodossa activity.Entities.Add. Lisäksi lisätään uusi Entity-objekti, jossa on asiakasohjelmaan perustuva Citation-määritys. Se sarjoitetaan JSON-objektiksi, jonka sarjoituksen asiakasohjelma sitten poistaa sen perusteella, miten se hahmonnetaan asiakasohjelmassa. Viime kädessä liitteet ovat viestejä ja lähdeviitteet voivat viitata liitteisiin, minkä lisäksi ne ovat myös yksi Activity-tietojen Entities-objektissa lähetetty objekti.

Kanavakohtaisesti huomioitavia seikkoja

Microsoft 365 -agenttien SDK on kehitetty keskukseksi, ja kehittäjät voivat luoda siinä agentteja, jotka toimivat missä tahansa asiakasohjelmassa, mukaan lukien Microsoftin tukemat asiakasohjelmat. Sen avulla kehittäjät saavat työkalut, joilla he voivat kehittää oman kanavasovittimen saman kehyksen avulla. Tämä arkkitehtuuri antaa kehittäjille monipuoliset mahdollisuudet agenttien kehittämiseen ja mahdollistaa laajennettavuuden, jolla asiakasohjelmat voidaan yhdistää keskukseen. Kyse voi olla yhdestä tai useasta asiakasohjelmasta, kuten Microsoft Teams ja Slack.

Eri kanavilla on erilaisia ominaisuuksia ja rajoituksia.

Kanava, josta aktiviteetti vastaanotettiin, voidaan tarkistaa tarkastelemalla Activity-objektin channelId-ominaisuutta.

Tietyt kanavien tiedot eivät vastaa kaikissa kanavissa yleisiä Activity-tietoja. Nämä tietoja voidaan käyttää TurnContext.[Activity.ChannelData](/dotnet/api/microsoft.agents.core.models.activity.channeldata)-ominaisuudesta muuttamalla sen koodissa käytettäviksi muuttujiksi.

Seuraavat osioissa on tiivistelmä huomioitavista seikoista yleisiä asiakasohjelmia käytettäessä.

Microsoft Teams

• Tukee monipuolisten mukautettujen korttien lisäominaisuuksia.
• Tukee viestien päivittämistä ja poistamista.
• Sisältää kanavakohtaisia Teams-ominaisuuksien tietoja, kuten mainintoja ja kokoustietoja.
• Tukee tehtävämoduulien käynnistysaktiviteetteja.

Microsoft 365 Copilot

• Koskee pääasiassa viestiaktiviteetteja.
• Tukee vastauksissa lähdeviitteitä ja viittauksia.
• Edellyttää vastauksia suoratoistona.
• Monipuolisten korttien ja mukautettujen korttien rajoitettu tuki.

Verkkokeskustelu/DirectLine

Verkkokeskustelu HTTP-protokolla, jota agentit voivat käyttää viestintään HTTPS-yhteydellä.

• Kaikkien aktiviteettityyppien täysi tuki.
• Tukee mukautettuja kanavatietoja.

Muut kuin Microsoftin kanavat

Tällaisia kanavia ovat esimerkiksi Slack ja Facebook.

• Tiettyjen aktiviteettityyppien tuki voi olla rajallista.
• Korttien hahmontaminen voi olla erilaista tai sitä ei tueta.
• Kanavakohtaiseen dokumentaatioon kannattaa aina perehtyä.

Seuraavat vaiheet

• Lisätietoja AgentApplication-rakenneosasta