Jak udostępnić katalog firm agentom AI przez uporządkowany interfejs

Agent AI nie przegląda katalogu firm tak jak człowiek. Nie przesuwa mapy, nie domyśla się znaczenia ikon i nie analizuje kilkunastu podstron, żeby ustalić, czy hydraulik z Gdańska obsługuje awarie w niedzielę. Potrzebuje danych, które można jednoznacznie odczytać, filtrować i porównać.

Dlatego katalog z atrakcyjnym interfejsem, ale bez uporządkowanej warstwy danych, pozostaje dla agenta zbiorem przypadkowych tekstów. Model może znaleźć nazwę firmy, lecz pomyli oddział z centralą, uznać nieaktualny numer telefonu za obowiązujący albo polecić usługodawcę spoza wskazanego obszaru. Problemem nie jest brak sztucznej inteligencji. Problemem jest brak jednego, stabilnego sposobu dostępu do informacji.

Najpierw uporządkuj rekord firmy, dopiero później buduj interfejs

Najczęstszy błąd pojawia się jeszcze przed uruchomieniem API: katalog przechowuje dane w formie przygotowanej do wyświetlenia, a nie do dalszego wykorzystania. Nazwa, miasto, kategoria i numer telefonu trafiają do jednego pola tekstowego albo występują w kilku sprzecznych wersjach.

Agent potrzebuje osobnych, jednoznacznie opisanych pól. Minimalny rekord firmy powinien zawierać:

• trwały identyfikator, który nie zmieni się po korekcie nazwy lub adresu;
• pełną nazwę rejestrową oraz opcjonalną nazwę handlową;
• kategorię główną i kategorie dodatkowe zapisane według jednej kontrolowanej listy;
• ulicę, numer budynku, numer lokalu, kod pocztowy, miejscowość i kraj w oddzielnych polach;
• współrzędne geograficzne;
• numer telefonu zapisany w formacie międzynarodowym, na przykład +48 501 234 567;
• adres strony internetowej;
• godziny otwarcia rozpisane na poszczególne dni;
• obszar obsługi, jeżeli firma dojeżdża do klientów;
• listę usług wraz z krótkimi opisami;
• status rekordu, na przykład active, temporarily_closed lub permanently_closed;
• datę ostatniej weryfikacji;
• źródło informacji i sposób jej potwierdzenia.

Nazwa, adres i telefon, czyli dane NAP, nie mogą być przechowywane jako jeden ciąg znaków. Jeżeli agent ma znaleźć firmy w kodzie pocztowym 00-001, odróżnić lokal przy ulicy Długiej 12 od lokalu przy Długiej 12A albo posortować wyniki według odległości, każde pole musi być dostępne oddzielnie.

Tak samo należy potraktować kategorie. Wprowadzenie przez użytkowników dowolnych określeń prowadzi do sytuacji, w której katalog zawiera jednocześnie „mechanika”, „warsztat samochodowy”, „serwis aut” i „naprawę samochodów”. Człowiek rozumie, że chodzi o podobne usługi. System filtrujący już niekoniecznie. Rozwiązaniem jest kontrolowany słownik kategorii oraz tabela synonimów używana podczas wyszukiwania.

Przy większym katalogu przydaje się struktura hierarchiczna:

• motoryzacja;
• serwis samochodowy;
• serwis opon;
• wulkanizacja mobilna.

Firma może należeć do kilku kategorii, ale jedna powinna być oznaczona jako główna. Bez tego wyniki zapytań stają się chaotyczne, a agent nie wie, czy wpis jest wyspecjalizowanym zakładem, czy firmą oferującą daną usługę tylko dodatkowo.

Trzeba też rozdzielić dane deklarowane przez firmę od danych zweryfikowanych przez operatora katalogu. Pole verified: true jest niewystarczające, jeżeli nie wiadomo, czego dotyczy weryfikacja i kiedy ją przeprowadzono. Lepszy model przechowuje osobno status telefonu, adresu, strony internetowej oraz godzin otwarcia.

To rozwiązanie zwiększa liczbę pól i komplikuje panel administracyjny. Jest to realna niedogodność. Import prostego pliku CSV trwa dłużej, a migracja starego katalogu może ujawnić tysiące niepełnych rekordów. Mimo to warto wykonać tę pracę przed budową integracji. API nie naprawia złych danych — udostępnia je szybciej i na większą skalę.

Udostępnij dane przez API zaprojektowane pod konkretne pytania

Najbardziej uniwersalnym punktem dostępu pozostaje API HTTP zwracające JSON. Nie trzeba od razu budować rozbudowanej platformy. Pierwsza wersja powinna obsługiwać kilka operacji odpowiadających rzeczywistym pytaniom użytkowników.

Praktyczne minimum obejmuje:

GET /companies/{id}
Zwraca pełny, aktualny rekord jednej firmy.

GET /companies?city=Poznan&category=dentist
Wyszukuje firmy według lokalizacji i kategorii.

