Activity Protocolin ymmärtäminen

Activity Protocol on standard-kommunikaatioprotokolla jota käytetään Microsoft monissa Microsoft SDK:issa, palveluissa ja asiakasohjelmissa. Activity Protocolia käyttävät Microsoft 365 Copilot, Microsoft Copilot Studio ja Microsoft 365 -agenttien SDK. Activity Protocol määrittää kohteen rakenteen Activity ja sen, miten viestit, tapahtumat ja vuorovaikutukset kulkevat kanavasta koodiin ja kaikkialle muulle näiden välillä. Asiakaspalvelijat voivat muodostaa yhteyden yhteen tai useampaan kanavaan, jotta he voivat olla vuorovaikutuksessa käyttäjien kanssa ja työskennellä muiden agenttien kanssa. Activity Protocol yhdenmukaistaa viestintäprotokollan minkä tahansa käyttämäsi asiakkaan kanssa, mukaan lukien Microsoft- ja ei-Microsoft asiakasohjelmat, jotta sinun ei tarvitse luoda mukautettua logiikkaa kullekin kanavalle.

Mikä toiminto on?

Activity on jäsennetty JSON-objekti, joka edustaa käyttäjän ja agenttisi välistä vuorovaikutusta. Aktiviteetti ei rajoitu tekstipohjaisiin viesteihin. Ne voivat sisältää erityyppisiä vuorovaikutuksia, kuten tapahtumia, kuten käyttäjän liittyminen tai poistuminen useita käyttäjiä tukeville asiakkaille, ilmaisimien kirjoittaminen, tiedostojen lataukset, korttitoiminnot ja kehittäjän suunnittelemat mukautetut tapahtumat.

Jokainen toiminto sisältää metatietoja aiheesta:

• Kuka sen lähetti (kohteesta)
• Kenen pitäisi saada se (vastaanottaja)
• Keskustelukonteksti
• Kanava, josta se on peräisin
• Vuorovaikutuksen tyyppi
• Hyötykuormatiedot

Toimintorakenne – tärkeimmät ominaisuudet

Tämä määritys määrittää Activity Protocol: Activity Protocol – Activity. Activity Protocolissa määritettyjä tärkeimpiä ominaisuuksia ovat:

Toimintotietojen käyttäminen

Kehittäjien TurnContext on käytettävä toiminnon sisältämiä tietoja suorittaakseen toimintoja objektista.

Löydät TurnContext luokan Microsoft 365 -agenttien SDK:n jokaisesta kieliversiosta:

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

TurnContext on tärkeä objekti, jota käytetään jokaisessa keskustelussa Microsoft 365 -agenttien SDK. Se tarjoaa käyttöoikeuden saapuvaan toimintaan, menetelmiä vastausten lähettämiseen, keskustelun tilanhallintaan ja kontekstiin, jota tarvitaan yksittäisen keskustelun käänteen käsittelemiseen. Sen avulla voit ylläpitää kontekstia, lähettää asianmukaisia vastauksia ja olla tehokkaasti vuorovaikutuksessa käyttäjiesi kanssa heidän asiakkaallaan tai kanavallaan. Aina, kun agentti saa uuden toimen kanavasta, Agenttien SDK luo uuden TurnContext esiintymän ja välittää sen rekisteröidyille käsittelijöillesi tai menetelmillesi. Tämä kontekstiobjekti on olemassa yksittäisen käännöksen aikana, ja se hävitetään, kun vuoro päättyy.

Kierros määritetään asiakkaalta lähetetyn viestin matkaksi, joka kulkee koodissasi edestakaisin. Koodisi käsittelee nämä tiedot, ja se voi myös lähettää vastauksen takaisin suorittaakseen käännöksen. Tämä kierto voidaan jakaa seuraaviin vaiheisiin:

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

2. Koodi vastaanottaa toiminnon, ja agentti käsittelee sen :n avulla TurnContext.

