Microsoft 365 Copilot API razvijalcem omogoča, da funkcionalnosti generativne umetne inteligence vključijo neposredno v lastne aplikacije, SharePoint strani in SPFx gradnike. V članku je predstavljen praktičen primer uporabe Copilot Chat API-ja v SharePoint Framework gradniku za prikaz pomembnih informacij iz Microsoft 365 okolja, skupaj s ključnimi koraki, konfiguracijo in priporočili za varno ter učinkovito uporabo.

Pomembne informacije s SPFx in Copilot API

Microsoft 365 Copilot je v zadnjih letih postal osrednji del sodobnih poslovnih okolij, saj omogoča uporabo naprednih jezikovnih modelov neposredno v okviru Microsoftovih aplikacij. Zmožnost povezovanja generativne umetne inteligence z organizacijskimi podatki v Microsoft 365 okolju omogoča razvijalcem, da z uporabo Graph API-ja, ustvarijo inteligentne, kontekstne funkcionalnosti, ki temeljijo na pogovornih vmesnikih, iskanju in generiranju vsebin. V tem članku bom predstavil, kako lahko uporabimo Copilot Graph API v SPFx gradniku za ustvarjanje enostavnega klepeta, ki prikazuje pomembne informacije.

Copilot Graph API omogoča dostop do Copilotovih funkcionalnosti kot sta pogovorne interakcije in iskanje z uporabo podatkov iz Microsoft 365. API trenutno vključuje dva ključna dela, Chat API in Search API. Chat API omogoča več nivojske pogovore s Copilotom, vključno z uporabo konteksta iz SharePointa, OneDrivea in drugih virov. Search API omogoča pametno iskanje z razširjenimi rezultati, metapodatki in citati. Za pravilno delovanje je pomembno, da se Copilot API-ji kličejo preko beta endpointov, kar pomeni, da je treba ustrezno konfigurirati dovoljenja in poskrbeti za pravilno uporabo MSGraphClientV3.

V gradniku sem,  zaradi lažjega prilagajanja, dodal v nastavitve poziv, ki ga bo gradnik pošiljal Copilotu za začetek pogovora. Ker Copilot generira odgovore nestrukturirano, mu je treba v pozivu natančno opredeliti, katere podatke želimo in v kakšne formatu. V tem primeru je v pozivu določeno naj vrne informacije vezane na delo za posamezni dan, zraven pa je poslana tudi struktura na kakšen način mora podatke vračati. Ne glede na natančnost poziva, lahko pride do odstopanj, na kar moramo biti pozorni pri prikazovanju rezultatov.

PropertyPaneTextField('prompt', {

   label: 'Prompt',

   multiline: true,

   resizable: true

})

Ko je osnovna struktura postavljena, se lahko uredi komponento za prikazovanje rezultatov. Zaradi boljše preglednosti, sem metode za interakcijo s Copilotom pisal v ločeno datoteko, zato jo je treba najprej inicializirati.

private copilotService: CopilotService | null = null;

private initializeCopilotService = async () => {

  try {

    const graphClient = await this.props.context.msGraphClientFactory.getClient('3');

    this.copilotService = new CopilotService({ graphClient });

  } catch (error) {}

}

Za interakcijo sem pripravil dve metodi, za začetek pogovora in za pošiljanje posameznega sporočila. Da lahko gradnik komunicira s Copilotom je treba najprej ustvariti pogovor preko endpointa »/copilot/conversations«. Klic mora biti tipa POST, poslati pa mu ni treba nobenih dodatnih informacij. Ko je klic uspešen, ustvari nov pogovor in vrne id pogovora, ki ga lahko kasneje uporabimo za pošiljanje posameznih sporočil.

private async copilotCreateConversation(): Promise<string> {

  try {

    const response = await this.graphClient

      .api('/copilot/conversations')

      .version('beta')

      .post({});

    this.conversationId = response.id;

    if (!this.conversationId) {

      throw new Error('Napaka pri ustvarjanju pogovora.');

    }

    return this.conversationId;

  } catch (error) {

    throw error;

  }

}

Naslednja metoda pošlje Copilotu posamezno sporočilo znotraj izbranega pogovora. Metoda najprej preveri, če pogovor že obstaja. V primeru obstoječega pogovora uporabi poslani id, sicer pokliče zgoraj opisano metodo in ustvari nov pogovor. Za pošiljanje sporočila se uporabi endpoint »/copilot/conversations/{id-pogovora}/chat«. Tudi ta je tipa POST, zahteva pa določeno strukturo. V vsebini sporočila je treba določiti poziv, ki ga pošljemo preko lastnosti message.text. Zraven pa je treba navesti tudi osnovne informacije o lokaciji, locationHint.timeZone. V primeru, da je v gradniku začet le en pogovor, lahko metoda vrne rezultate neposredno, ker pa je v tem gradniku lahko začetih več pogovorov, je v spodnji metodi prilagojeno vračanje rezultatov in le ta vrne nov objekt z id-jem pogovora in rezultati.

