Rozszerzanie agenta przy użyciu narzędzi z interfejsu API REST (wersja zapoznawcza)

[Ten artykuł stanowi wstępną wersję dokumentacji i może ulec zmianie.]

Możesz użyć interfejsów API REST (w tym API OpenAI), aby połączyć utworzonego agenta z systemami zewnętrznymi i uzyskać dostęp do dostępnych danych do wykorzystania w ramach agenta. Możesz połączyć swojego agenta z interfejsem API REST, podając w programie Copilot Studio trzy elementy:

• Specyfikacja OpenAPI definiująca funkcje interfejsu API i dostępne akcje
• Szczegółowe informacje na temat wymaganego typu uwierzytelniania i szczegółów uwierzytelniania dla użytkowników, którzy mogą połączyć się z interfejsem API w celu uzyskania dostępu do systemu zewnętrznego
• Opisy ułatwiające modelowi językowemu określenie, kiedy należy wywołać interfejs API w celu wykorzystania danych

Interfejsy API REST można dodawać do agentów funkcji Copilot i agentów niestandardowych za pośrednictwem Copilot Studio.

Agenty funkcji Copilot umożliwiają twórcy łączenie wielu źródeł danych, takich jak łączniki, interfejsy API, prompty i źródła wiedzy, w jeden agent. Możesz użyć tego agenta, aby rozszerzyć środowiska agenta marki Microsoft, takie jak Microsoft 365 Copilot.

Agenci niestandardowi to agenci autonomiczni, którzy zawierają łączniki, interfejsy API, monity i źródła wiedzy. Możesz korzystać z niestandardowych agentów bezpośrednio, integrując je ze stronami internetowymi lub innymi kanałami.

Wymagania wstępne

Aby rozszerzyć środowiska agentów marki Microsoft za pomocą akcji konektora, należy spełnić kilka wymagań wstępnych.

W przypadku wszystkich typów środowiska agenta musisz mieć uwierzytelnienia na poziomie twórcy i licencji Copilot Studio.

Będziesz także potrzebować kopii specyfikacji OpenAPI, wiedzy na temat wymaganego rodzaju uwierzytelnienia i szczegółów uwierzytelnienia.

Dodawanie akcji interfejsu API REST do agenta

Dodanie interfejsu API REST do agenta obejmuje kilka kroków. Poniższe sekcje przeprowadzą Cię przez ten proces.

Proces dodawania interfejsu API REST jest identyczny zarówno dla agentów niestandardowych, jak i agentów funkcji Copilot.

Proces składa się z kilku kroków.

Dodawanie akcji do agenta

1. Przejdź do strony Omówienie agenta.

   

2. W sekcji Narzędzia wybierz pozycję Dodaj narzędzie. Możesz również przejść do karty Narzędzia i wybrać pozycję Dodaj narzędzie.

   Strona Dodawanie narzędzia jest wyświetlana.

3. Wybierz Nowe narzędzie>REST API.

Podaj specyfikację, opis i rozwiązanie interfejsu API

1. Prześlij plik specyfikacji OpenAPI dla interfejsu API REST, z którym chcesz się połączyć. Możesz przeciągnąć i upuścić plik specyfikacji na ekran Prześlij interfejs API REST lub przejrzeć system, aby zlokalizować plik, którego chcesz użyć.

   

   Notatka

   Specyfikacja OpenAPI musi być plikiem JSON w formacie v2. Jeśli zostanie przesłana specyfikacja w wersji 3, zostanie ona automatycznie przetłumaczona na specyfikację w wersji 2 podczas procesu tworzenia.

   Po przesłaniu specyfikacji ekran zostanie zaktualizowany, aby wskazać nazwę pliku specyfikacji i szczegóły.

   

   W kolejnych krokach osadzimy procedurę na konkretnym przykładzie SunnyADO, systemu zarządzania zgłoszeniami ADO. W tym przykładzie celem jest umożliwienie użytkownikom pobierania i aktualizowania biletów za pośrednictwem agenta.

