Uwierzytelnianie Agent2Agent (A2A)

Protokół Agent2Agent (A2A) umożliwia agentom wywoływanie innych agentów. Większość punktów końcowych A2A wymaga uwierzytelniania w celu uzyskania dostępu do punktu końcowego i jego podstawowej usługi. Skonfigurowanie uwierzytelniania zapewnia, że tylko autoryzowani użytkownicy mogą wywoływać narzędzia A2A w Foundry Agent Service.

W tym artykule opisano metody uwierzytelniania dostępne dla połączeń A2A i pomaga wybrać odpowiednie podejście dla danego scenariusza.

Scenariusze uwierzytelniania

Ogólnie rzecz biorąc, istnieją dwa scenariusze uwierzytelniania:

• Wspólne uwierzytelnianie: Każdy użytkownik agenta używa tej samej tożsamości do uwierzytelniania w punkcie końcowym A2A. Pojedynczy kontekst użytkownika nie jest utrwalany. Takie podejście jest idealne, gdy wszyscy użytkownicy powinni mieć ten sam poziom dostępu. Jeśli na przykład utworzysz agenta czatu w celu pobrania informacji z Azure Cosmos DB dla organizacji, możesz chcieć, aby każdy użytkownik mógł uzyskać dostęp do tego samego udostępnionego kontenera bez konieczności logowania indywidualnego.
• Indywidualne uwierzytelnianie: połączenie A2A ponownie używa kontekstu użytkownika Microsoft Entra z przychodzącego żądania agenta lub prosi każdego użytkownika o ustanowienie oddzielnej sesji protokołu OAuth. Takie podejście jest niezbędne, gdy akcje powinny być ograniczone do uprawnień użytkownika. Na przykład, jeśli utworzysz agenta kodowania, który pobiera zatwierdzenia i żądania ściągnięcia z GitHub, każdy deweloper powinien zalogować się ze swojego konta na GitHubie, aby widzieć tylko repozytoria, do których mają dostęp.

Wymagania wstępne

Przed wybraniem metody uwierzytelniania potrzebne są następujące elementy:

• Dostęp do portalu Foundry i projektu. Jeśli go nie masz, zobacz Tworzenie projektów w narzędziu Foundry.

• Rola Użytkownika usługi Foundry lub wyższa w Twoim projekcie. Ta rola przyznaje uprawnienia do tworzenia połączeń projektu i konfigurowania agentów. Aby uzyskać szczegółowe informacje, zobacz Kontrola dostępu oparta na rolach w portalu Foundry.

  Ważne

  Niedawno zmieniono nazwy ról RBAC w usłudze Foundry. Użytkownik Foundry, właściciel Foundry, właściciel konta Foundry i menedżer projektu Foundry były wcześniej nazywane odpowiednio użytkownikiem Azure AI, właścicielem Azure AI, właścicielem konta Azure AI i menedżerem projektu Azure AI. Poprzednie nazwy mogą być nadal widoczne w niektórych miejscach, podczas gdy zmiana nazwy jest wdrażana. Identyfikatory ról i uprawnienia podstawowe są niezmienione przez zmianę nazwy.

• Adres URL punktu końcowego A2A, z którym chcesz nawiązać połączenie. Skontaktuj się z wydawcą punktu końcowego, aby potwierdzić, które metody uwierzytelniania obsługuje punkt końcowy.

• Poświadczenia wybranej metody uwierzytelniania:

  • Oparte na kluczu: klucz interfejsu API, prywatny token dostępu (PAT) lub inny tajny token od wydawcy punktu końcowego.
  • Uwierzytelnianie Microsoft Entra: Przypisania ról dla tożsamości agenta lub tożsamości zarządzanej projektu w podstawowej usłudze. Określone role zależą od usługi (na przykład Cosmos DB Data Reader dla Azure Cosmos DB).

Wybieranie metody uwierzytelniania

Wybrana metoda uwierzytelniania zależy od tego, czy potrzebujesz kontekstu współużytkowanego, czy indywidualnego użytkownika, oraz od protokołów uwierzytelniania, które obsługuje punkt końcowy A2A.

Skorzystaj z poniższej tabeli, aby wybrać odpowiednią metodę dla danego scenariusza:

Obsługiwane metody uwierzytelniania

Poniższa tabela zawiera podsumowanie metod uwierzytelniania dostępnych dla połączeń A2A:

Uwierzytelnianie oparte na kluczach

Użyj uwierzytelniania opartego na kluczach, gdy punkt końcowy A2A akceptuje klucz API, osobisty token dostępu (Personal Access Token) lub inne poufne poświadczenie. Aby zwiększyć bezpieczeństwo, przechowuj udostępnione poświadczenia w połączeniu projektowym zamiast przekazywania ich podczas uruchamiania.

Po połączeniu punktu końcowego A2A z agentem w portalu Foundry, Foundry automatycznie tworzy dla Ciebie połączenie projektu. Podaj nazwę poświadczeń (nazwę nagłówka HTTP) i wartość poświadczeń (wartość nagłówka). Format zależy od oczekiwanego punktu końcowego.

Typowe formaty poświadczeń:

Gdy agent wywołuje punkt końcowy A2A, Agent Service pobiera poświadczenia z połączenia projektu i dołącza je do nagłówków żądań.

Najlepsze rozwiązania w zakresie zabezpieczeń dotyczące uwierzytelniania opartego na kluczach

• Użyj poświadczeń o najniższych uprawnieniach: zażądaj tylko minimalnych uprawnień wymaganych dla zadań agenta.
• Regularnie obracaj tokeny: ustaw przypomnienie, aby ponownie wygenerować tokeny przed ich wygaśnięciem.
• Ogranicz dostęp do projektu: ogranicz, kto może uzyskiwać dostęp do projektów zawierających udostępnione wpisy tajne.
• Audyt wykorzystania poświadczeń: Monitorowanie dostępu do połączeń projektowych w dziennikach aktywności Azure.

delegowanie użytkownika klienta Microsoft Entra

Użyj delegowania użytkownika klienta Microsoft Entra, gdy wywołanie innego agenta usługi Foundry musi zachować kontekst użytkownika reprezentowanego przez klienta, który wywołał agenta źródłowego. To zachowanie różni się od wywołania A2A typu app-only, w którym agent wywołujący uwierzytelnia się przy użyciu tożsamości agenta bez delegowanego kontekstu użytkownika.

Istniejące integracje rozwiązania Foundry-to-Foundry mogą wykorzystywać UserEntraToken jako ścieżkę zgodności. Wartość „audience” tokenu przychodzącego punktu końcowego określa, czy usługa Foundry, czy tożsamość agenta żąda tokenu podrzędnego. Użyj tej opcji w przypadku istniejących integracji z agentami usługi Foundry.

Użyj AgentOnBehalfOfUser, gdy miejsce docelowe obsługuje tożsamość agenta działającą w imieniu użytkownika. Punkt końcowy agenta źródłowego musi używać schematu AgentBlueprint, a token przychodzący musi być przeznaczony dla schematu agenta źródłowego. Ten typ uwierzytelniania jest w wersji zapoznawczej.

Aby zapoznać się z modelem aktora, schematem punktów końcowych i wymaganiami dotyczącymi odbiorców tokenu, zgodą dla usług podrzędnych i migracją z UserEntraToken do AgentOnBehalfOfUser, zobacz Konfigurowanie delegowania użytkowników dla narzędzi w usłudze Microsoft Foundry.

Uwierzytelnianie Microsoft Entra ID

Użyj uwierzytelniania Microsoft Entra ID, gdy punkt końcowy A2A i jego podstawowa usługa akceptują tokeny Microsoft Entra ID. Ta metoda eliminuje konieczność zarządzania sekretami, ponieważ Azure automatycznie zajmuje się pozyskiwaniem i odnawianiem tokenów.

Ustaw projekt Foundry jako aktywny projekt przed utworzeniem połączenia A2A opartego na tożsamości:

PROJECT_ENDPOINT="https://<account>.services.ai.azure.com/api/projects/<project>"
azd ai project set "$PROJECT_ENDPOINT"

Tożsamość agenta