GET /companies?lat=52.4064&lon=16.9252&radius=5000
Zwraca wyniki w promieniu pięciu kilometrów od wskazanego punktu.

GET /companies?service=awaryjne-otwieranie&open_at=2026-08-01T22:00:00+02:00
Pozwala znaleźć firmę oferującą konkretną usługę i działającą o wskazanej godzinie.

GET /companies/changes?updated_after=2026-07-31T00:00:00Z
Udostępnia rekordy zmienione od określonego momentu, dzięki czemu integrator nie musi pobierać całego katalogu.

Odpowiedź nie powinna zawierać wyłącznie listy firm. Potrzebne są również informacje o liczbie wyników, zastosowanych filtrach, paginacji i czasie wygenerowania danych. Przykładowa struktura może wyglądać następująco:

{
  "data": [
    {
      "id": "pl-poznan-18452",
      "name": "Serwis Rowerowy Mostowa",
      "category": {
        "id": "bicycle_repair",
        "label": "Serwis rowerowy"
      },
      "address": {
        "street": "Mostowa",
        "building": "14",
        "postal_code": "61-854",
        "city": "Poznań",
        "country": "PL"
      },
      "geo": {
        "latitude": 52.4059,
        "longitude": 16.9381
      },
      "phone": "+48612345678",
      "status": "active",
      "verified_at": "2026-07-18T09:30:00Z"
    }
  ],
  "meta": {
    "page": 1,
    "page_size": 20,
    "total": 47,
    "generated_at": "2026-08-01T13:10:00Z"
  }
}

Dokumentację interfejsu najlepiej opisać w standardzie OpenAPI. Dzięki temu można automatycznie wygenerować dokumentację, biblioteki klienckie i testy zgodności. Schemat musi jednak określać nie tylko typ pola, lecz również jego znaczenie. Informacja, że radius jest liczbą, nie wystarcza. Trzeba dopisać, czy wartość oznacza metry czy kilometry, jaki jest jej maksymalny poziom i co dzieje się po jego przekroczeniu.

W publicznym katalogu sensowny limit początkowy to zazwyczaj 60–120 zapytań na minutę dla jednego klucza API. Dla partnerów pobierających większe paczki danych można przygotować oddzielny limit, na przykład 5–20 tys. zapytań dziennie albo eksport okresowy. Są to parametry operacyjne, nie uniwersalny standard. Należy je ustalić na podstawie wielkości rekordów, kosztu wyszukiwania geograficznego oraz realnego obciążenia serwera.

Każda odpowiedź powinna mieć przewidywalne kody błędów:

• 400 — niepoprawne parametry;
• 401 — brak prawidłowego uwierzytelnienia;
• 403 — brak dostępu do danego zakresu danych;
• 404 — firma lub zasób nie istnieje;
• 409 — konflikt operacji;
• 429 — przekroczony limit zapytań;
• 500 lub 503 — błąd albo czasowa niedostępność usługi.

Nie należy zwracać komunikatu „Something went wrong”. Agent nic z nim nie zrobi. Błąd powinien zawierać stabilny kod, opis oraz wskazanie problematycznego pola, na przykład INVALID_RADIUS albo UNSUPPORTED_CATEGORY.

Koszt wykonania prostego, tylko do odczytu API dla istniejącej bazy zwykle mieści się w granicach 40–120 godzin pracy programistycznej. Przy stawkach około 180–300 zł netto za godzinę daje to orientacyjnie 7–36 tys. zł netto. Kwota rośnie, gdy trzeba wcześniej oczyścić dane, wdrożyć wyszukiwanie geograficzne, zbudować panel zarządzania kluczami albo zapewnić gwarantowaną dostępność. Sama dokumentacja i testy integracyjne potrafią zająć 20–30% całego czasu.

Dodaj warstwę dla agentów, ale nie rezygnuj ze zwykłego API

REST API rozwiązuje problem dostępu do danych, lecz agent nadal musi wiedzieć, jakie operacje może wykonać. Można mu to ułatwić, udostępniając katalog jako zestaw jasno opisanych narzędzi.

Przykładowe operacje to:

• search_companies — wyszukiwanie firm według kategorii, lokalizacji, promienia i godzin działania;
• get_company — pobranie szczegółów konkretnej firmy;
• compare_companies — zwrócenie porównywalnych parametrów kilku wpisów;
• get_company_services — pobranie usług, cen orientacyjnych i warunków realizacji;
• report_incorrect_data — przesłanie zgłoszenia o nieaktualnym adresie, telefonie lub statusie firmy.

Takie narzędzia można wystawić przez Model Context Protocol, czyli otwarty sposób łączenia aplikacji opartych na modelach językowych z zewnętrznymi danymi i funkcjami. Narzędzie powinno mieć jednoznaczną nazwę, opis działania i schemat argumentów. Agent otrzymuje wtedy informację, że parametr radius_meters przyjmuje liczbę całkowitą, a open_at wymaga daty z uwzględnieniem strefy czasowej.

