Agentin laajentaminen REST-ohjelmointirajapinnan työkaluilla (esikatselu)

[Tämä artikkeli sisältää julkaisua edeltävää materiaalia ja voi muuttua.]

Voit käyttää REST API -ohjelmointirajapintoja (mukaan lukien OpenAI APIa) yhdistääksesi luomasi agentin ulkoisiin järjestelmiin ja käyttääksesi saatavilla olevia tietoja agentissasi. Voit yhdistää agentin REST-ohjelmointirajapintaan tarjoamalla Copilot Studio kolme asiaa:

• OpenAPI-määritys, joka määrittää ohjelmointirajapinnan funktiot ja käytettävissä olevat toiminnot
• Tiedot tarvittavan todennuksen tyypistä ja todennustiedot, joilla käyttäjät voivat muodostaa yhteyden ohjelmointirajapintaan ulkoisen järjestelmän käyttöä varten
• Kuvaukset, joiden avulla kielimalli määrittää, milloin ohjelmointirajapinta käynnistetään tietojen käyttämistä varten

Voit lisätä REST-ohjelmointirajapintoja Copilot agentteihin ja mukautettuihin agentteihin Copilot Studio kautta.

Tärkeää

Tämä artikkeli sisältää Microsoft Copilot Studio esikatseludokumentaatiosta, ja sitä voidaan muuttaa.

Esiversiotoimintoja ei ole tarkoitettu tuotantokäyttöön, ja niiden toiminnot voivat olla rajoitettuja. Nämä toiminnot ovat käytettävissä ennen virallista julkaisua, jotta voit käyttää niitä aikaisessa vaiheessa ja antaa palautetta.

Jos rakennat tuotantovalmista agenttia, katso Microsoft Copilot Studio Yleiskatsaus.

Copilot agenttien avulla tekijä voi yhdistää useita tietolähteitä, kuten yhdistimiä, ohjelmointirajapintoja, kehotteita ja tietolähteitä, yhdeksi agentiksi. Tämän agentin avulla voit laajentaa Microsoft agenttikokemuksia, kuten Microsoft 365 Copilot.

Mukautetut agentit ovat itsenäisiä agentteja, jotka sisältävät yhdistimiä, ohjelmointirajapintoja, kehotteita ja tietolähteitä. Voit käyttää mukautettuja agentteja suoraan integroimalla ne verkkosivustoihin tai muihin kanaviin.

Muistiinpano

Sinun on luotava REST-ohjelmointirajapintatyökalut OpenAPI v2 -määrityksestä. Tämä vaatimus johtuu Power Platformin toiminnasta API-määrityksiä käsiteltäessä. Jos lähetät v3-määrityksen, luontiprosessi kääntää sen automaattisesti v2-määritykseksi.

edellytykset

• tekijätason tunnistetiedot ja Copilot Studio käyttöoikeus.
• Kopio OpenAPI-määrittelystä REST-rajapinnalle, johon haluat yhdistää
• Tieto siitä, millaista tunnistautumista tarvitaan API:n yhdistämiseen, sekä todennustiedot.

Lisää REST API -työkalu agenttiisi

Jos haluat lisätä REST-ohjelmointirajapintatyökalun agenttiisi, suorita seuraavat vaiheet:

1. Lisää uusi agenttityökalu ja valitse REST API
2. Tarjoa API-määrittely, kuvaus ja ratkaisu
3. Anna todennustiedot
4. Valitse työkalut API:sta
5. Arvostelu ja julkaiseminen

Seuraavat osiot opastavat sinua prosessin läpi vaihe vaiheelta.

REST-ohjelmointirajapinnan lisäämisprosessi on sama sekä mukautetuille agenteille että Microsoft 365 Copilot agenteille.

Lisää uusi agenttityökalu ja valitse REST API

1. Mene agenttisi Yleiskatsaus-sivulle.

2. Valitse Työkalut-osiossaLisää työkalu. Voit myös siirtyä Työkalut-välilehteen ja valita Lisää työkalu.

   Näyttöön tulee Lisää työkalu -sivu.

3. Valitse Uusi työkalu>REST-ohjelmointirajapinta.

