Masz API. Agent chce je wywołać. Jak agent wie jakie endpointy istnieją, jakie parametry przyjmują, co zwracają, jakie są kody błędów? Mógłbyś napisać dokumentację w Wordzie — agent nie przeczyta. Mógłbyś napisać wiki — agent nie sparsuje. Możesz napisać OpenAPI schema — agent rozumie natywnie.
Czym jest OpenAPI schema
OpenAPI schema (wcześniej Swagger) to ustandaryzowany format opisu API REST w YAML lub JSON — definiujący endpointy, parametry, typy danych, kody odpowiedzi i autoryzację w maszynie-czytelny sposób — pozwalający agentom AI automatycznie odkryć możliwości API i wywołać je poprawnie bez wcześniejszej wiedzy o jego strukturze.
Dlaczego agenty kochają OpenAPI
Agent który chce wywołać API bez OpenAPI musi zgadywać. Jaki jest URL endpointu? Jakie parametry są wymagane? Jaki format daty? Co zwraca w przypadku błędu? To jest trial and error który kosztuje tokeny, czas i może produkować błędy.
Agent który ma dostęp do OpenAPI schema wie wszystko: GET /products?category={category}&limit={limit} zwraca array of Product objects z polami id, name, price, available. Wywołanie jest deterministyczne i poprawne za pierwszym razem.
MCP integruje się naturalnie z OpenAPI — istnieją narzędzia które automatycznie generują serwer MCP z OpenAPI schema. Każdy endpoint API staje się narzędziem MCP bez ręcznego kodowania.
OpenAPI a agent-readiness
API bez OpenAPI schema jest dla agentów jak strona bez semantycznego HTML — dostępne, ale wymaga zgadywania. API z OpenAPI schema jest pierwszorzędnie agent-ready.
Dla właściciela strony który ma custom API (sklep z własnym backendem, system rezerwacji, CRM): dodanie OpenAPI schema to jeden YAML plik który zmienia API z „trudne dla agentów” w „natywnie agent-ready”. Swagger UI lub Redoc generuje też automatycznie dokumentację dla ludzi z tego samego pliku.
Swagger UI jako discovery
Wiele serwisów publikuje Swagger UI pod /api-docs lub /swagger — interaktywna dokumentacja API wygenerowana z OpenAPI schema. Agenty mogą pobierać OpenAPI schema bezpośrednio z /openapi.json lub /swagger.json i dynamicznie odkrywać dostępne narzędzia.
OpenAPI w NLWeb
NLWeb /ask endpoint może być opisany przez OpenAPI schema — definiując że endpoint przyjmuje parametr `q` (query string) i zwraca JSON z tablicą wyników. To pozwala agentom które rozumieją OpenAPI automatycznie zintegrować się z NLWeb endpoint bez dodatkowej konfiguracji.