Uw agent uitbreiden met hulpprogramma's van een REST API (preview)

[Dit artikel maakt deel uit van de voorlopige documentatie en kan nog veranderen.]

U kunt REST API's (inclusief OpenAI API) gebruiken om een door u gemaakte agent te verbinden met externe systemen en toegang te krijgen tot beschikbare gegevens voor gebruik binnen uw agent. U kunt uw agent verbinden met een REST API door drie dingen op te geven in Copilot Studio:

• Een OpenAPI-specificatie die de functies en beschikbare acties van de API definieert
• Details over het type verificatie dat nodig is en de verificatiegegevens voor gebruikers om verbinding te maken met de API om toegang te krijgen tot het externe systeem
• Beschrijvingen om het taalmodel te helpen bepalen wanneer de API moet worden aangeroepen om de gegevens te gebruiken

REST API's kunnen aan Copilot- en aangepaste agenten worden toegevoegd via Copilot Studio.

Belangrijk

Dit artikel bevat documentatie voor de preview van Microsoft Copilot Studio en kan nog veranderen.

Preview-functies zijn niet bedoeld voor productiegebruik en hebben mogelijk beperkte functionaliteit. Deze functies zijn beschikbaar voor een officiële release zodat u vroeg toegang kunt krijgen en feedback kunt geven.

Zie Overzicht van Microsoft Copilot Studio als u een productieklare agent aan het bouwen bent.

Met Copilot-agenten kan een maker meerdere gegevensbronnen, zoals connectoren, API's, prompts en kennisbronnen, combineren in één agent. U kunt deze agent gebruiken om Microsoft-agentervaringen, zoals Microsoft 365 Copilot, uit te breiden.

Aangepaste agenten zijn zelfstandige agenten die connectoren, API's, prompts en kennisbronnen bevatten. U kunt aangepaste agenten direct gebruiken door ze te integreren in websites of andere kanalen.

Notitie

REST API-hulpprogramma's moeten worden gemaakt op basis van een OpenAPI v2-specificatie. Deze vereiste is het gevolg van het gedrag van Power Platform bij het verwerken van API-specificaties. Als er een v3-specificatie wordt ingediend, wordt deze tijdens het aanmaakproces automatisch vertaald naar een v2-specificatie.

Voorwaarden

• Maker-level credentials en een Copilot Studio-licentie.
• Een kopie van de OpenAPI-specificatie voor de REST API waarmee je wilt verbinden
• Kennis van het type authenticatie dat nodig is om verbinding te maken met de API, en de authenticatiedetails.

Voeg een REST API-tool toe aan je agent

Het toevoegen van een REST API-tool aan je agent omvat een paar stappen:

1. Voeg een nieuwe agenttool toe en selecteer REST API
2. Bied API-specificatie, beschrijving en oplossing
3. Geef authenticatiegegevens
4. Selecteer tools uit de API
5. Beoordelen en publiceren

De volgende secties leiden je stap voor stap door het proces.

Het proces om een REST API toe te voegen is identiek voor zowel custom agents als agents voor Microsoft 365 Copilot.

Voeg de nieuwe agent-tool toe en selecteer de REST API

1. Ga naar de Overzichtspagina van je makelaar.

2. Selecteer het hulpmiddel Toevoegen in de sectie Extra. U kunt ook naar het tabblad Extra gaan en een hulpprogramma toevoegen selecteren.

   De pagina Hulpprogramma toevoegen wordt weergegeven.

3. Selecteerde REST API>.

API-specificatie, beschrijving en oplossing opgeven

1. Upload een OpenAPI-specificatiebestand voor de REST API waarmee u verbinding wilt maken. U kunt het specificatiebestand naar het scherm Een REST API uploaden slepen en neerzetten of door uw systeem bladeren om het bestand te vinden dat u wilt gebruiken.

   

   Notitie

   De OpenAPI-specificatie moet een JSON-bestand in v2-indeling zijn. Als er een v3-specificatie wordt ingediend, wordt deze tijdens het aanmaakproces automatisch vertaald naar een v2-specificatie.

   Nadat u de specificatie hebt geüpload, wordt het scherm bijgewerkt met de bestandsnaam van de specificatie en de details.

   

   In de volgende stappen baseren we de procedure op een specifiek voorbeeld van SunnyADO, een ADO-ticketbeheersysteem. In het voorbeeld is het de bedoeling dat gebruikers hun tickets kunnen ophalen en bijwerken via de agent.

