Rozšíření agenta pomocí nástrojů z rozhraní REST API (Preview)

Note

Funkce v tomto článku jsou poháněny standardním kabelem, který využívá fakturační možnosti popsané v sekci Licencování pro agenty poháněné standardním kabelem. Naučte se, jak získat přístup ke standardním funkcím v části Přístup ke standardním agentům a tokům agentů.

[Tento článek představuje předběžnou dokumentaci a může se změnit.]

Pomocí rozhraní REST API (včetně rozhraní OpenAI API) můžete připojit agenta, kterého vytvoříte, s externími systémy a získat přístup k dostupným datům pro použití v rámci agenta. Agenta můžete připojit k rozhraní REST API tím, že Copilot Studiu poskytnete tři věci:

• Specifikace OpenAPI definující funkce rozhraní API a dostupné akce
• Podrobnosti o potřebném typu ověřování a podrobnostech ověřování pro uživatele pro připojení k rozhraní API pro přístup k externímu systému
• Popisy, které jazykovému modelu pomůžou určit, kdy se má vyvolat rozhraní API pro využití dat

Do agentů Copilota a vlastních agentů můžete přidávat rozhraní REST API prostřednictvím aplikace Copilot Studio.

Important

Tento článek obsahuje dokumentaci Microsoft Copilot Studio Preview a může se změnit.

Funkce náhledu nejsou určeny pro produkční použití a mohou mít omezenou funkčnost. Jsou to funkce, které jsou poskytnuté před oficiálním vydáním, abyste si je mohli co nejdříve vyzkoušet a napsat nám své názory.

Pokud vytváříte agenta připraveného pro produkční prostředí, přečtěte si Přehled Microsoft Copilot Studio.

Copilot agenti umožňují tvůrci kombinovat více zdrojů dat, jako jsou konektory, rozhraní API, výzvy a zdroje znalostí, do jednoho agenta. Tento agent můžete použít k rozšíření Microsoft značkových prostředí agentů, jako je Microsoft 365 Copilot.

Vlastní agenti jsou samostatní agenti, kteří obsahují konektory, rozhraní API, výzvy a zdroje znalostí. Vlastní agenty můžete používat přímo jejich integrací do webů nebo jiných kanálů.

Note

Nástroje REST API musíte vytvořit ze specifikace OpenAPI v2. Tento požadavek je způsoben chováním platformy Power Platform při zpracování specifikací rozhraní API. Pokud odešlete specifikaci v3, proces vytváření ho automaticky přeloží na specifikaci v2.

Předpoklady

• Přihlašovací údaje na úrovni tvůrce a licence Copilot Studio.
• Kopie specifikace OpenAPI pro REST API, ke kterému se chcete připojit
• Znalost typu autentizace potřebnou k připojení k API a detaily autentizace.

Přidejte do svého agenta nástroj REST API

Pokud chcete do agenta přidat nástroj REST API, proveďte následující kroky:

1. Přidejte nový nástroj agenta a vyberte REST API
2. Poskytnout specifikaci, popis a řešení API
3. Uveďte autentizační údaje
4. Vyberte nástroje z API
5. Kontrola a publikování

Následující části vás krok za krokem provedou celým procesem.

Postup přidání rozhraní REST API je stejný jak pro vlastní agenty, tak pro agenty Microsoft 365 Copilot.

Přidejte nástroj pro nové agenty a vyberte REST API

1. Přejděte na stránku Přehledu vašeho makléře.

2. V části Nástroje vyberte Přidat nástroj. Můžete také přejít na kartu Nástroje a vybrat Přidat nástroj.

   Zobrazí se stránka Přidat nástroj .

3. Vyberte Nové nástroje>REST API.

Poskytnout specifikaci, popis a řešení API

1. Nahrajte OpenAPI soubor specifikace pro rozhraní REST API, ke kterému se chcete připojit. Soubor specifikace můžete buď přetáhnout na obrazovku Nahrát rozhraní REST API, nebo procházet systém a vyhledat soubor, který chcete použít.

   

   Note

   Specifikace OpenAPI musí být soubor JSON ve formátu v2. Pokud odešlete specifikaci v3, proces vytváření ho automaticky přeloží na specifikaci v2.

   Po nahrání specifikace se obrazovka aktualizuje, aby se zobrazil název souboru specifikace a podrobnosti.

   

   V následujících krocích tento postup používá konkrétní příklad systému správy lístků ADO SunnyADO. V tomto příkladu je záměrem umožnit uživatelům načítat a aktualizovat své tikety prostřednictvím agent.