Tarjoa API-määrittely, kuvaus ja ratkaisu

1. Lataa sen REST-ohjelmointirajapinnan OpenAPI-määritystiedosto, johon haluat muodostaa yhteyden. Voit joko vetää ja pudottaa määritystiedoston Lataa REST API -näyttöön tai selata järjestelmääsi löytääksesi tiedoston, jota haluat käyttää.

   

   Muistiinpano

   OpenAPI-määrityksen on oltava JSON-tiedosto v2-muodossa. Jos lähetät v3-määrityksen, luontiprosessi kääntää sen automaattisesti v2-määritykseksi.

   Kun olet ladannut määrityksen, näyttö päivittyy näyttämään määrityksen tiedostonimen ja tiedot.

   

   Seuraavissa vaiheissa menettely käyttää tiettyä esimerkkiä SunnyADO: sta, joka on ADO-lipunhallintajärjestelmä. Esimerkissä tarkoituksena on antaa käyttäjille mahdollisuus hakea ja päivittää tukipyyntönsä agentin kautta.

2. Tarkista tiedot ja valitse sitten Seuraava.

   Näkyviin tulee Ohjelmointirajapintalaajennuksen tiedot -sivu, jolla voit antaa lisätietoja ohjelmointirajapinnasta.

   

   Kuvauskenttä täytetään aluksi palveluun lataamasi ohjelmointirajapintamäärityksen kuvauksen perusteella. Anna tarkka kuvaus, koska agentin orkestrointi määrittää kuvauksen avulla, milloin kyseistä työkalua kannattaa käyttää. Anna lisätietoja, kuten synonyymeja, jotka auttavat agenttia valintaprosessissa.

   Alkuperäinen kuvaus voi esimerkiksi olla "Yksinkertainen palvelu palvelupyyntöjen hallintaa varten".

   Parempi kuvaus on "Järjestelmä, jolla noudetaan, etsitään ja näytetään olemassa olevia palvelupyyntöjä SunnyADO:sta. Sen avulla käyttäjät voivat päivittää, muuttaa ja hallita palvelupyyntöjä tarjotakseen enemmän tietoja tietueiden parantamiseksi."

3. Syötä parannettu kuvaus Kuvaus-kenttään.

4. Ratkaisu-kohdan avattavissa luetteloissa ovat kaikki kulloisessakin ympäristössä käytettävissä olevat ratkaisut. Valitse käytettävä ratkaisu. Lue lisätietoja ratkaisujen ratkaisukonsepteista.

   

   Jos kyse on ensisijaisesta ratkaisusta tai valittu yhdistin on jo ratkaisussa, kyseinen ratkaisu valitaan automaattisesti.

   Voit joko valita ratkaisun tai jättää sen tyhjäksi. Jos jätät ratkaisun tyhjäksi, sinulle luodaan ratkaisu, jolla on toiminnon nimi ja oletusjulkaisija. Toiminnon tallentaminen ratkaisuun mahdollistaa sen vaivattoman siirtämisen ympäristöjen välillä.

   Muistiinpano

   Jos et näe tässä tapauksessa oletusratkaisua tai CDS-oletusratkaisua vaihtoehtona, lisää mukautettu ratkaisu, joka helpottaa hallintaa. Lisätietoja on artikkelissa Oletusratkaisu verrattuna mukautettuun ratkaisuun.

5. Kun ratkaisu on valittuna, jatka valitsemalla Seuraava .

Anna todennustiedot

Näkyviin tulee Todennus-sivu . Valitse ohjelmointirajapinnalle käytettävä todennustyyppi.

1. Valitse todennustapa luettelosta. Valitse kolmesta vaihtoehdosta:

   • Ei mitään: API:n käyttämiseen ei tarvita todennustodistusta.
   • API-avain: Valitse tämä vaihtoehto, jos API:si vaatii API-avaimen todennukseen. Ajonaikaisesti, kun agentti haluaa käyttää API-työkalua, agentti pyytää käyttäjää tunnistautumaan. Käyttäjä antaa API-avaimen, ja agentti yhdistää API:n tämän avaimen avulla.
   • Auth 2.0: Valitse tämä vaihtoehto, jos MCP-palvelimesi käyttää OAuth 2.0:aa todennukseen. OAuth 2.0 antaa yksittäisille käyttäjille mahdollisuuden tunnistautua API:lle identiteettipalveluntarjoajan kautta. Tämän todennusmenetelmän avulla käyttäjä voi myöntää käyttöoikeudet sovelluksellesi (agentille) jakamatta tunnistetietojaan agentille.

