Breid uw agent uit met acties vanuit een REST API (preview)

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 worden toegevoegd aan Copilot-agenten en aangepaste agenten via Copilot Studio.

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 de ervaringen van Microsoft-agents uit te breiden, zoals Microsoft 365 Copilot.

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

API-acties 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 de API-specificaties. Als er een v3-specificatie wordt ingediend, wordt deze tijdens het aanmaakproces automatisch vertaald naar een v2-specificatie.

Voorwaarden

Er is een aantal vereisten nodig om de Microsoft-gemerkte agentervaringen met connectoracties uit te breiden.

Voor alle agent-ervaringstypen moet u over referenties op makerniveau en een Copilot Studio-licentie beschikken.

U hebt ook een kopie van de OpenAPI-specificatie nodig, kennis van het verificatietype dat nodig is en de verificatiegegevens.

Een REST API-actie toevoegen aan een agent

Het toevoegen van een REST API aan uw agent omvat een paar stappen. In de volgende secties wordt het proces doorlopen.

Het proces om een REST API toe te voegen is identiek voor aangepaste en Copilot-agenten.

Het proces bestaat uit een aantal stappen.

Een actie toevoegen aan de agent

1. Begin op de pagina Overzicht van uw agent.

   

2. Selecteer Actie toevoegen in de sectie Acties. U kunt ook naar het tabblad Acties gaan en Actie toevoegen selecteren.

   

   De wizard voor het maken van acties wordt gestart en de pagina Een actie kiezen wordt weergegeven.

API-specificatie, beschrijving en oplossing opgeven

1. Selecteer Een API toevoegen voor een aangepaste connector onder aan de pagina.

   

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

3. 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, omdat uw agentorkestratie de beschrijving gebruikt om te bepalen wanneer de specifieke actie 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.

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

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

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

Notitie

Momenteel zijn de beschikbare opties Geen, Auth 2.0 en API.

1. Selecteer een verificatiemethode in de lijst.

2. Vul de vereiste velden in voor de verificatiemethode. De velden variëren afhankelijk van de verificatiemethode.

   • Geen: er zijn geen andere velden verplicht.
   • API-sleutel:
     • Parameterlabel: een tekstlabel voor de API-parameter.
     • Parameternaam: een tekstnaam voor de API-parameter.
     • Parameterlocatie: de positie waar de parameter kan worden gevonden.
   • Auth 2.0:
     • Client-id: client-GUID voor de doelservice.
     • Clientgeheim – Geheime waarde voor de client. Het geheim wordt niet weergegeven wanneer de gebruiker daarna het bewerkingspaneel opent. Bewaar het geheim wel goed, want u heeft het nodig als u later nog wijzigingen wilt aanbrengen.
     • Autorisatie-URL: URL die wordt gebruikt om het bronsysteem te autoriseren.
     • Token-URL: URL waar het token kan worden opgehaald.
     • Vernieuwings-URL: naar welke URL wordt u doorgestuurd in een vernieuwingsscenario?
     • Bereik: de bereik-URL die is toegewezen aan de API voor Microsoft Entra-apps.
     • Welke Microsoft 365-organisatie heeft toegang tot de eindpunten: hiermee wordt de toegang tot de bron beperkt tot de organisatie van de maker of tot alle organisaties.
     • Welke app (client) kan de eindpunten gebruiken: GUID die het clientsysteem definieert dat kan worden gebruikt om toegang te krijgen tot deze gegevens. Apps kunnen Microsoft 365, Power Automate en andere opties bevatten.

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

   U krijgt een pagina Uw invoegtoepassingsactie selecteren en configureren te zien, waar u acties kunt selecteren die u voor de API wilt inschakelen.

   

Acties selecteren voor de API

Kies de door API ondersteunde acties die u wilt inschakelen. Over het algemeen biedt een REST API een reeks acties via de verschillende combinaties van eindpunt en HTTP-methode (get, put, post, delete enzovoort) die in de API-specificatie zijn gedefinieerd. In sommige gevallen wilt u misschien niet dat de gebruikers van de agent elke actie kunnen uitvoeren die de API doorgaans biedt. Bijvoorbeeld, uw API-specificatie kan acties voor bijwerken en verwijderen bevatten, maar u wilt dat alleen gebruikers van uw agent records kunnen maken.

1. Selecteer een actie in de lijst om te configureren.

   De pagina Uw invoegtoepassingsactie configureren wordt weergegeven.

   

2. Configureer de geselecteerde actie. Net als bij de algemene API wordt u gevraagd een Actienaam en Actiebeschrijving op 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 wel de actie zelf weergeven. De beschrijving moet, net als de algemene API-beschrijving, specifiek genoeg zijn om het taalmodel te voorzien van details waarmee beter kan worden vastgesteld of uw query bij deze specifieke actie past.

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

   De pagina Parameters van uw actie controleren wordt weergegeven.

   

   Op deze pagina worden de waarden weergegeven die als onderdeel van de mogelijke invoer- en uitvoerwaarden worden opgegeven. Deze waarden kunnen niet worden gewijzigd. De beschrijvingen van de invoer en uitvoer kunnen echter wel worden bijgewerkt. Alle inhoud op deze pagina wordt rechtstreeks uit de geüploade API-specificatie gehaald.

4. Vul indien nodig waarden in voor de beschrijvingen. 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.

   De eerste actie is nu geconfigureerd en verschijnt in de lijst met Geselecteerde acties op de pagina Uw invoegtoepassingsactie selecteren en configureren.

   

6. Voeg eventuele andere acties toe die u op dit moment wilt opnemen. Zodra u klaar bent met het toevoegen van acties die u wilt dat uw agent ondersteunt, selecteert u Volgende.

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

   

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 waarin wordt aangegeven dat uw actie wordt gepubliceerd terwijl het proces wordt voltooid. U wordt op de hoogte gebracht zodra de publicatie is voltooid.

2. Nadat het publiceren is voltooid, keert u terug naar het scherm Een actie kiezen. Hier kunt u de nieuw geconfigureerde REST API toevoegen aan uw Copilot-agent of aangepaste agent en de configuratie van het onderdeel voltooien.

   

De REST API-actie is nu beschikbaar voor gebruik in uw agent.

Tip

Om uw actie gemakkelijker te vinden, kunt u de zoekbalk gebruiken.