Nie należy jednak traktować MCP jako zamiennika całej infrastruktury. Protokół jest warstwą integracyjną. Źródłem prawdy nadal powinna być baza oraz stabilne API, z którego mogą korzystać również aplikacje mobilne, partnerzy, porównywarki i wewnętrzny panel operatora.

Drugim kanałem jest Schema.org w formacie JSON-LD umieszczone na publicznych stronach firm. Dla lokalnego przedsiębiorstwa właściwym punktem wyjścia jest typ LocalBusiness albo dokładniejszy typ branżowy. W danych można oznaczyć między innymi nazwę, adres, współrzędne, telefon, godziny otwarcia i adres strony.

JSON-LD pomaga maszynom zrozumieć pojedynczą podstronę, ale nie zastępuje interfejsu wyszukiwania. Agent może odczytać dane firmy, której stronę już znalazł. Nie wykona jednak sprawnie zapytania o wszystkie czynne apteki w promieniu trzech kilometrów, jeżeli musiałby wcześniej pobrać i przeanalizować tysiące podstron.

W praktyce warto utrzymywać trzy poziomy dostępu:

1. JSON-LD na stronie firmy — do identyfikacji pojedynczego podmiotu.
2. API wyszukiwawcze — do filtrowania, sortowania i pobierania danych.
3. narzędzia dla agentów — do wykonywania jasno zdefiniowanych operacji.

Najwięcej problemów sprawia synchronizacja tych warstw. Godziny otwarcia zmienione w panelu nie mogą być aktualizowane tylko na stronie HTML, podczas gdy API nadal zwraca starą wartość. Wszystkie kanały powinny korzystać z tej samej bazy lub wspólnej usługi danych.

Konieczna jest również kontrola bezpieczeństwa. Narzędzie wyszukujące można udostępnić dość szeroko, ale funkcji zmieniających rekord nie wolno pozostawiać bez silnego uwierzytelnienia, walidacji i dziennika operacji. Agent nie powinien mieć prawa do automatycznego zatwierdzania zmian tylko dlatego, że zgłoszenie wygląda wiarygodnie.

W katalogach jednoosobowych działalności trzeba uważać na dane osobowe. Publiczny charakter wpisu nie oznacza, że można bez ograniczeń rozpowszechniać prywatny numer telefonu, adres zamieszkania właściciela albo dane historyczne. Zakres API należy ograniczyć do informacji potrzebnych do wyszukiwania i kontaktu, zgodnie z celem katalogu. Pełny eksport bazy powinien mieć ostrzejsze warunki niż pojedyncze wyszukiwanie.

FAQ

Czy plik robots.txt wystarczy, aby agent AI korzystał z katalogu?
Nie. robots.txt może określać zasady dostępu robotów do określonych części serwisu, ale nie opisuje struktury rekordów ani dostępnych operacji wyszukiwania.

Czy trzeba wdrażać MCP od pierwszej wersji projektu?
Nie. Najpierw należy uporządkować dane i uruchomić stabilne API. Warstwę MCP warto dodać wtedy, gdy podstawowe zapytania są już przetestowane, a zespół potrafi kontrolować uprawnienia, limity i wersjonowanie.

Jak często weryfikować dane firm?
Numer telefonu, status działalności i adres dobrze jest sprawdzać co 90–180 dni. Godziny otwarcia powinny mieć oddzielną procedurę przed świętami. Rekord nieweryfikowany przez ponad rok warto oznaczyć niższym poziomem zaufania.

Czy agent powinien otrzymywać wszystkie dane przechowywane w katalogu?
Nie. Powinien dostawać wyłącznie pola potrzebne do wykonania konkretnej operacji. Dane administracyjne, historia moderacji, prywatne adresy e-mail i techniczne notatki operatora nie powinny trafiać do publicznej odpowiedzi.

Jak obsłużyć firmy mające kilka oddziałów?
Każdy oddział powinien być osobnym rekordem z własnym identyfikatorem, adresem, współrzędnymi, telefonem i godzinami otwarcia. Oddziały można połączyć polem wskazującym wspólną organizację nadrzędną.

Czy można obiecać, że katalog pojawi się w odpowiedziach wszystkich agentów AI?
Nie. Uporządkowanie danych zwiększa możliwość poprawnego odczytu i integracji, ale nie gwarantuje wykorzystania katalogu przez konkretny model lub usługę. Dostawca agenta sam decyduje, z jakich źródeł korzysta.

Od czego zacząć wdrożenie?
Najpierw pobierz losową próbę 100 aktywnych wpisów i sprawdź pięć pól: nazwę, adres, telefon, kategorię oraz datę ostatniej weryfikacji. Jeżeli więcej niż 5–10 rekordów zawiera sprzeczne, niepełne albo nieaktualne dane, nie zaczynaj od MCP ani nowego endpointu. Najpierw usuń błędy w modelu danych i procesie aktualizacji. To one będą później powielane przez każdego podłączonego agenta.

Więcej na ten temat na stronie: wizytówki NAP – poadresie.pl