Użyj tożsamości agenta do uwierzytelniania się w punktach końcowych A2A, które obsługują uwierzytelnianie tożsamości agenta. Usługa agenta tworzy unikatowy identyfikator dla domyślnego wystąpienia agenta podczas tworzenia agenta. Tożsamość zaczyna bez uprawnień do zasobów podrzędnych.

Agenci starszego typu mogą używać identyfikatora udostępnionego projektu. Aby zapoznać się z bieżącym modelem tożsamości i starszymi wskazówkami dotyczącymi migracji, zobacz Pojęcia dotyczące tożsamości agenta w usłudze Microsoft Foundry.

Aby skonfigurować uwierzytelnianie tożsamości agenta:

1. Zidentyfikuj podstawową usługę, która obsługuje punkt końcowy A2A (na przykład Azure Cosmos DB lub Azure Storage).
2. Przypisz do tożsamości agenta w tej usłudze wymagane role. Określone role zależą od usługi i operacji, które musi wykonać agent.
3. Skonfiguruj połączenie A2A w celu korzystania z uwierzytelniania tożsamości agenta.

azd ai connection create my-a2a-connection \
  --kind remote-a2a \
  --target https://<a2a-endpoint> \
  --auth-type agentic-identity \
  --audience "<entra-audience>"

Gdy agent wywołuje punkt końcowy A2A, usługa agenta używa tożsamości agenta do żądania tokenu autoryzacji z Microsoft Entra ID i dołącza go do żądania.

Tożsamość zarządzana projektu Foundry

Użyj tożsamości zarządzanej projektu Foundry do uwierzytelniania za pomocą punktów końcowych A2A. Ta opcja jest przydatna, gdy chcesz, aby wszyscy agenci w projekcie współużytkować tę samą tożsamość na potrzeby uzyskiwania dostępu do zasobów.

Aby skonfigurować uwierzytelnianie za pomocą zarządzanej tożsamości projektu:

1. Zidentyfikuj podstawową usługę, która obsługuje punkt końcowy usługi A2A.
2. Przypisz wymagane role do tożsamości zarządzanej projektu w tej usłudze.
3. Skonfiguruj połączenie A2A, aby korzystać z uwierzytelniania za pomocą zarządzanej tożsamości projektu.

azd ai connection create my-a2a-connection \
  --kind remote-a2a \
  --target https://<a2a-endpoint> \
  --auth-type project-managed-identity \
  --audience "<entra-audience>"

Gdy agent wywołuje punkt końcowy A2A, usługa agenta używa tożsamości zarządzanej projektu do żądania tokenu autoryzacji z Microsoft Entra ID i dołącza go do żądania.

Przekazywanie tożsamości OAuth

Mechanizm przekazywania tożsamości OAuth pozwala agentowi działać w imieniu poszczególnych użytkowników. Użyj tej metody, gdy akcje powinny być ograniczone do uprawnień każdego użytkownika, takich jak uzyskiwanie dostępu do plików osobistych, repozytoriów lub innych chronionych zasobów.

Przekazywanie tożsamości OAuth działa z punktami końcowymi Microsoft i innymi niż Microsoft A2A, które obsługują protokół OAuth 2.0, w tym usługi korzystające z Microsoft Entra ID.

Jak działa przekazywanie tożsamości OAuth

1. Pierwsza interakcja: gdy użytkownik najpierw wchodzi w interakcję z agentem, usługa agenta generuje link zgody.
2. Zgoda użytkownika: użytkownik otwiera link, loguje się do usługi źródłowej i autoryzuje agenta do uzyskiwania dostępu do swoich danych.
3. Magazyn tokenów: Usługa Agenta bezpiecznie przechowuje tokeny OAuth użytkownika (token dostępu i token odświeżania). Te tokeny są ograniczone do tej konkretnej kombinacji użytkownika i agenta.
4. Kolejne żądania: gdy agent wywołuje punkt końcowy A2A, usługa agenta zawiera token dostępu użytkownika w żądaniu. Jeśli token dostępu wygaśnie, usługa agenta używa tokenu odświeżania do uzyskania nowego tokenu.

Typy tokenów OAuth

Protokół OAuth używa dwóch typów tokenów:

Zakresy protokołu OAuth określają, do czego agent może uzyskiwać dostęp i wykonywać w imieniu użytkownika. Zakresy określa się podczas konfigurowania połączenia, a użytkownik widzi je podczas przepływu zgody. Aby uzyskać więcej informacji na temat protokołu OAuth, zobacz dokumentację dotyczącą zabezpieczeń Microsoft.

Zarządzane uwierzytelnianie OAuth a niestandardowe uwierzytelnianie OAuth

Usługa agenta obsługuje dwie opcje konfiguracji protokołu OAuth:

Aby skonfigurować niestandardowy protokół OAuth, podaj następujące informacje:

• Identyfikator klienta: identyfikator aplikacji z rejestracji aplikacji OAuth.
• Klucz tajny klienta (jeśli jest to wymagane): wpis tajny skojarzony z rejestracją aplikacji.
• Adres URL autoryzacji: punkt, w którym użytkownicy autoryzują dostęp.
• Adres URL tokenu: punkt końcowy, w którym usługa agenta wymienia kod autoryzacji dla tokenów.
• Adres URL odświeżania: punkt końcowy służący do odświeżania wygasłych tokenów dostępu.
• Scopes: Uprawnienia wymagane przez agenta (na przykład repo dla GitHub lub Files.Read dla Microsoft Graph).

Dostęp niezwierzytelniony

Używaj nieuwierzytelnionego dostępu tylko wtedy, gdy punkt końcowy A2A jest publicznie dostępny i nie wymaga uwierzytelniania. Ta opcja jest rzadka w scenariuszach produkcyjnych, ale może być odpowiednia dla:

• Publiczne interfejsy API, które nie wymagają uwierzytelniania
• Wewnętrzne punkty końcowe programowania lub testowania
• Punkty końcowe chronione przez zabezpieczenia na poziomie sieci (takie jak prywatne punkty końcowe) zamiast uwierzytelniania

Konfigurowanie uwierzytelniania dla połączenia A2A

Wykonaj następujące kroki, aby skonfigurować uwierzytelnianie dla połączenia A2A:

1. Zidentyfikuj punkt końcowy A2A i obsługiwane metody uwierzytelniania. Skontaktuj się z wydawcą punktu końcowego lub sprawdź dokumentację punktu końcowego, aby określić, które metody uwierzytelniania są obsługiwane.

2. Zbierz wymagane poświadczenia na podstawie wybranej metody uwierzytelniania:

   • oparte na kluczach: uzyskaj klucz API lub token od wydawcy interfejsu końcowego.
   • Microsoft Entra ID: Zidentyfikuj wymagane przypisania ról dla podstawowej usługi.
   • Microsoft Entra delegowanie użytkownika klienta/aplikacji: upewnij się, że obiekt docelowy obsługuje wybrany delegowany typ uwierzytelniania, odbiorców i uprawnienia.
   • OAuth: określ, czy zarządzany OAuth jest dostępny, lub zbierz szczegóły niestandardowej rejestracji aplikacji OAuth.

3. Utwórz połączenie projektu w portalu Foundry. Połączenie przechowuje adres URL punktu końcowego A2A, metodę uwierzytelniania i poświadczenia.

   • Aby uzyskać ogólne wskazówki dotyczące połączenia, zobacz Dodawanie nowego połączenia do projektu.
   • Aby uzyskać informacje o konfiguracji specyficznej dla A2A, zobacz Dodaj punkt końcowy agenta A2A do usługi Foundry Agent Service.

4. Konfigurowanie uwierzytelniania:

   • W przypadku uwierzytelniania aplikacji przypisz wymagane role do tożsamości agenta lub tożsamości zarządzanej projektu w usłudze podstawowej.
   • W przypadku delegowania użytkownika klienta w Microsoft Entra należy wykonać autoryzację dla usługi podrzędnej wymaganą dla agenta i użytkownika.

5. Dodaj narzędzie A2A do swojego agenta. Odwołaj się do utworzonego połączenia projektu i skonfiguruj narzędzia z punktu końcowego A2A, które agent może wywołać.

Poświadczenia żądania karty agenta

Zanim agent będzie mógł wywołać punkt końcowy A2A, Agent Service pobiera kartę zdalnego agenta. Niezależnie od wybranej metody uwierzytelniania domyślnie ma ona zastosowanie tylko do wywołań narzędzi, więc żądanie pobrania karty agenta jest wysyłane anonimowo. Większość punktów końcowych udostępnia kartę agenta publicznie, dzięki czemu pobranie się udaje.