public async copilotSendMessage(prompt: string, conversationId?: string): Promise<any> {

  try {

    if (conversationId && conversationId.trim() !== '') {

      this.conversationId = conversationId;

    }

    if (!this.conversationId) {

      await this.copilotCreateConversation();

    }

    if (!this.conversationId) {

      throw new Error('Napaka pri ustvarjanju pogovora.');

    }

    const response = await this.graphClient

      .api(`/copilot/conversations/${this.conversationId}/chat`)

      .version('beta')

      .post({

        message: {

          text: prompt

        },

        locationHint: {

          timeZone: Intl.DateTimeFormat().resolvedOptions().timeZone

        }

      });

    let fullResponse = {chatId: this.conversationId, chatResponse: response};

    return fullResponse;

  } catch (error) {

    throw error;

  }

}

V glavni komponenti gradnika je najprej ustvarjen osnovni pogovor, ki prikaže kratke povzetke o najpomembnejših informacijah. Metoda pošlje poziv iz nastavitev gradnika metodi za pošiljanje sporočila, opisani v prejšnjem koraku.

private getWelcomeMessage = async () => {

  let prompt = this.props.prompt;

  try {

    const aiResponse = await this.copilotService.copilotSendMessage(prompt);

    const aiResponseObj = aiResponse.chatResponse;

    if (aiResponseObj && aiResponseObj.messages && aiResponseObj.messages.length > 0) {

      this.setState({

        initialConversation: [aiResponse]

      });

    }

  } catch (error) {}

}

Ko API vrne odgovor se v gradniku lahko prikaže pomembne informacije za tekoči dan.

Zraven posamezne točke je še možnost za pridobitev več informacij, ki kliče novo metodo. Ta metoda najprej preveri ali obstoječi pogovor že obstaja, če obstaja ga prikaže, sicer ustvari nov pogovor, ki razširi temo točke z dodatnimi informacijami in datotekami.

private getExpandedInfo = async (i: any, id?: string) => {

  let existingConversation = this.state.conversations.find(c => c.id === id);

  if (existingConversation && existingConversation.content) {

    this.modalSet(existingConversation);

  } else {

    let conversationId = null;

    let prompt = `Give me detailed information about the following topic: ${i.summary }. If possible focus on the following prompt: ${i.prompt}.`;

    try {

      const aiResponse = await this.copilotService.copilotSendMessage(prompt, conversationId);

      const aiResponseObj = aiResponse.chatResponse;

      if (aiResponseObj && aiResponseObj.messages && aiResponseObj.messages.length > 0) {

        let messageObject = {

          id: id,

          chatId: aiResponse.chatId,

          content: aiResponseObj.messages[1].text,

          fullResponse: aiResponse

        };

        this.setState({

          conversations: [...this.state.conversations, messageObject]

        }, () => this.modalSet(messageObject));

      }

    } catch (error) {}

  }

}

Ko metoda vrne rezultate, jih lahko prikažemo v pojavnem oknu.

Pri posameznih pozivih je pomembno, da mu natančno opredelimo strukturo vrnjenih podatkov. Kadar nameravamo podatke naknadno še prerazporejati, ji najbolje, da nam jih vrne v JSON formatu, če pa jih želimo le prikazati, nam jih lahko vrne v navadnem besedilu, HTML formatu ali markup zapisu. Dostikrat mu je treba tudi specificirati kako naj ravna s premalo informacijami.

Uporaba Graph API-ja za komunikacijo s Copilotom je uporabna, saj lahko tako integriramo pogovore in iskanje direktno na SharePoint stran, znotraj vsebine, ali pa uporabimo kot dodano podporo pri posameznih gradnikih. Ker pa so rezultati odvisni od podatkov in se lahko od primera do primera močno razlikujejo, je treba biti pozoren pri uporabi vrnjenih podatkov in ujeti izjeme, do katerih lahko prihaja. Ker zbira podatke iz celotnega Microsoft 365 okolja, dostikrat odgovori potrebujejo kar nekaj časa preden se dokončno ustvarijo, zato ne moremo pričakovati zelo hitrih odgovorov in rezultatov.

Domen Gričar

Front - end programer, predavatelj

MCT, MS, MCSD

domen.gricar@kompas-xnet.si

Imate dodatna vprašanja?

Za več informacij smo vam vedno z veseljem na voljo. Pišite nam na info@kompas-xnet.si ali nas pokličite 01 5136 990.