Agentin laajentaminen REST-ohjelmointirajapinnan työkaluilla (esikatselu)

Muistio

Tässä artikkelissa kuvataan ominaisuuksia, joita käytetään agenteissa tai agenttivirroissa, joita käytetään standardivaljastuksen voimalla.

[Tämä artikkeli on esijulkaisuasiakirja, ja se voi muuttua.]

Käytä REST-rajapintoja (mukaan lukien OpenAI API) yhdistääksesi luomasi agentin ulkoisiin järjestelmiin ja käyttämään saatavilla olevaa dataa agentissasi. Yhdistä agenttisi REST-rajapintaan tarjoamalla Copilot Studio:lle 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

Lisää REST-rajapintoja Copilot-agentteihin ja räätälöityihin agentteihin Copilot Studio:n kautta.

Important

Tämä artikkeli sisältää Microsoft Copilot Studion esiversiota koskevia ohjeita. Tiedot voivat muuttua.

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 olet luomassa tuotantovalmista agenttia, katso lisätietoja kohdasta Microsoft Copilot Studion yleiskuvaus.

Copilot agenttien avulla tekijä voi yhdistää useita tietolähteitä, kuten yhdistimiä, ohjelmointirajapintoja, kehotteita ja tietolähteitä, yhdeksi agentiksi. Käytä tätä agenttia laajentaaksesi Microsoft-brändättyjä agenttikokemuksia, kuten Microsoft 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.

Muistio

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-rajapinnan lisäämisprosessi on sama sekä mukautetuille agenteille että Microsoft 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.

   Lisää työkalusivu näkyy.

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 raahata ja pudottaa määrittelytiedoston Upload a REST API -näyttöön tai selata järjestelmääsi löytääksesi haluamasi tiedoston.

   

   Muistio

   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ää tikettinsä agentin kautta.

2. Tarkista tiedot ja valitse sitten Seuraava.

   Sinulle esitetään API-lisäosan yksityiskohdat , josta voit antaa lisätietoja API:sta.

   

   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, järjestelmä luo sinulle ratkaisun toiminnon nimellä ja oletusjulkaisijalla. Toiminnon tallentaminen ratkaisuun mahdollistaa sen vaivattoman siirtämisen ympäristöjen välillä.

   Muistio

   Jos et näe oletusratkaisua tai oletusratkaisua vaihtoehtona tässä tapauksessa, lisää mukautettu ratkaisu helpon hallinnan vuoksi. 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. Vaihtoehtoja on kolme:

   • 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.

   Määritä 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.

   Tarkista työkalusi parametrit -sivulla näkyy.

   

   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. Tarvittaessa päivitä kuvaukset. 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. Liitä nimi mukaan, jos sinulla ei ole parempaa kuvausta.

5. Kun olet suorittanut kuvaukset, 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 näkyy. 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.