Utöka din agent med verktyg från ett REST API (förhandsversion)

[Den här artikeln är en förhandsversion av dokumentationen och kan ändras.]

Du kan använda REST-API:er (inklusive OpenAI API) för att ansluta en agent som du skapar till externa system och få tillgång till tillgängliga data för användning i din agent. Du kan ansluta din agent till ett REST API genom att tillhandahålla Copilot Studio med tre saker:

• En OpenAPI-specifikation som definierar API:ets funktioner och tillgängliga åtgärder
• Information om vilken typ av autentisering som behövs och autentiseringsinformation för användare som ska ansluta till API:et för att få åtkomst till det externa systemet
• Beskrivningar som hjälper språkmodellen att avgöra när API:et ska anropas för att använda data

REST-API:er kan läggas till i Copilot agenter och anpassade agenter via Copilot Studio.

Copilot agenter gör det möjligt för en tillverkare att kombinera flera datakällor som anslutningsappar, API:er, uppmaningar och kunskapskällor till en enda agent. Du kan använda den här agenten för att utöka Microsoft-märkta agentupplevelser som Microsoft 365 Copilot.

Anpassade agenter är fristående agenter som innehåller anslutningsprogram, API:er, prompter och kunskapskällor. Du kan använda anpassade agenter direkt genom att integrera dem på webbplatser eller andra kanaler.

Förutsättningar

• Autentiseringsuppgifter på maker-nivå och en Copilot Studio-licens.
• En kopia av OpenAPI-specifikationen för det REST API du vill ansluta till
• Kunskap om vilken typ av autentisering som behövs för att ansluta till API:et, samt autentiseringsdetaljerna.

Lägg till ett REST API-verktyg i din agent

Att lägga till ett REST API-verktyg i din agent innebär några steg:

1. Lägg till ett nytt agentverktyg och välj REST API
2. Tillhandahålla API-specifikation, beskrivning och lösning
3. Ange autentiseringsuppgifter
4. Välj verktyg från API:et
5. Granska och publicera

Följande avsnitt guidar dig genom processen, steg för steg.

Processen för att lägga till ett REST-API är identisk för både anpassade agenter och agenter för Microsoft 365 Copilot.

Lägg till ett verktyg för ny agent och välj REST API

1. Gå till din mäklares översiktssida .

2. I avsnittet Verktyg väljer du Lägg till verktyg. Du kan också gå till fliken Verktyg och välja Lägg till ett verktyg.

   Sidan Lägg till verktyg visas.

3. Välj RESTAPI>.

Tillhandahålla API-specifikation, beskrivning och lösning

1. Ladda upp en OpenAPI-specifikationsfil för den REST API som du vill ansluta till. Du kan antingen dra och släppa specifikationsfilen på skärmen Ladda upp ett REST API eller bläddra i systemet för att hitta filen du vill använda.

   

   Obs

   OpenAPI-specifikationen måste vara en JSON-fil i v2-format. Om en v3-specifikation skickas översätts den automatiskt till en v2-specifikation när den skapas.

   När du har laddat upp specifikationen uppdateras skärmen för att ange specifikationsfilens namn och detaljer.

   

   I stegen som följer grundar vi proceduren i ett specifikt exempel på SunnyADO, ett ADO-biljetthanteringssystem. I exemplet är avsikten att tillåta användarna att hämta och uppdatera sina ärenden via agenten.

2. Kontrollera uppgifterna och välj sedan Nästa.

   Du får sidan information för API-plugin-program där du kan ange ytterligare information om API:et.

   

   Beskrivningsfältet fylls initialt i baserat på beskrivningen i API-specifikationen som du laddade upp. Ange en detaljerad beskrivning eftersom agenten använder beskrivningen för att avgöra när det specifika verktyget ska användas. Ange detaljer, inklusive synonymer, för att hjälpa din agent med urvalsprocessen.

   Den inledande beskrivningen är till exempel: "En enkel tjänst för att hantera biljetter."

   En bättre beskrivning är: "Ett system som används för att hämta, hitta och visa befintliga biljetter från SunnyADO". Det gör det möjligt för användare att uppdatera, ändra och hantera biljetter för att tillhandahålla mer data för att förbättra posterna.