2. Controleer de gegevens en selecteer Volgende.

   U krijgt een pagina met details over API-invoegtoepassingen te zien, waar u aanvullende informatie over de API kunt opgeven.

   

   Het beschrijvingsveld wordt in eerste instantie ingevuld op basis van de beschrijving in de API-specificatie die u hebt geüpload. Geef een gedetailleerde beschrijving op, omdat uw agentindeling gebruikmaakt van de beschrijving om te bepalen wanneer het specifieke hulpprogramma moet worden gebruikt. Geef details, inclusief synoniemen, om uw agent te helpen bij het selectieproces.

   De initiële beschrijving die wordt gegeven, is bijvoorbeeld: 'Een eenvoudige service om tickets te beheren.'

   Een betere omschrijving is: "Een systeem waarmee u bestaande tickets van SunnyADO kunt ophalen, vinden en weergeven." Hiermee kunnen gebruikers tickets bijwerken, wijzigen en beheren om meer gegevens te verstrekken en zo de registratie te verbeteren.

3. Voer een verbeterde beschrijving in het veld Beschrijving in.

4. In een vervolgkeuzelijst onder Oplossing worden alle oplossingen weergegeven die beschikbaar zijn in de huidige omgeving. Selecteer de oplossing die u wilt gebruiken. Zie voor meer informatie over wat oplossingen zijn Oplossingsconcepten.

   

   Als u een voorkeursoplossing hebt of als de door u geselecteerde connector al in de oplossing voorkomt, wordt die oplossing automatisch geselecteerd.

   U kunt een oplossing selecteren of deze optie leeg laten. Als u de oplossing leeg laat, wordt er een oplossing voor u gemaakt met de actienaam en de standaarduitgever. Door uw actie in een oplossing op te slaan, kunt u deze gemakkelijk tussen omgevingen verplaatsen.

   Notitie

   Als u in dit geval de standaardoplossing of de CDS-standaardoplossing niet als optie ziet, raden wij u aan een aangepaste oplossing te gebruiken voor eenvoudig beheer. Voor meer informatie, zie: Standaardoplossing vs. aangepaste oplossing.

5. Selecteer een oplossing en klik op Volgende om door te gaan.

Verificatiedetails toevoegen

De pagina Verificatie wordt weergegeven, waar u kunt selecteren welk type verificatie u voor de API wilt gebruiken.

1. Selecteer een verificatiemethode in de lijst. Er zijn drie opties:

   • Geen: Er is geen authenticatie nodig om toegang te krijgen tot de API.
   • API-sleutel: Kies deze optie als je API een API-sleutel vereist voor authenticatie. Tijdens runtime, wanneer de agent de API-tool wil gebruiken, vraagt de agent de gebruiker om te authenticeren. De gebruiker levert een API-sleutel en de agent maakt verbinding met de API via die sleutel.
   • Auth 2.0: Selecteer deze optie als je MCP-server OAuth 2.0 gebruikt voor authenticatie. OAuth 2.0 stelt individuele gebruikers in staat zich via een identiteitsprovider te authenticeren bij de API. Dit stelt de gebruiker in staat om rechten te verlenen aan je applicatie (agent) zonder hun inloggegevens met de agent te delen.

2. Voer de vereiste velden in voor de geselecteerde authenticatiemethode. De velden variëren afhankelijk van de verificatiemethode.

   • Geen: Geen informatie om te geven.
   • API-sleutel:
     • Parameterlabel: Een tekstlabel voor de API-parameter om aan gebruikers te presenteren.
     • Parameternaam: De daadwerkelijke naam van de API-sleutelparameter die gebruikt moet worden in de header of querystring.
     • Parameterlocatie: Hoe je de sleutel voor de API moet sturen. Selecteer ofwel Header of Query.
   • Authenticatie 2.0:
     • Client ID: de client-ID die de identiteitsprovider aanmaakt wanneer u uw app registreert. Met de client-id weet de id-provider welke app de aanvraag doet.
     • Clientgeheim: het clientgeheim dat de id-provider uitgeeft wanneer u uw app registreert. Uw agent verzendt het clientgeheim samen met de client-id om te bewijzen dat uw agent gemachtigd is om toegangstokens aan te vragen voor de MCP-server.
     • Autorisatie-URL: het eindpunt van de id-provider waar uw agent de gebruiker omleidt om zich aan te melden en machtigingen te verlenen aan uw agent (toestemmingskaart die wordt weergegeven in de agentchat). De gebruiker verifieert zich hier en vervolgens reageert de id-provider terug naar de agent op de callback-URL met een autorisatiecode.
     • Token URL: Het eindpunt waar je agent de autorisatiecode (of refresh token) uitwisselt voor een access token en refresh token. Met het toegangstoken kan uw agent de MCP-server namens de gebruiker gebruiken. Met vernieuwingstokens krijgt uw agent nieuwe toegangs- en vernieuwingstokens van het vernieuwingseindpunt, wanneer het vorige toegangstoken verloopt.
     • Vernieuwings-URL: het eindpunt om een nieuw toegangstoken aan te vragen met behulp van een vernieuwingstoken (zodat de gebruiker zich niet opnieuw hoeft aan te melden wanneer het token verloopt).
     • Scope: (Optioneel): De rechten waar je app om vraagt, als een ruimtegescheiden lijst.
     • Welke Microsoft 365-organisatie toegang krijgt tot de endpoints: Dit beperkt de toegang tot de broncode tot ofwel de organisatie van de maker, of alle organisaties. Selecteer een van de volgende opties:
       • Alleen mijn organisatie
       • Alle Microsoft 365-organisaties
     • Welke app (client) kan de eindpunten gebruiken: GUID die het clientsysteem definieert dat gebruikt kan worden om deze data te benaderen. Apps kunnen Microsoft 365, Power Automate en andere opties bevatten.

