Zestaw SDK agenta (wersja zapoznawcza)

Przekazuje ładunki działania bot framework/Microsoft Agentów SDK do punktu końcowego agenta dostarczonego przez użytkownika. Adres URL punktu końcowego agenta jest dostarczany na wywołanie jako parametr wejściowy. Uwierzytelnianie jest wybierane podczas tworzenia połączenia: brak uwierzytelniania, statyczny klucz interfejsu API lub Microsoft Entra ID OAuth (client_credentials lub logowanie użytkownika). Po wybraniu protokołu OAuth odbiorcy tokenu elementu nośnego (adres URL zasobu skonfigurowany w połączeniu) muszą być zgodni z odbiorcami oczekiwaną przez agenta docelowego.

Ten łącznik jest dostępny w następujących produktach i regionach:

Łącznik zestawu SDK agenta przekazuje ładunek działania bot framework/Microsoft agentów do punktu końcowego agenta dostarczonego przez użytkownika. Adres URL punktu końcowego agenta jest dostarczany na wywołanie jako parametr wejściowy. Połączenie wybiera sposób uwierzytelniania łącznika w agencie: brak uwierzytelniania, statyczny klucz interfejsu API, token tylko Microsoft Entra ID aplikacji (poświadczenia klienta) lub Microsoft Entra ID delegowany token użytkownika (logowanie użytkownika). W przypadku obu opcji Microsoft Entra ID odbiorcy tokenu elementu nośnego (adres URL zasobu skonfigurowany w połączeniu) muszą być zgodni z odbiorcami oczekiwaną przez agenta docelowego.

Wymagania wstępne