3. Ange en förbättrad beskrivning under fältet beskrivning.

4. Under Lösning visa en rullgardinsmeny alla tillgängliga lösningar i den aktuella miljön. Välj lösningen som du vill använda. Mer information om vad lösningar är finns i Lösningskoncept.

   

   Lösningen väljs automatiskt om du har en föredragen lösning eller om det valda anslutningsprogrammet redan finns i lösningen.

   Du kan antingen välja en lösning eller lämna den tom. Om du lämnar lösningen tom skapas en lösning åt dig med åtgärdsnamnet och standardutgivaren. Om du lagrar åtgärden i en lösning blir det enkelt att flytta den mellan olika miljöer.

   Obs

   Om du inte ser standardlösningen eller CDS standardlösningen visas inte som ett alternativ i det här fallet eftersom vi rekommenderar att du har en anpassad lösning för enkel hantering. För mer information, se: Standardlösning jämfört med anpassad lösning.

5. När du har valt en lösning väljer du Nästa för att fortsätta.

Ange autentiseringsuppgifter

Sidan Autentisering visas för att välja vilken typ av autentisering som ska användas för API:et.

1. Välj en autentiseringsmetod från listan. Det finns tre alternativ:

   • Ingen: Ingen autentisering krävs för att komma åt API:et.
   • API-nyckel: Välj detta alternativ om ditt API kräver en API-nyckel för autentisering. Under körning, när agenten vill använda API-verktyget, uppmanar agenten användaren att autentisera sig. Användaren tillhandahåller en API-nyckel och agenten ansluter till API:et med den nyckeln.
   • Auth 2.0: Välj detta alternativ om din MCP-server använder OAuth 2.0 för autentisering. OAuth 2.0 låter enskilda användare autentisera sig mot API:et via en identitetsleverantör. Detta låter användaren ge behörigheter till din applikation (agent) utan att dela sina inloggningsuppgifter med agenten.

2. Ange de nödvändiga fälten för den valda autentiseringsmetoden. Fälten varierar beroende på autentiseringsmetod.

   • Ingen: Ingen information att ge.
   • API-nyckel:
     • Parameteretikett: En textetikett för API-parametern att presentera för användarna.
     • Parameternamn: Det faktiska namnet på API-nyckelparametern som ska användas i antingen headern eller frågesträngen.
     • Parameterlokalisering: Hur du ska skicka nyckeln till API:et. Välj antingen Header eller Query.
   • Autentisering 2.0:
     • Klient-ID: Klientidentifieraren som utfärdas av identitetsutfärdaren när du registrerar din app. Med klient-ID:t kan identitetsprovidern veta vilken app som gör begäran.
     • Klientens hemlighet: Hemligheten som utfärdats av identitetsleverantören när du registrerar din app. Din agent skickar klienthemligheten tillsammans med klient-ID:t för att bevisa att din agent har behörighet att begära åtkomsttoken för MCP-servern.
     • Auktoriserings-URL: Identitetsproviderns slutpunkt där din agent omdirigerar användaren till att logga in och bevilja behörigheter till din agent (medgivandekort som visas i agentchatten). Användaren autentiserar här och sedan svarar identitetsprovidern tillbaka till agenten på återanrops-URL:en med en auktoriseringskod.
     • Token-URL: Slutpunkten där din agent byter auktorisationskoden (eller refresh-token) mot en access-token och refresh-token. Med åtkomsttoken kan din agent använda MCP-servern för användarens räkning. Med uppdateringstoken kan agenten få ny åtkomst och uppdatera token från uppdateringsslutpunkten när den tidigare åtkomsttoken upphör att gälla.
     • Uppdaterings-URL: Slutpunkten för att begära en ny åtkomsttoken med en uppdateringstoken (så att användaren inte behöver logga in igen när token upphör att gälla).
     • Scope: (Valfritt): De behörigheter din app efterfrågar, som en rymdseparerad lista.
     • Vilket Microsoft 365 organisation har åtkomst till slutpunkterna: Detta begränsar åtkomsten till källan till antingen tillverkarens organisation eller alla organisationer. Välj antingen:
       • Endast min organisation
       • Vilken som helst Microsoft 365-organisation
     • Vilken app (klient) kan använda endpoints: GUID som definierar klientsystemet som kan användas för att komma åt denna data. Appar kan innehålla Microsoft 365, Power Automate och andra alternativ.