2. Syötä vaaditut kentät valitulle todennusmenetelmälle. Kentät vaihtelevat todennusmenetelmän mukaan.

   • Ei mitään: Ei tietoa annettavana.
   • Ohjelmointirajapinta-avain:
     • Parametritarra: Tekstitunniste, jonka API-parametri esittää käyttäjille.
     • Parametrin nimi: Ohjelmointirajapinnan avainparametrin todellinen nimi, jota käytetään joko otsikossa tai kyselymerkkijonossa.
     • Parametrin sijainti: Miten lähetät avaimen ohjelmointirajapinnalle. Valitse joko Otsikko tai Kysely.
   • Todennus 2.0:
     • Asiakastunnus: Asiakastunnus tunnistaa tunnistetietopalvelun ongelmat, kun rekisteröit sovelluksesi. Asiakastunnuksen avulla tunnistetietopalvelu tietää, mikä sovellus tekee pyynnön.
     • Asiakassalasana: Asiakassalasana, jonka tunnistepalvelun tarjoaja myöntää kun rekisteröit sovelluksesi. Agenttisi lähettää asiakassalaisuuden ja asiakastunnuksen todistaakseen, että agenttisi on valtuutettu pyytämään käyttöoikeustietueita MCP-palvelimelle.
     • Valtuutuksen URL: Tunnistetietopalvelun päätepiste, jossa agenttisi ohjaa käyttäjän kirjautumaan sisään ja myöntämään käyttöoikeudet agentillesi (suostumuskortti, joka esitetään agenttikeskustelussa). Käyttäjä todentaa tässä ja sitten tunnistetietopalvelu vastaa takaisin agentille takaisinkutsun URL-osoitteessavaltuutuskoodilla.
     • Token URL: Päätepiste, jossa agenttisi vaihtaa valtuutuskoodin (tai refresh-tokenin) pääsytunnukseen ja refresh-tokeniin. Käyttöoikeustietue antaa agenttisi käyttää MCP-palvelinta käyttäjän puolesta. Päivitystunnusten avulla agenttisi voi saada uudet käyttöoikeudet ja päivitystunnukset päivityksen päätepisteestä, kun aiempi käyttöoikeustietue vanhenee.
     • Päivitä URL-osoite: Päätepiste, jolla pyydetään uutta käyttöoikeustietuetta päivitystunnuksen avulla (jotta käyttäjän ei tarvitse kirjautua sisään uudelleen tunnuksen vanhentuessa).
     • Scope: (Valinnainen): Käyttöoikeudet, joita sovelluksesi pyytää, välilyöntilistana.
     • Which Microsoft 365 organisaatio käyttää päätepisteitä: Tämä asetus rajoittaa lähteen käytön joko tekijän organisaatiolle tai kaikille organisaatioille. Valitse jompiku:
       • Vain minun organisaationi
       • Mitkä tahansa Microsoft 365 -organisaatiot
     • Mikä sovellus (asiakas) voi käyttää päätelaitteita: GUID, joka määrittelee asiakasjärjestelmän, jolla voidaan käyttää datan käyttöä. Sovellukset voivat sisältää Microsoft 365, Power Automate ja muita vaihtoehtoja.

3. Kun olet suorittanut kaikki kentät, valitse Seuraava.

   Työkalun valitseminen ja määrittäminen -sivulla voit valita käyttöön otettavat työkalut ohjelmointirajapinnasta.

   

Valitse työkalut API:sta