Niektóre punkty końcowe chronią samą ścieżkę karty agenta i odrzucają nieuwierzytelnione żądania. Dla tych punktów końcowych ustaw wartość send_credentials_for_agent_card na true w definicji narzędzia A2A. Następnie usługa agenta wysyła poświadczenia połączenia w ramach żądania karty agenta, a także w późniejszych wywołaniach narzędzia.

{
  "type": "a2a",
  "a2a_version": "1.0",
  "base_url": "https://<a2a-endpoint>",
  "project_connection_id": "<connection-id>",
  "send_credentials_for_agent_card": true
}

Właściwość send_credentials_for_agent_card jest opcjonalna i domyślnie ma wartość false, więc istniejące narzędzia nadal anonimowo pobierają kartę agenta.

Poświadczenia są przesyłane wyłącznie do hosta w base_url i wyłącznie przez HTTPS. Jeśli punkt końcowy używa protokołu HTTP lub jeśli ustawisz opcjonalną agent_card_path właściwość na pełny adres URL na innym hoście, usługa agenta ignoruje to ustawienie i pobiera kartę agenta anonimowo.

Weryfikowanie uwierzytelniania

Po skonfigurowaniu uwierzytelniania przetestuj połączenie, aby potwierdzić, że działa poprawnie.

Weryfikowanie uwierzytelniania opartego na kluczach lub Microsoft Entra ID

1. Otwórz swojego "agenta" w portalu Foundry.
2. Rozpocznij konwersację i wyzwól akcję, która wywołuje narzędzie A2A.
3. Potwierdź pomyślne zakończenie wywołania narzędzia. Jeśli wywołanie nie powiedzie się, sprawdź komunikat o błędzie i zobacz Rozwiązywanie problemów.

Weryfikowanie delegowania klienta Microsoft Entra przez użytkownika

1. Wywołaj agenta źródłowego za pośrednictwem schematu autoryzacji punktu końcowego i grupy odbiorców tokenu wymaganych przez wybrany typ uwierzytelniania.
2. Wyzwalaj akcję, która wywołuje agenta docelowego.
3. Upewnij się, że element docelowy otrzymuje delegowany dostęp dla zamierzonego użytkownika i aktora.
4. Przetestuj z innym użytkownikiem, aby potwierdzić, że autoryzacja pozostaje odizolowana dla każdego użytkownika.

Weryfikowanie przekazywania tożsamości protokołu OAuth

1. Otwórz swojego agenta w portalu Foundry za pomocą konta użytkownika testowego, dla którego wcześniej nie udzielono zgody.
2. Rozpocznij konwersację i wyzwól akcję, która wywołuje narzędzie A2A.
3. Upewnij się, że link zgody jest wyświetlany w odpowiedzi agenta.
4. Otwórz link zgody i zaloguj się przy użyciu poświadczeń użytkownika testowego.
5. Autoryzuj żądane uprawnienia.
6. Wróć do agenta i uruchom ponownie narzędzie A2A.
7. Potwierdź pomyślne zakończenie wywołania narzędzia przy użyciu poświadczeń użytkownika testowego.
8. (Opcjonalnie) Przetestuj przy użyciu innego konta użytkownika, aby potwierdzić, że przepływy zgody działają dla wielu użytkowników.

Rozwiązywanie problemów

Skorzystaj z poniższej tabeli, aby zdiagnozować i rozwiązać typowe problemy z uwierzytelnianiem:

Powiązana zawartość

• Dodanie punktu końcowego agenta A2A do usługi agenta Foundry: Przewodnik krok po kroku dotyczący konfigurowania narzędzia A2A dla agenta.
• Agent identity concepts in Microsoft Foundry: Dowiedz się, jak działają tożsamości agentów i ich cykl życia.
• Kontrola dostępu oparta na rolach dla Microsoft Foundry: Omówienie ról i uprawnień dostępnych w narzędziu Foundry.
• Dodaj nowe połączenie do projektu: ogólne wskazówki dotyczące tworzenia połączeń projektu.