• Wdrożony zestaw SDK agentów Microsoft/agent platformy Bot Framework osiągalny za pośrednictwem protokołu HTTPS.
• W przypadku Microsoft Entra ID (poświadczeń klienta): aplikacja Microsoft Entra ID zarejestrowana w dzierżawie hostująca agenta, skonfigurowana przy użyciu client_credentials udzielenia i uprawnienia do wywoływania agenta docelowego.
• W przypadku Microsoft Entra ID (logowanie użytkownika): aplikacja Microsoft Entra ID agenta (jej identyfikator aplikacji Microsoft) z wpisem tajnym klienta, uwidoczniony zakres interfejsu API, na który użytkownicy mogą wyrazić zgodę, Microsoft Graph User.Read ("Zaloguj się i odczyt profilu użytkownika") delegowane uprawnienie ze zgodą i https://global.consent.azure-apim.net/redirect/agentsdk dodane jako identyfikator URI przekierowania sieci Web.
• W przypadku opcji klucza interfejsu API i poświadczeń klienta oczekiwana grupa odbiorców tokenu agenta (zazwyczaj Microsoft identyfikator aplikacji agenta, na przykład api://<appId> identyfikator GUID identyfikatora aplikacji lub identyfikatora GUID identyfikatora aplikacji). W przypadku logowania użytkownika odbiorcy muszą być identyfikatorem GUID identyfikatora aplikacji (zobacz poniżej).

Pobieranie poświadczeń

Microsoft Entra ID (poświadczenia klienta)

Łącznik wysyła token tylko do aplikacji. Do uwierzytelniania żądań interfejsu API potrzebne są następujące elementy:

1. Identyfikator dzierżawy aplikacji Microsoft Entra ID.
2. Identyfikator klienta (identyfikator aplikacji) aplikacji Microsoft Entra ID.
3. Klucz tajny klienta dla tej aplikacji.
4. Adres URL zasobu zgodny z odbiorcami oczekiwany przez agenta docelowego (wzorzec uwierzytelniania umiejętności bot framework).

Podaj te wartości podczas tworzenia połączenia. Utwórz jedno połączenie na agenta, jeśli odbiorcy różnią się.

Microsoft Entra ID (logowanie użytkownika)

Łącznik wysyła delegowany token konta zalogowanego do połączenia, aby agent mógł wymienić go w imieniu tego konta (na przykład za pomocą programu obsługi Zestaw SDK agentów usługi Microsoft 365ConnectorUserAuthorization). Potrzebne będą następujące elementy:

1. Identyfikator dzierżawy aplikacji Microsoft Entra ID agenta.
2. Identyfikator klienta: własny identyfikator aplikacji Microsoft agenta. Zestaw SDK agentów usługi Microsoft 365 wymienia token w imieniu użytkownika tylko wtedy, gdy token został wystawiony dla własnej aplikacji agenta.
3. Klucz tajny klienta dla tej aplikacji.
4. Adres URL zasobu: Microsoft identyfikator aplikacji agenta (GUID), taką samą wartość jak identyfikator klienta. Ponieważ własna aplikacja agenta jest zarówno klientem, jak i zasobem, Microsoft Entra wymaga tutaj identyfikatora GUID (AADSTS90009 w przeciwnym razie); api://<appId> nie jest obsługiwana dla tej opcji.

Podaj te wartości podczas tworzenia połączenia, a następnie zaloguj się i wyrazisz zgodę na uwidoczniony zakres agenta. Utwórz jedno połączenie na agenta.

Aplikacja wymaga również uprawnienia delegowanego użytkownika Microsoft Graph User.Read ("Zaloguj się i odczyt profilu użytkownika") ze zgodą. Bez niego logowanie kończy się niepowodzeniem z AADSTS90008.

Aby wymienić token dla podrzędnego interfejsu API, skonfiguruj delegowane uprawnienia tego interfejsu API w aplikacji agenta i uzyskaj wymaganą zgodę użytkownika lub administratora. Uwidacznianie zakresu we własnym interfejsie API agenta nie przyznaje uprawnień podrzędnych.

Znane problemy i ograniczenia

• Dane agentEndpoint wejściowe muszą być pełnym adresem URL HTTPS (na przykład https://my-agent.azurewebsites.net). Łącznik dołącza /api/messages i przekazuje ładunek działania.
• Łącznik przekazuje ładunek działania as-is i nie ustawia wartości deliveryMode. Agent odpowiada asynchronicznie (normalne dostarczanie) przez działania odpowiedzi POSTing z powrotem do podanego serviceUrl w działaniu przychodzącym (obiekt wywołujący, np. Microsoft Copilot Studio, zapewnia wywołanie zwrotne serviceUrlz kluczem SAS).
• Połączenie Microsoft Entra ID (logowanie użytkownika) zawsze wysyła delegowany token konta zalogowanego do połączenia, dla każdego wywołania wykonanego z tym połączeniem, w tym połączeń w imieniu innych osób rozmawiających z agentem. Nie wysyła oddzielnego tokenu dla każdego obiektu wywołującego, więc użytkownik działania from może różnić się od użytkownika w tokenie. Autoryzuj żądania tylko jako konto w zweryfikowanych tokenach i nie traktuj nagłówków działań from ani żądań jako urzędu osoby rozmawiającej. Jeśli agent musi działać jako każda osoba rozmawiająca z nim, nie używaj tego typu połączenia.
• Jeśli zgoda zalogowanego konta zostanie odwołana lub jego sesja nie może być już odświeżona, zaloguj się ponownie do połączenia.
• Ten łącznik jest w wersji zapoznawczej. Dostępność i możliwości mogą ulec zmianie.

Tworzenie połączenia

Łącznik obsługuje następujące typy uwierzytelniania:

klucz interfejsu API

Identyfikator uwierzytelniania: apiKey

Dotyczy: wszystkie regiony

Uwierzytelnianie przy użyciu klucza statycznego interfejsu API oczekiwanego przez agenta docelowego w niestandardowym nagłówku HTTP. Określ zarówno nazwę nagłówka (na przykład x-api-key) jak i jego wartość.

Nie jest to możliwe do udostępnienia połączenie. Jeśli aplikacja power zostanie udostępniona innemu użytkownikowi, zostanie wyświetlony monit o jawne utworzenie nowego połączenia.

Microsoft Entra ID (poświadczenia klienta)

Identyfikator uwierzytelniania: oauthClientCredentials

Dotyczy: wszystkie regiony

Mint OAuth tokeny elementu nośnego z aplikacji Microsoft Entra ID przy użyciu przepływu client_credentials. Odbiorcy tokenu elementu nośnego (adres URL zasobu) muszą być zgodni z odbiorcami oczekiwaną przez agenta docelowego.

Nie jest to możliwe do udostępnienia połączenie. Jeśli aplikacja power zostanie udostępniona innemu użytkownikowi, zostanie wyświetlony monit o jawne utworzenie nowego połączenia.

Microsoft Entra ID (logowanie użytkownika)

Identyfikator uwierzytelniania: oauthAuthorizationCode

Dotyczy: wszystkie regiony

Zaloguj się za pośrednictwem aplikacji Microsoft Entra ID agenta docelowego (przepływu kodu autoryzacji) i wyślij token delegowanego elementu nośnego konta logowania. Każde wywołanie wykonane za pomocą tego połączenia używa konta zalogowanego do połączenia, a nie osoby rozmawiającej z agentem. Aby wymienić token w imieniu użytkownika, agent potrzebuje uprawnień delegowanych podrzędnych i skonfigurowanych zgody.

Nie jest to możliwe do udostępnienia połączenie. Jeśli aplikacja power zostanie udostępniona innemu użytkownikowi, zostanie wyświetlony monit o jawne utworzenie nowego połączenia.

Bez uwierzytelniania

Identyfikator uwierzytelniania: anonimowy

Dotyczy: wszystkie regiony

Wywołaj docelowy punkt końcowy agenta bez żadnego nagłówka uwierzytelniania. Tej funkcji należy używać tylko z agentami, którzy jawnie akceptują połączenia anonimowe.

Jest to możliwe do udostępnienia połączenie. Jeśli aplikacja power jest udostępniana innemu użytkownikowi, połączenie jest również udostępniane. Aby uzyskać więcej informacji, zobacz omówienie Connectors dla aplikacji kanwy — Power Apps | Microsoft Docs

Domyślne [PRZESTARZAŁE]

Dotyczy: wszystkie regiony

Ta opcja dotyczy tylko starszych połączeń bez jawnego typu uwierzytelniania i jest dostępna tylko w celu zapewnienia zgodności z poprzednimi wersjami.

Nie jest to możliwe do udostępnienia połączenie. Jeśli aplikacja power zostanie udostępniona innemu użytkownikowi, zostanie wyświetlony monit o jawne utworzenie nowego połączenia.

Akcje

Wysyłanie działania do agenta

Definicje

obiekt