2. Sprawdź szczegóły, a następnie wybierz przycisk Dalej.

   Zostanie wyświetlona strona szczegółów wtyczki interfejsu API, na której można podać dodatkowe informacje o interfejsie API.

   

   Pole opisu jest początkowo wypełniane na podstawie opisu w przesłanej specyfikacji interfejsu API. Podaj szczegółowy opis, ponieważ aranżacja agenta używa opisu do określenia, kiedy użyć konkretnego narzędzia. Podaj szczegóły, w tym synonimy, aby pomóc agent w procesie selekcji.

   Na przykład początkowy opis brzmi: "Prosta usługa do zarządzania biletami".

   Lepszy opis to: „System używany do pobierania, wyszukiwania i wyświetlania istniejących biletów z SunnyADO. Pozwala użytkownikom aktualizować, zmieniać i zarządzać zgłoszeniami, aby dostarczyć więcej danych w celu ulepszenia rekordów.

3. Wprowadź poprawiony opis w polu Opis.

4. W obszarze Rozwiązanie na liście rozwijanej zostaną wyświetlone wszystkie rozwiązania dostępne w bieżącym środowisku. Wybierz rozwiązanie, które chcesz zastosować. Więcej informacji na temat rozwiązań można znaleźć w pojęciach rozwiązań.

   

   Jeśli preferowane rozwiązanie lub wybrany łącznik znajduje się już w rozwiązaniu, to rozwiązanie zostanie automatycznie zaznaczone.

   Można wybrać rozwiązanie lub pozostawić puste. Jeśli pozostawisz rozwiązanie puste, zostanie utworzone rozwiązanie z nazwą akcji i domyślnym wydawcą. Przechowywanie akcji w rozwiązaniu umożliwia łatwe przenoszenie jej w środowiskach.

   Notatka

   W tym przypadku rozwiązanie domyślne lub rozwiązanie domyślne (CDS) nie będzie widzieć jako opcji, ponieważ zaleca się posiadanie niestandardowego rozwiązania do łatwego zarządzania. Więcej informacji znajdziesz w temacie Rozwiązanie domyślne a rozwiązanie niestandardowe.

5. Po wybraniu rozwiązania wybierz przycisk Dalej, aby kontynuować.

Dodaj szczegóły uwierzytelniania

Strona Uwierzytelnianie zostanie wyświetlona, na której można wybrać typ uwierzytelniania, który ma być używany dla interfejsu API.

1. Wybierz metodę uwierzytelniania z listy.

2. Wypełnij wymagane pola dla metody uwierzytelniania. Pola różnią się w zależności od metody uwierzytelniania.

   • Brak: żadne inne pola nie są wymagane.
   • Klucz interfejsu API:
     • Etykieta parametru: Etykieta tekstowa parametru interfejsu API.
     • Nazwa parametru: nazwa tekstowa parametru interfejsu API.
     • Lokalizacja parametru: pozycja, w której można znaleźć parametr.
   • Auth 2.0:
     • Identyfikator klienta: identyfikator GUID klienta usługi docelowej.
     • Klucz tajny klienta — wartość klucza tajnego klienta. Klucz tajny nie jest wyświetlany, gdy użytkownik otworzy później panel edycji. Zachowaj jednak klucz tajny, ponieważ będzie on potrzebny, jeśli zdecydujesz się wprowadzić dalsze zmiany.
     • Adres URL autoryzacji: adres URL używany do autoryzacji systemu źródłowego.
     • Adres URL tokenu: adres URL, z którego można pobrać token.
     • Adres URL odświeżania: Adres URL, na który zostaniesz przekierowany w scenariuszu odświeżania.
     • Zakres: adres URL zakresu przypisany do interfejsu API dla aplikacji Microsoft Entra.
     • Która organizacja Microsoft 365 uzyskuje dostęp do punktów końcowych: ogranicza dostęp do źródła do organizacji twórcy lub wszystkich organizacji.
     • Aplikacja (klient) może używać punktów końcowych: identyfikator GUID definiujący system kliencki, którego można użyć do uzyskania dostępu do tych danych. Aplikacje mogą obejmować Microsoft 365, Power Automate i inne opcje.

