Activity Protocolin ymmärtäminen

Activity Protocol on kommunikaatioprotokolla ja vakioprotokolla, joita käytetään Microsoftissa monissa Microsoftin SDK:issa, palveluissa ja asiakkaissa. Tähän sisältyvät Microsoft 365 Copilot, Microsoft Copilot Studio ja Microsoft 365 Agents SDK. Toimintaprotokolla määrittää kohteen muodon 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 jokaisen asiakkaan, mukaan lukien Microsoftin ja kolmannen osapuolen asiakkaiden, välillä, joten sinun ei tarvitse luoda mukautettua logiikkaa työskentelemistäsi kanavaa kohden.

Mikä toiminto on?

Activity on jäsennetty JSON-objekti, joka edustaa käyttäjän ja agenttisi välistä vuorovaikutusta. Toiminnot eivät ole vain tekstipohjaisia viestejä, ne voivat sisältää monenlaisia toimia, kuten tapahtumia, kuten käyttäjän liittyminen sovelluksiin tai poistuminen sovelluksille, jotka tukevat useita käyttäjiä, kirjoitusilmaisimet, tiedostojen lataukset, korttitoiminnot ja mukautetut tapahtumat, jotka kehittäjät suunnittelevat itse.

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ää Toiminto-protokollan: Activity protocol – Activity. Toimintoprotokollassa määritettyjä tärkeimpiä ominaisuuksia ovat seuraavat:

Ominaisuus	Kuvaus
`Id`	Yleensä kanavan luoma, jos se on peräisin kanavasta
`Type`	Tyyppi ohjaa aktiviteetin merkitystä, esimerkiksi viestityyppiä
`ChannelID`	Viittaa `ChannelID` kanavaan, josta aktiviteetti on peräisin. Esimerkki: `msteams`.
`From`	Aktiviteetin lähettäjä (joka voi olla käyttäjä tai agentti)
`Recipient`	Aktiviteetin aiottu vastaanottaja
`Text`	Viestin tekstisisältö
`Attachment`	Monipuolinen sisältö, kuten kortit, tiedostojen kuvat

Käyttötoiminnan tiedot

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

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

.NET: TurnContext
Python: TurnContext
JavaScript: TurnContext

Note

Tämän artikkelin koodikatkelmat käyttävät C#:tä. JavaScript- ja Python-versioiden syntaksi- ja ohjelmointirajapintarakenne ovat samankaltaisia.

On TurnContext tärkeä objekti, jota käytetään kaikissa keskusteluissa Microsoft 365 -agenttien SDK:ssa. 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 ylläpidetään kontekstia, lähetetään asianmukaisia vastauksia ja vuorovaikutteisia käyttäjiä asiakkaan/kanavan kanssa tehokkaasti. Aina, kun agenttisi vastaanottaa uuden toimen kanavasta, Agenttien SDK luo uuden TurnContext esiintymän ja välittää sen rekisteröidyille käsittelijöillesi/menetelmillesi. Tämä kontekstiobjekti on olemassa yksittäisen käännöksen aikana, ja se hävitetään, kun käännös päättyy.

Käänne määritetään asiakkaalta lähetetyn viestin kiertomatkaksi, ja samalla koodisi käsittelee nämä tiedot, ja koodi voi halutessaan lähettää vastauksen takaisin ja suorittaa käännöksen loppuun. Tämän edestakaisen matkan voi jakaa:

Saapuva toiminta: Käyttäjä lähettää viestin tai suorittaa toiminnon, joka luo aktiviteetin.
Koodi vastaanottaa toiminnon, ja agentti käsittelee sen :n avulla TurnContext.
Agenttisi lähettää yhden tai useamman aktiviteetin takaisin.
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 on tärkeä, koska se määrittää, mitä asiakkaiden, käyttäjien ja edustajien välinen toiminta edellyttää tai odottaa.

Viesti

Yleinen aktiviteettityyppi on Sanoma-tyyppiActivity, joka voi sisältää tekstiä, liitteitä ja ehdotettuja toimintoja ja nimetä muutamia yleisiä käyttötarkoituksia tälle tyypille.

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ä, sillä merkittävä asiakas on Microsoft Teams.

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.Reciepient.Id)
            {
                await turnContext.SendActivityAsync(MessageFactory.Text($"Welcome {member.Name}!"), cancellationToken);
            }
        }
    }
})

Tapahtumat

TapahtumatyyppiActivity on mukautettu tapahtuma, jonka avulla kanavat tai asiakkaat voivat lähettää jäsennettyjä tietoja agentillesi. Tätä ei ole määritetty etukäteen tietojen rakenteessaActivity.

Sinun on luotava menetelmän/reitityskäsittelijän tietylle Event tyypille ja hallittava sitten haluttua logiikkaa:

Nimi – Tapahtuman nimi tai tunniste asiakasarvo – 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)
}

Käynnistä