3. När alla fält är ifyllda väljer du Nästa.

   Du får en sida för Select och konfigurera ditt verktyg där du kan välja verktyg att aktivera från API:et.

   

Välj verktyg från API:et

Välj de API-stödda verktygen från REST API för att lägga till i din agent. Generellt erbjuder ett REST-API en rad verktyg genom de olika kombinationerna av endpoint- och HTTP-metoder (get, put, post, delete och så vidare) som definieras i API-specifikationen. I vissa fall kanske du inte vill att agentens användare ska ha möjlighet att utföra alla åtgärder som API:et vanligtvis erbjuder. Till exempel kan din API-specifikation inkludera möjligheten att uppdatera och ta bort, men du vill bara att användare av din agent ska kunna skapa poster.

1. Välj ett verktyg i listan som ska konfigureras.

   Sidan Konfigurera ditt verktyg visas.

   

2. Konfigurera namn och beskrivning för det valda verktyget. Precis som i det övergripande API:et ombeds du ange ett verktygsnamn och en verktygsbeskrivning. Beskrivningarna fylls först i automatiskt från beskrivningarna i API-specifikationen. Namnet behöver inte vara unikt, men det bör representera själva verktyget. Beskrivningen, liksom den övergripande API-beskrivningen, bör vara tillräckligt specifik för att ge språkmodellen detaljer för att bättre kunna identifiera om din fråga stämmer överens med just detta verktyg.

3. När fälten är ifyllda väljer du Nästa.

   Sidan Granska verktygets parametrar visas.

   

   Denna sida visar de värden som förväntas för indata och de utdata som returneras. Du kan inte ändra dessa värden, men du kan uppdatera beskrivningarna av in- och utgångar. Allt innehåll på den här sidan hämtas direkt från den uppladdade API-specifikationen.

4. Uppdatera beskrivningarna vid behov. Beskrivningarna ger en definition av vad värdena används till. Om någon av beskrivningarna är tom måste de fyllas i innan du kan gå vidare. Du kan klistra in namnet om du inte har en bättre beskrivning.

5. När du har slutfört beskrivningarna väljer du Nästa.

   Det första verktyget är nu konfigurerat och visas i listan över valda verktyg på sidan Välj och konfigurera plugin-verktyget .

   

6. Lägg till andra verktyg från API:et som du vill inkludera just nu. När du är klar med att lägga till verktyg som du vill att agenten ska stödja väljer du Nästa.

   Sidan Granska ditt verktyg är synlig. Sidan innehåller information om det konfigurerade REST API-verktyget.

   

Granska och publicera

1. Om du behöver göra några uppdateringar kan du välja Tillbaka och göra ändringarna. Annars väljer du Nästa.

   En skärm visas som anger att verktyget publiceras medan processen slutförs. Du informeras när publiceringen är klar.

2. Välj Skapa anslutning för att fortsätta. Du återvänder till skärmen för Lägg till .

3. Välj REST API i verktygstypväljaren. Du kan se de nyskapade verktygen från ditt API. Det borde finnas en post per verktyg du lagt till från API:et.

4. För varje av de nykonfigurerade verktygen från API:et behöver du skapa eller välja en anslutning till API:et och lägga till verktyget i din agent:

   1. På skärmen Lägg till verktyg , välj verktyget.
   2. Under Anslutning, välj en befintlig anslutning eller välj Skapa ny anslutning.
   3. Ange all information som behövs för anslutningen, välj sedan Create för att skapa anslutningen till verktyget.
   4. Välj Add och konfigurera för att lägga till verktyget i din agent.

   

Verktygen från REST API finns nu tillgängliga för användning i din agent.