2. Ověřte podrobnosti a pak vyberte Další.

   Zobrazí se stránka s podrobnostmi o modulu plug-in API, kde můžete poskytnout další informace o rozhraní API.

   

   Pole popisu se zpočátku vyplní na základě popisu ve specifikaci rozhraní API, kterou jste nahráli. Zadejte podrobný popis, protože orchestrace agenta využívá tuto informaci k určení, kdy použít konkrétní nástroj. Uveďte podrobnosti, včetně synonym, které pomohou vašemu agent s výběrovým řízením.

   Počáteční popis je například: "Jednoduchá služba pro správu tiketů."

   Lepší popis je: "Systém používaný k získání, načtení, vyhledání a zobrazení existujících vstupenek od SunnyADO." Umožňuje uživatelům aktualizovat, měnit a spravovat lístky, aby poskytovali více dat pro zlepšení záznamů.

3. Zadejte vylepšený popis do pole Popis.

4. V části Řešení se v rozevíracím seznamu zobrazí všechna řešení dostupná v aktuálním prostředí. Vyberte řešení, které chcete použít. Přečtěte si další informace o řešeních v konceptech řešení.

   

   Pokud máte preferované řešení nebo je vámi vybraný konektor již v řešení, toto řešení je vybráno automaticky.

   Můžete buď vybrat řešení, nebo ho nechat prázdné. Ponecháte-li řešení prázdné, vytvoří se pro vás řešení s názvem akce a výchozím vydavatelem. Uložení vaší akce do řešení vám umožní snadno ji přesouvat napříč prostředími.

   Note

   Pokud výchozí řešení nebo výchozí řešení CDS nevidíte jako možnost v tomto případě, přidejte vlastní řešení pro snadnou správu. Další informace najdete ve výchozím řešení vs. vlastní řešení.

5. S vybraným řešením pokračujte výběrem možnosti Další .

Uveďte autentizační údaje

Zobrazí se stránka Ověřování . Vyberte typ ověřování, který se má použít pro rozhraní API.

1. Ze seznamu vyberte metodu ověřování. Vyberte ze tří možností:

   • Žádné: Pro přístup k API není potřeba žádná autentizace.
   • API klíč: Vyberte tuto možnost, pokud vaše API vyžaduje API klíč pro autentizaci. Za běhu, když chce agent použít API nástroj, agent uživatele vyzve k autentizaci. Uživatel zadá API klíč a agent se připojí k API pomocí tohoto klíče.
   • Autentizace 2.0: Vyberte tuto možnost, pokud váš MCP server používá OAuth 2.0 pro autentizaci. OAuth 2.0 umožňuje jednotlivým uživatelům autentizovat se k API prostřednictvím poskytovatele identity. Tato metoda ověřování umožňuje uživateli udělit oprávnění k vaší aplikaci (agentu) bez sdílení přihlašovacích údajů s agentem.

2. Zadejte požadovaná pole pro vybranou metodu autentizace. Pole se liší v závislosti na metodě ověřování.

   • Žádné: Žádné informace k poskytnutí.
   • Klíč rozhraní API:
     • Štítek parametru: Textový štítek pro parametr API, který se zobrazí uživatelům.
     • Název parametru: Skutečný název parametru klíče rozhraní API, který se má použít v hlavičce nebo řetězci dotazu.
     • Umístění parametru: Jak odešlete klíč pro rozhraní API. Vyberte buď hlavičku , nebo dotaz.
   • Autentizace 2.0:
     • ID klienta: Identifikátor klienta, který poskytovatel identity vydává při registraci vaší aplikace. ID klienta umožňuje zprostředkovateli identity zjistit, jaká aplikace žádost provádí.
     • Tajný klíč klienta: Tajný klíč klienta, který vydává poskytovatel identity při registraci vaší aplikace. Váš agent odešle tajný klíč klienta spolu s ID klienta, aby potvrdil, že váš agent má oprávnění požadovat přístupové tokeny pro server MCP.
     • Adresa URL autorizace: Koncový bod zprostředkovatele identity, kde váš agent přesměruje uživatele, aby se přihlásil a udělil oprávnění k vašemu agentu (karta souhlasu prezentovaná v chatu agenta). Uživatel se tady ověří a zprostředkovatel identity odpoví zpět agentu na adrese URL zpětného volánípomocí autorizačního kódu.
     • URL tokenu: Endpoint, kde váš agent vyměňuje autorizační kód (nebo obnovovací token) za přístupový token a obnovovací token. Přístupový token umožňuje vašemu agentu používat server MCP jménem uživatele. Obnovovací tokeny umožňují agentu získat nový přístup a obnovovací tokeny z koncového bodu aktualizace, když vyprší platnost předchozího přístupového tokenu.
     • Adresa URL aktualizace: Koncový bod k vyžádání nového přístupového tokenu pomocí obnovovacího tokenu (aby se uživatel nemusel při vypršení platnosti tokenu znovu přihlásit).
     • Rozsah: (volitelné): Oprávnění, která vaše aplikace žádá, jako seznam oddělený mezi řádky.
     • Která Microsoft 365 organizace přistupuje ke koncovým bodům: Toto nastavení omezuje přístup ke zdroji na organizaci tvůrce nebo na všechny organizace. Vyberte jednu z těchto akcí:
       • Pouze moje organizace
       • Jaká organizace Microsoft 365
     • Která aplikace (klient) může používat koncové body: GUID, který definuje klientský systém, který lze použít k přístupu k těmto datům. Aplikace můžou zahrnovat Microsoft 365, Power Automate a další možnosti.

