Agent Card: karta możliwości agenta w A2A

Agent Card to karta możliwości agenta działającego w protokole Agent2Agent, czyli A2A. Jest dokumentem JSON publikowanym przez serwer agenta, zwykle pod przewidywalnym adresem w katalogu .well-known. Zamiast kazać każdej integracji ręcznie zgadywać, co robi zewnętrzny agent i jak się z nim połączyć, karta podaje podstawowe informacje w jednym ustandaryzowanym formacie. To mechanizm odkrywania, nie panel marketingowy. Klient A2A czyta kartę po to, aby ocenić, czy agent pasuje do zadania i jakie warunki musi spełnić przed rozpoczęciem współpracy.

Dobra Agent Card opisuje co najmniej nazwę, opis i wersję agenta, jego endpointy oraz interfejsy protokołu. Zawiera też listę umiejętności, czyli konkretnych spraw, które agent umie obsłużyć. Umiejętność może mieć własny identyfikator, opis, tagi, przykładowe pytania oraz obsługiwane typy wejścia i wyjścia. Karta deklaruje również możliwości takie jak streaming, powiadomienia o postępie lub rozszerzona karta agenta. Dzięki temu klient nie musi zakładać, że każda usługa przyjmie plik, odpowie w JSON albo utrzyma długie zadanie researchowe.

Najważniejsze rozróżnienie brzmi: Agent Card mówi, co agent deklaruje, a nie co wolno mu zrobić w Twoim systemie. Nie należy traktować opisu umiejętności jako zgody na dostęp do CRM, poczty czy plików klienta. Przed delegacją klient powinien sprawdzić adres usługi, wymagany schemat uwierzytelnienia, zakres tokenu oraz własne reguły dostępu. Jeżeli agent ma przygotować analizę oferty, wyślij tylko materiały niezbędne do tej analizy. Jeżeli ma wykonać akcję zewnętrzną, potrzebuje dodatkowej, egzekwowanej po stronie serwera polityki i, gdy ryzyko jest wysokie, zatwierdzenia człowieka.

Praktyczny przykład dla eksperta: system obsługi zapytań ma agenta koordynującego i osobnego agenta od analizy briefów. Koordynator najpierw pobiera Agent Card analityka. Widzi w niej umiejętność „analiza briefu”, obsługę plików PDF oraz zwrotu ustrukturyzowanego wyniku, ale brak możliwości wysyłania e-maili. Dopiero wtedy przekazuje zanonimizowany brief i prosi o listę luk oraz pytania doprecyzowujące. Wynik trafia z powrotem do koordynatora jako artefakt, a wiadomość do klienta nadal powstaje i czeka na akceptację w głównym systemie. Role są jasne, a granica działania każdego agenta jest widoczna.

Agent Card nie zastępuje MCP. A2A służy temu, by niezależne agenty odnalazły się, ustaliły sposób komunikacji i wspólnie prowadziły zadanie. MCP opisuje z kolei, jak agent korzysta z narzędzi, danych i zasobów. W jednym procesie agent koordynujący może znaleźć analityka przez jego Agent Card, zlecić mu zadanie przez A2A, a analityk może wewnątrz swojej usługi użyć MCP do odczytania dozwolonej bazy wiedzy. Łączenie tych pojęć prowadzi do błędu projektowego: karta A2A nie jest katalogiem wszystkich uprawnień narzędziowych ani automatycznym dostępem do danych.

Przy tworzeniu karty zacznij od wąskiego, testowalnego zakresu. Nazwij umiejętność według wyniku, nie według wewnętrznej technologii, na przykład „wyciąga dane z briefu” zamiast „agent LangGraph”. Dodaj krótki opis, przykładowe wejście i dokładne formaty, które przyjmujesz oraz zwracasz. Podaj tylko rzeczywiście dostępne endpointy i wymagania bezpieczeństwa. Jeżeli funkcja jest eksperymentalna, nie deklaruj jej jako stabilnej. Wersjonuj kartę wraz ze zmianą kontraktu, aby klient mógł wykryć, że poprzedni format lub umiejętność przestały obowiązywać.

Najczęstszy błąd to karta z szeroką, nieprecyzyjną obietnicą typu „pomagam w biznesie”. Taki opis nie daje klientowi podstawy do bezpiecznej delegacji ani nie pozwala wybrać właściwego agenta. Drugi błąd to publikowanie danych wrażliwych: sekretów, wewnętrznych nazw środowisk, adresów paneli administracyjnych lub szczegółów, które ułatwiają atak. Karta ma być publicznym opisem interfejsu. Sekrety zostają poza nią, a wymagania autoryzacji muszą być jasne. Trzeci błąd to uznanie deklarowanych zdolności za wystarczającą kontrolę. Każde wywołanie nadal wymaga walidacji danych, limitów oraz obserwowalnego śladu.

Dla soloprzedsiębiorcy Agent Card ma sens dopiero wtedy, gdy istnieje co najmniej jeden realny agent lub usługa, którą inny system ma odnajdywać i używać. Nie buduj jej tylko dlatego, że A2A jest modne. Najpierw ustal jedno powtarzalne zadanie, jego wejście, oczekiwany wynik i granice odpowiedzialności. Następnie opublikuj minimalną kartę, przetestuj jej odczyt z oddzielnego klienta i sprawdź odmowę dostępu bez właściwego tokenu. Jeśli nie potrzebujesz współpracy między niezależnymi agentami, prostszy kontrakt API albo pojedynczy workflow będzie tańszy w utrzymaniu i łatwiejszy do audytu.