3. Po wypełnieniu wszystkich pól wybierz przycisk Dalej.

   Zostanie wyświetlona strona Wybierz i skonfiguruj narzędzie wtyczki, na której można wybrać narzędzia, które mają zostać włączone dla interfejsu API.

   

Wybieranie narzędzi dla interfejsu API

Wybierz narzędzia obsługiwane przez interfejs API, które mają być włączone. Ogólnie rzecz biorąc, interfejs API REST oferuje szereg narzędzi za pośrednictwem różnych kombinacji punktów końcowych i metody HTTP (get, put, post, delete itd.) zdefiniowanych w specyfikacji interfejsu API. W niektórych przypadkach możesz nie chcieć, aby użytkownicy agent mieli możliwość wykonywania każdej akcji ogólnie oferowanej przez interfejs API. Na przykład specyfikacja interfejsu API może obejmować akcje aktualizowania i usuwania, ale chcesz, aby tylko użytkownicy Twojego agent mogli tworzyć rekordy.

1. Wybierz narzędzie z listy, aby je skonfigurować.

   Zostanie wyświetlona strona Skonfiguruj akcję wtyczki.

   

2. Skonfiguruj wybrane działanie. Podobnie jak w przypadku ogólnego interfejsu API, zostanie wyświetlony monit o podanie nazwy narzędzia i opisu narzędzia. Opisy są początkowo wstępnie wypełniane na podstawie opisów w specyfikacji interfejsu API. Nazwa nie musi być unikatowa, ale powinna reprezentować samo narzędzie. Opis, podobnie jak w przypadku ogólnego opisu interfejsu API, powinien być wystarczająco szczegółowy, aby zapewnić modelowi języka szczegółowe informacje, aby lepiej zidentyfikować, że zapytanie jest zgodne z tym konkretnym narzędziem.

3. Po wypełnieniu pól wybierz przycisk Dalej.

   Zostanie wyświetlona strona Przegląd parametrów narzędzia.

   

   Na tej stronie wyświetlane są wartości podawane jako część możliwych wartości wejściowych i wyjściowych. Tych wartości nie można zmienić, jednak opisy danych wejściowych i wyjściowych można aktualizować. Cała zawartość tej strony jest pobierana bezpośrednio z przesłanej specyfikacji interfejsu API.

4. Wypełnij wartości zgodnie z potrzebami opisów. Opisy zawierają definicję tego, do czego służą wartości. Jeśli którykolwiek z opisów jest pusty, należy go uzupełnić, zanim będzie można przejść dalej. Możesz wkleić nazwę, jeśli nie masz lepszego opisu.

5. Po zakończeniu opisów wybierz przycisk Dalej.

   Pierwsze narzędzie jest teraz skonfigurowane i wyświetlane na liście Wybranych narzędzi na stronie Wybierz i skonfiguruj narzędzie wtyczki .

   

6. Dodaj wszelkie inne działania, które chcesz uwzględnić w tej chwili. Po zakończeniu dodawania narzędzi, które mają być obsługiwane przez agenta, wybierz pozycję Dalej.

   Zostanie wyświetlona strona Przegląd twojego narzędzia. Strona zawiera szczegółowe informacje o skonfigurowanym narzędziu interfejsu API REST.

   

Przejrzyj i opublikuj

1. Jeśli musisz wprowadzić aktualizacje, możesz wybrać pozycję Wstecz i wprowadzić zmiany. W przeciwnym razie wybierz Dalej.

   Na ekranie pojawi się komunikat informujący, że Twoje narzędzie jest publikowane, gdy proces jest finalizowany. Otrzymasz informację po zakończeniu publikowania.

2. Po zakończeniu publikowania wrócisz do ekranu Wybieranie narzędzia . W tym miejscu można dodać nowo skonfigurowany interfejs API REST do agenta funkcji Copilot lub agenta niestandardowego i zakończyć konfigurację komponentu.

   

Narzędzie interfejsu API REST jest teraz dostępne do użycia w agencie.