3. Po dokončení všech polí vyberte Další.

   Zobrazí se stránka Vybrat a nakonfigurovat nástroj , kde můžete vybrat nástroje, které se mají povolit z rozhraní API.

   

Vyberte nástroje z API

Vyberte nástroje podporované API z REST API a přidejte je do svého agenta. Obecně REST API nabízí řadu nástrojů prostřednictvím různých kombinací koncových a HTTP metod (get, put, post, delete atd.) definovaných ve specifikaci API. V některých případech možná nebudete chtít, aby uživatelé agent měli možnost provádět všechny akce, které rozhraní API obecně nabízí. Například specifikace API může zahrnovat možnost aktualizovat a mazat, ale chcete, aby záznamy vytvářeli pouze uživatelé vašeho agenta.

1. Vyberte nástroj ze seznamu, který chcete nakonfigurovat.

   Zobrazí se stránka Konfigurace nástroje .

   

2. Nastavte název a popis vybraného nástroje. Podobně jako v celkovém rozhraní API zadejte název nástroje a popis nástroje. Popisy jsou zpočátku předem vyplněny z popisů ve specifikaci API. Název nemusí být jedinečný, ale měl by představovat samotný nástroj. Popis, stejně jako u celkového popisu API, by měl být dostatečně konkrétní, aby jazykovému modelu poskytl podrobnosti pro lepší určení, zda váš dotaz odpovídá tomuto konkrétnímu nástroji.

3. Po dokončení polí vyberte Další.

   Zobrazí se stránka Kontrola parametrů vašeho nástroje .

   

   Tato stránka ukazuje očekávané hodnoty pro vstup a výstupní hodnoty, které jsou vráceny. Tyto hodnoty nemůžete změnit, ale můžete aktualizovat popisy vstupů a výstupů. Veškerý obsah na této stránce se načítá přímo z nahrané specifikace rozhraní API.

4. Popisy podle potřeby aktualizujte. Popisy poskytují definici toho, k čemu se hodnoty používají. Pokud je některý z popisů prázdný, musíte je před přechodem dopředu dokončit. Pokud nemáte lepší popis, můžete vložit název.

5. Po dokončení popisů vyberte Další.

   První nástroj je teď nakonfigurovaný a zobrazí se v seznamu vybraných nástrojů na stránce Vybrat a nakonfigurovat nástroj plug-in .

   

6. Přidejte další nástroje z rozhraní API, které chcete v tuto chvíli zahrnout. Až budete hotovi s přidáváním nástrojů, které má agent podporovat, vyberte Další.

   Zobrazí se stránka Zkontrolovat nástroj . Na stránce najdete podrobnosti o nakonfigurovaném nástroji REST API.

   

Kontrola a publikování

1. Pokud potřebujete provést nějaké aktualizace, vyberte Zpět a proveďte změny. V opačném případě vyberte Další.

   Zobrazí se obrazovka s oznámením, že váš nástroj se publikuje během procesu. Po dokončení publikování budete informováni.

2. Vyberte Vytvořit spojení pro pokračování. Vrátíte se na obrazovku Přidat nástroje .

3. Vyberte REST API ve výběru typu nástroje. Nově vytvořené nástroje můžete vidět přímo ve svém API. Na každý nástroj, který jste přidali z API, by měl být jeden záznam.

4. Pro všechny nově nakonfigurované nástroje z rozhraní API vytvořte nebo vyberte připojení k rozhraní API a přidejte ho do svého agenta:

   1. Na obrazovce Přidat nástroj vyberte nástroj.
   2. V sekci Připojení vyberte stávající spojení nebo zvolte Vytvořit nové připojení.
   3. Zadejte všechny informace potřebné pro připojení a pak vyberte Vytvořit pro vytvoření připojení k nástroji.
   4. Vyberte Přidat a nastavit, abyste nástroj přidali do svého agenta.

   

Nástroje z REST API jsou nyní dostupné pro použití ve vašem agentu.

Tip

Pokud chcete nástroj snadněji najít, najděte ho pomocí panelu hledání.