Valitse REST API:n API-tukemat työkalut lisätääksesi ne agenttiisi. Yleisesti ottaen REST-rajapinta tarjoaa erilaisia työkaluja API:n määrittelyssä määriteltyjen päätepiste- ja HTTP-metodien (get, put, post, delete jne.) yhdistelmän kautta. Joissakin tapauksissa et ehkä halua, että agentin käyttäjät pystyvät suorittamaan kaikkia ohjelmointirajapinnan yleensä tarjoamia toimintoja. Esimerkiksi API-määrittelysi saattaa sisältää mahdollisuuden päivittää ja poistaa, mutta haluat vain agentin käyttäjien pystyvän luomaan tietueita.

1. Valitse luettelosta määritettävä työkalu.

   Asetus työkalusi -sivu näkyy.

   

2. Määritä valitun työkalun nimi ja kuvaus. Anna yleisen ohjelmointirajapinnan tapaan työkalun nimi ja työkalun kuvaus. Kuvaukset täytetään aluksi valmiiksi ohjelmointirajapinnan määrityksen kuvausten perusteella. Nimen ei tarvitse olla yksilöllinen, mutta sen tulisi edustaa itse työkalua. Kuvauksen, kuten koko API-kuvauksen, tulisi olla riittävän tarkka, jotta kielimalli saa yksityiskohtia, jotta voidaan paremmin tunnistaa, vastaako kyselysi juuri tätä työkalua.

3. Kun kentät on täytetty, valitse Seuraava.

   Työkalun parametrien tarkastelu -sivu tulee näkyviin.

   

   Tämä sivu näyttää syötteen odotetut arvot ja palautetut tulosarvot. Et voi muuttaa näitä arvoja, mutta voit päivittää syötteiden ja tulosten kuvaukset. Kaikki tämän sivun sisältö noudetaan suoraan ladatusta ohjelmointirajapinnan määrityksestä.

4. Päivitä kuvaukset tarpeen mukaan. Kuvauksissa määritellään, mihin arvoja käytetään. Jos jokin kuvauksista on tyhjä, sinun on täytettävä ne, ennen kuin voit siirtyä eteenpäin. Voit liittää nimen, jos sinulla ei ole parempaa kuvausta.

5. Kun olet saanut kuvaukset valmiiksi, valitse Seuraava.

   Ensimmäinen työkalu on nyt määritetty, ja se näkyy Valittujen työkalujen luettelossa Valitse ja määritä laajennustyökalu - sivulla.

   

6. Lisää ohjelmointirajapinnasta kaikki muut työkalut, jotka haluat sisällyttää tällä hetkellä. Kun olet lisännyt työkalut, joita haluat agenttisi tukevan, valitse Seuraava.

   Tarkista työkalusi -sivu tulee näkyviin. Sivu sisältää määritetyn REST-ohjelmointirajapintatyökalun tiedot.

   

Arvostelu ja julkaiseminen

1. Jos sinun on tehtävä päivityksiä, valitse Takaisin ja tee haluamasi muutokset. Valitse muussa tapauksessa Seuraava.

   Näyttöön tulee näyttö, joka ilmaisee, että työkalu on julkaistu prosessin aikana. Saat ilmoituksen, kun julkaisu on valmis.

2. Valitse Luo yhteys jatkaaksesi. Sinut palautetaan Lisää työkalun näyttöön.

3. Valitse REST API työkalutyyppivalitsimesta. Voit nähdä uudet työkalut API:n kautta. Jokaiselle API:n kautta lisäämälle työkalulle pitäisi olla yksi merkintä.

4. Luo tai valitse kullekin ohjelmointirajapinnan äskettäin määritetylle työkalulle yhteys ohjelmointirajapintaan ja lisää työkalu agentillesi:

   1. Lisää työkalu -näytöllä valitse työkalu.
   2. Connection -kohdasta valitse olemassa oleva yhteys tai valitse Luo uusi yhteys.
   3. Anna yhteyden edellyttämät tiedot ja luo yhteys työkaluun valitsemalla Luo .
   4. Valitse Lisää ja määritä lisätäksesi työkalun agentillesi.

   

REST API:n työkalut ovat nyt käytettävissä agentissasi.

Vinkki

Löydät työkalusi helpommin käyttämällä hakupalkkia sen paikantamiseen.