3. Agenttisi lähettää yhden tai useamman aktiviteetin takaisin.

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

Käytä tietoja : TurnContextsta, kuten:

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

Tämä koodikatkelman näyttää esimerkin täydellisestä käännöksestä:

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 sisällä ovat usein käytetyt avaintiedot:

• Aktiviteetti: pääasiallinen tapa hakea tietoja aktiviteetista
• Sovitin: tämä on aktiviteetin luonut kanavasovitin.
• TurnState: Vuoron tila

Toimintatyypit

Aktiviteetin tyyppi määrittää, mitä toiminnan loppuosa edellyttää tai odottaa asiakkaiden, käyttäjien ja agenttien välillä.

Näitä ovat:

• Sanoma
• Keskustelupäivitys
• Tapahtuma
• Aktivoi
• Kirjoittaa

Sanoma

Yleinen aktiviteetin tyyppi on Sanoma-tyyppi .Activity Tämä 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);
});

Keskustelupäivitys

ConversationUpdate-tyyppiActivity ilmoittaa agentillesi, kun jäsenet liittyvät tai lähtevät keskustelusta. Kaikki asiakkaat eivät tue tätä ilmoitusta, mutta Microsoft Teams tukee.

Seuraava koodikatkelman tervehtii uusia jäseniä 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

TapahtumatyyppiActivity on mukautettu tapahtuma, jonka avulla kanavat tai asiakkaat lähettävät jäsennettyjä tietoja agentillesi. Näitä tietoja ei ole määritetty etukäteen tietojen rakenteessa Activity .

Sinun on luotava menetelmä tai reitityskäsittelijä tietylle Event tyypille. Hallitse sitten haluttua logiikkaa seuraavasti:

• Nimi: tapahtuman nimi tai tunniste asiakkaalta
• Arvo: Tapahtuman tiedot, jotka ovat yleensä JSON-objekteja

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)
});

Aktivoi

KutsutyyppiActivity on tietyntyyppinen aktiviteetti, jonka asiakas kutsuu agentiksi suorittaakseen komennon tai toiminnon. Se ei ole vain viesti. Tällaisia toimintoja ovat esimerkiksi esimerkiksi Microsoft Teams for task/fetch ja task/submit. Kaikki kanavat eivät tue tämäntyyppisiä toimintoja.

Kirjoittaa

KirjoittaminenActivity on aktiviteetin luokitus, joka ilmaisee, että joku kirjoittaa keskustelussa. Tällaista toimintaa nähdään yleensä ihmisten ja ihmisten välisten keskustelujen välillä esimerkiksi Microsoft Teams asiakaskoneessa. Kirjoittamistoimintoja ei tueta kaikissa asiakaskoneissa. Microsoft 365 Copilot eivät erityisesti tue kirjoitustoimintoja.

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

Aktiviteettien luominen ja lähettäminen

Jos haluat lähettää vastauksia, tarjoaa TurnContextuseita tapoja lähettää vastauksia 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

Asiakaspalvelijat työskentelevät usein käyttäjien (tai jopa muiden edustajien) lähettämien liitteiden kanssa. Asiakas lähettää Message aktiviteetin, joka sisältää liitteen (se ei ole tietyntyyppistä aktiviteettia). Koodin on käsiteltävä viestin vastaanottaminen liitteen kanssa, luettava metatiedot ja noudettava tiedosto turvallisesti asiakkaan antamasta URL-osoitteesta. Yleensä siirrät tiedoston omaan tallennustilaasi.

Liitteen vastaanottaminen

Seuraava koodi näyttää, miten voit vastaanottaa liitteen.

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ä jos asiakas haluaa vastaanottaa asiakirjan liitettä varten, hän lähettää todennetun GET pyynnön varsinaisen sisällön noutamista varten. Kummallakin sovittimella on oma tapansa saada nämä tiedot. Esimerkiksi Teams ja OneDrive. On myös tärkeää tietää, että nämä URL-osoitteet ovat yleensä lyhytikäisia, joten älä oleta URL-osoitteiden pysyvän voimassa pitkään. Tämän rajoituksen vuoksi omaan tallennustilaan siirtyminen on tärkeää, jos haluat tarkastella sisältöä myöhemmin.