3. Zodra alle velden zijn ingevuld, selecteert u Volgende.

   Je krijgt een select-en-configureer-pagina te zien waarop je tools kunt selecteren die je via de API wilt inschakelen.

   

Selecteer tools uit de API

Selecteer de door de API ondersteunde tools uit de REST API om aan je agent toe te voegen. Over het algemeen biedt een REST-API een reeks tools via de verschillende combinaties van endpoint- en HTTP-methoden (get, put, post, delete, enzovoort) zoals gedefinieerd in de API-specificatie. In sommige gevallen wilt u misschien niet dat de gebruikers van de agent elke actie kunnen uitvoeren die de API doorgaans biedt. Bijvoorbeeld, je API-specificatie kan de mogelijkheid bevatten om te updaten en te verwijderen, maar je wilt alleen dat gebruikers van je agent records kunnen aanmaken.

1. Selecteer een hulpprogramma in de lijst die u wilt configureren.

   De pagina 'Je tool configureren ' wordt weergegeven.

   

2. Configureer de naam en beschrijving van de geselecteerde tool. Net als bij de algemene API wordt je gevraagd een toolnaam en toolbeschrijving te geven. Beschrijvingen worden in eerste instantie ingevuld op basis van de beschrijvingen in de API-specificatie. De naam hoeft niet uniek te zijn, maar moet het hulpprogramma zelf vertegenwoordigen. De beschrijving, net als de algemene API-beschrijving, moet specifiek genoeg zijn om het taalmodel details te geven om beter te bepalen of je query aansluit bij deze specifieke tool.

3. Zodra u de velden hebt ingevuld, selecteert u Volgende.

   De pagina Parameters van uw hulpprogramma controleren wordt weergegeven.

   

   Deze pagina toont de verwachte waarden voor input en de outputwaarden die worden teruggegeven. Je kunt deze waarden niet veranderen, maar je kunt wel de beschrijvingen van de inputs en outputs bijwerken. Alle inhoud op deze pagina wordt rechtstreeks uit de geüploade API-specificatie gehaald.

4. Werk de beschrijvingen bij indien nodig. De beschrijvingen geven aan waarvoor de waarden worden gebruikt. Als er nog geen beschrijvingen zijn ingevuld, moet u deze eerst invullen voordat u verder kunt gaan. Als u geen betere beschrijving hebt, kunt u de naam plakken.

5. Nadat u de beschrijvingen hebt voltooid, selecteert u Volgende.

   Het eerste hulpprogramma is nu geconfigureerd en wordt weergegeven in de lijst met geselecteerde hulpprogramma's op de pagina Hulpprogramma voor invoegtoepassing selecteren en configureren .

   

6. Voeg op dit moment alle andere tools uit de API toe die je wilt toevoegen. Zodra u klaar bent met het toevoegen van hulpprogramma's die uw agent moet ondersteunen, selecteert u Volgende.

   De pagina Uw hulpprogramma controleren wordt weergegeven. De pagina bevat de details van het geconfigureerde REST API-hulpprogramma.

   

Beoordelen en publiceren

1. Als u wijzigingen wilt aanbrengen, kunt u Terug selecteren en uw wijzigingen aanbrengen. Anders selecteert u Volgende.

   Er wordt een scherm weergegeven dat aangeeft dat uw hulpprogramma wordt gepubliceerd terwijl het proces wordt voltooid. U wordt op de hoogte gebracht zodra de publicatie is voltooid.

2. Selecteer Verbinding aanmaken om verder te gaan. Je wordt teruggebracht naar het scherm 'Gereedschap toevoegen '.

3. Selecteer REST API in de tooltype-selector. Je kunt de nieuw gemaakte tools zien via je API. Er zou één invoer per tool moeten zijn die je via de API hebt toegevoegd.

4. Voor elk van de nieuw geconfigureerde tools vanuit de API moet je een verbinding met de API maken of selecteren en de tool toevoegen aan je agent:

   1. Selecteer op het scherm 'Gereedschap toevoegen ' het gereedschap.
   2. Selecteer onder Verbinding een bestaande verbinding of kies voor Nieuwe verbinding aanmaken.
   3. Voer alle benodigde informatie in voor de verbinding en selecteer vervolgens Create om de verbinding met de tool te maken.
   4. Selecteer Add en configure om de tool aan je agent toe te voegen.

   

De tools van de REST API zijn nu beschikbaar voor gebruik in je agent.

Tip

Gebruik de zoekbalk om het hulpprogramma gemakkelijker te vinden.