-kutsutyyppiActivity on tietyntyyppinen aktiviteetti, jota asiakas kutsuu agenttiin suorittaakseen komennon tai toiminnon, ei 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ämä näkyy yleensä ihmisten välisten keskustelujen välillä esimerkiksi Microsoft Teams -asiakasohjelmassa. Kirjoitustoimintoja ei tueta kaikissa asiakkaassa, eikä Microsoft 365 Copilot 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

Vastausten lähettämiseksi TurnContext tarjoaa useita menetelmiä vastausten lähettämiseksi 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

Agenttien on usein tehtävä yhteistyötä käyttäjien (tai jopa muiden agenttien) lähettämien liitteiden kanssa. Asiakas lähettää Message aktiviteetin, joka sisältää liitteen (se ei ole tietyntyyppistä toimintaa), ja koodisi on käsiteltävä viestin vastaanottaminen liitteen kanssa, luettava metatiedot ja noudettava tiedosto turvallisesti asiakkaan toimittamasta URL-osoitteesta. Tavallisesti tämä siirtää tiedoston omaan tallennustilaasi.

Liitteen vastaanottaminen

Seuraava koodi näyttää, miten vastaanotto ja liite lisätään

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ä asiakas lähettää todennetun GET pyynnön liitteenä tiedoston noutamiseksi. Kullakin sovittimella on oma tapansa saada tiedot, kuten Teams, OneDrive ja niin edelleen. On myös tärkeää tietää, että nämä URL-osoitteet ovat yleensä lyhytikäisia, joten älä oleta niiden säilyvän siellä, minkä vuoksi siirtyminen omaan tallennustilaasi on tärkeää, jos haluat viitata tähän myöhemmin.

Lainaukset

On tärkeää tietää, että liite ja lainaus eivät ole samaa objektityyppiä. Lainaukset ovat asiakkaiden, kuten Microsoft Teamsin, käsittelemiä ja käyttävät -kohteen Entiteetit-ominaisuuttaActivity. Niitä voidaan lisätä kohteen kanssa ja lisätä uuden activity.Entities.Add objektin kanssaEntity, jolla on asiakkaaseen perustuva erityinen Citation määritys. Se sarjoitetaan JSON-objektiksi, jonka asiakas sitten sarjoittaa sen perusteella, miten se hahmonnetaan asiakaskoneessa. Yleisesti ottaen liitteet ovat sanomia, ja lainaukset voivat viitata liitteisiin ja ovat toinen objekti, joka lähetetään EntitiesActivity tietojen kautta.

Kanavakohtaisia seikkoja

Microsoft 365 Agent sDK on rakennettu "keskukseksi", jonka avulla kehittäjät voivat luoda agentteja, jotka voivat työskennellä minkä tahansa asiakkaan kanssa, mukaan lukien tukemamme asiakkaat, ja tarjota kehittäjille työkaluja oman kanavasovittimen luomiseen käyttämällä samaa sovelluskehystä. Näin kehittäjät voivat agentteja käsiteltäessä laajennettavuutta asiakkaille, jotta he voivat muodostaa yhteyden kyseiseen keskukseen. Asiakas voi esimerkiksi olla yksi tai useampi asiakas, kuten Microsoft Teams ja Slack.

Eri kanavilla on eri ominaisuuksia ja rajoituksia, ja seuraavassa on yhteenveto huomioon otettavista seikoista, kun työskentelet yleisten asiakkaiden kanssa.

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

Kanavat sisältävät tiettyjä tietoja, jotka eivät vastaa yleisiä Activity hyötymääriä kaikissa kanavissa, ja niitä voi käyttää TurnContext-funktiolla.Activity.ChannelData ja erityisesti sen heittäminen muuttujiin koodissasi käytettäväksi.

Microsoft-tiimit

Tukee monipuolisia mukautuvia kortteja kehittyneillä ominaisuuksilla
Tukee viestipäivityksiä ja poistoja
Sisältää tiettyjä Teamsin ominaisuuksia koskevia kanavatietoja (maininnat, kokoustiedot ja niin edelleen)
Tukee kutsutoimintoja tehtävämoduuleissa

Microsoft 365 Copilot

Ensisijaisesti viestitoimintoihin keskittyvät
Tukee lainauksia ja viittauksia vastauksissa
Edellyttää suoratoistovastauksia
Rajoitettu tuki monipuolisille korteille tai mukautuville korteille

WebChat/DirectLine

Web Chat on HTTP-protokolla, jota käytetään agenttien puhuessa HTTPS-yhteyden kautta

Täysi tuki kaikille toimintotyypeille
Tukee mukautettujen kanavien tietoja

Kolmansien osapuolten kanavat

Näitä ovat esimerkiksi Slack ja Facebook.

Tietyille toimintotyypeille saattaa olla rajallinen tuki
Kortin hahmontaminen voi olla erilaista tai ei-tuettua
Tarkista aina tietyn kanavan dokumentaatio

Palaute

Onko tästä sivusta apua?

Last updated on 2025-11-19