Lainaukset

On tärkeää tietää, että liite ja lainaus eivät ole samaa objektityyppiä. Asiakkaat, kuten Microsoft Teams, käsittelevät lainauksia omilla tavoillaan. He käyttävät kohteen Entiteetit-ominaisuuttaActivity. Voit lisätä lainauksia :n kanssa activity.Entities.Add ja lisätä uuden Entity objektin, jolla on asiakkaaseesi perustuva erityinen Citation määritys. Se sarjoitetaan JSON-objektiksi, jonka asiakas sitten sarjoittaa sen perusteella, miten se hahmonnetaan asiakaskoneessa. Periaatteessa liitteet ovat sanomia, ja lainaukset voivat viitata liitteisiin ja ovat toinen objekti, joka lähetetään EntitiesActivity tietojen kautta.

Kanavakohtaisia seikkoja

Microsoft 365 -agenttien SDK luodaan "keskukseksi", jonka avulla kehittäjät luovat agentteja, jotka voivat työskennellä any -asiakkaan kanssa, mukaan lukien tukemamme asiakkaat. Se tarjoaa kehittäjille työkalut oman kanavasovittimen luomiseen samalla kehyksellä. Tämä arkkitehtuuri tarjoaa kehittäjille laajuuden agenttien suhteen ja laajennettavuuden asiakkaille, jotta he voivat muodostaa yhteyden tähän keskukseen, mikä voi olla yksi tai useampi asiakas, kuten Microsoft Teams, Slack ja paljon muuta.

Eri kanavilla on eri ominaisuuksia ja rajoituksia.

Voit tarkistaa kanavan, josta sait toiminnon, tarkistamalla ominaisuuden channelId kohteessa Activity.

Kanavat sisältävät tiettyjä tietoja, jotka eivät vastaa yleisiä Activity hyötymääriä kaikissa kanavissa. Voit käyttää näitä tietoja -ominaisuudesta TurnContext.[Activity.ChannelData](/dotnet/api/microsoft.agents.core.models.activity.channeldata) heittämällä ne muuttujiin koodissasi käytettäväksi.

Seuraavissa osissa on yhteenveto huomioon otettavia seikkoja, kun työskentelet yleisten asiakkaiden kanssa.

Microsoft Teams

• Tukee monipuolisia Mukautuvat kortit kehittyneillä ominaisuuksilla.
• Tukee viestipäivityksiä ja poistoja.
• Sisältää tiettyjä Teamsin ominaisuuksien kanavatietoja, kuten mainintoja ja kokoustietoja.
• Tukee aktiviteettien kutsumista tehtävämoduuleissa.

Microsoft 365 Copilot

• Ensisijaisesti viestitoimintoihin keskittyneitä.
• Tukee lainauksia ja viittauksia vastauksissa.
• Edellyttää suoratoistovastauksia.
• Rajoitettu tuki monipuolisille korteille ja mukautuville korteille.

WWW-keskustelu/DirectLine

WWW-keskustelu on HTTP-protokolla, jonka avulla agentit voivat viestiä HTTPS:n kautta.

• Täysi tuki kaikille toimintotyypeille.
• Tukee mukautettuja kanavatietoja.

Ei-Microsoft-kanavat

Näihin kanaviin kuuluvat Slack, Facebook ja paljon muuta.

• Tietyille toimintotyypeille saattaa olla rajallinen tuki.
• Kortin hahmontaminen voi olla erilaista tai sitä ei tueta.
• Tarkista aina tietyn kanavan dokumentaatio.

Seuraavat vaiheet

• Lisätietoja AgentApplicationista