Przewodnik po zrozumieniu, budowaniu i optymalizacji agentów wywołujących API

Rola sztucznej inteligencji w firmach technologicznych szybko ewoluuje; przypadki użycia AI ewoluowały od pasywnego przetwarzania informacji do proaktywnych agentów zdolnych do wykonywania zadań. Według badania z marca 2025 r. na temat globalnej adopcji AI przeprowadzonego przez Gruziński i NewtonXWedług doniesień 91% kadry kierowniczej ds. technicznych w przedsiębiorstwach na etapie wzrostu i dużych przedsiębiorstwach korzysta lub planuje korzystać z agentowej sztucznej inteligencji.

Agenci wywołujący API są głównym przykładem tego przejścia na agentów. Agenci wywołujący API wykorzystują duże modele językowe (LLM) do interakcji z systemami oprogramowania za pośrednictwem interfejsów programowania aplikacji (API).

Na przykład, tłumacząc polecenia języka naturalnego na precyzyjne wywołania API, agenci mogą pobierać dane w czasie rzeczywistym, automatyzować rutynowe zadania, a nawet kontrolować inne systemy oprogramowania. Ta możliwość przekształca agentów AI w użytecznych pośredników między ludzkimi intencjami a funkcjonalnością oprogramowania.

Firmy wykorzystują obecnie agentów wywołujących API w różnych domenach, w tym:

• Aplikacje konsumenckie: Asystenci tacy jak Siri firmy Apple czy Alexa firmy Amazon zostali zaprojektowani w celu uproszczenia codziennych zadań, takich jak sterowanie inteligentnymi urządzeniami domowymi i dokonywanie rezerwacji.
• Przepływy pracy w przedsiębiorstwie: Przedsiębiorstwa wdrażają agentów API w celu automatyzacji powtarzalnych zadań, takich jak pobieranie danych z systemów CRM, generowanie raportów lub konsolidacja informacji z systemów wewnętrznych.
• Pobieranie i analiza danych: Przedsiębiorstwa wykorzystują agentów API w celu uproszczenia dostępu do zastrzeżonych zestawów danych, zasobów opartych na subskrypcji i publicznych interfejsów API w celu generowania spostrzeżeń.

W tym artykule zastosuję podejście skoncentrowane na inżynierii do zrozumienia, budowania i optymalizacji agentów wywołujących API. Materiał w tym artykule opiera się częściowo na praktycznych badaniach i rozwoju prowadzonych przez Georgian's AI Lab. Motywującym pytaniem dla większości badań AI Lab w obszarze agentów wywołujących API było: „Jeśli organizacja ma API, jaki jest najskuteczniejszy sposób zbudowania agenta, który może komunikować się z tym API za pomocą języka naturalnego?”

Wyjaśnię, jak działają agenci wywołujący API i jak skutecznie projektować i konstruować tych agentów pod kątem wydajności. Na koniec przedstawię systematyczny przepływ pracy, którego zespoły inżynieryjne mogą używać do implementacji agentów wywołujących API.

I. Kluczowe definicje:

• API lub interfejs programowania aplikacji: Zbiór reguł i protokołów umożliwiający różnym aplikacjom komunikowanie się i wymianę informacji.
• Agent: System sztucznej inteligencji (AI) zaprojektowany do postrzegania otoczenia, podejmowania decyzji i wykonywania działań w celu osiągnięcia określonych celów.
• Agent wywołujący API: Specjalistyczny agent AI, który tłumaczy instrukcje w języku naturalnym na precyzyjne wywołania API.
• Agent generujący kod: System AI wspomagający rozwój oprogramowania poprzez pisanie, modyfikowanie i debugowanie kodu. Choć to powiązane, skupiam się tutaj głównie na agentach, którzy wezwanie API, choć sztuczna inteligencja również może pomóc budować tych agentów.
• MCP (protokół kontekstu modelu): Protokół, w szczególności opracowane przez Anthropicdefiniując w jaki sposób LLM może łączyć się z zewnętrznymi narzędziami i źródłami danych oraz wykorzystywać je.

II. Główne zadanie: tłumaczenie języka naturalnego na działania API

Podstawową funkcją agenta wywołującego API jest interpretacja żądania użytkownika w języku naturalnym i konwersja go na jedno lub więcej precyzyjnych wywołań API. Proces ten zazwyczaj obejmuje:

1. Rozpoznawanie intencji: Zrozumienie celu użytkownika, nawet jeśli jest on wyrażony niejednoznacznie.
2. Wybór narzędzi: Określenie odpowiednich punktów końcowych interfejsu API — lub „narzędzi” — spośród zestawu dostępnych opcji, które mogą spełnić zamierzenie.
3. Ekstrakcja parametrów: Identyfikowanie i wyodrębnianie niezbędnych parametrów dla wybranych wywołań API z zapytania użytkownika.
4. Wykonywanie i generowanie odpowiedzi: Wykonywanie wywołań API, odbieranie odpowiedzi, a następnie syntetyzowanie tych informacji w spójną odpowiedź lub wykonywanie kolejnej czynności.

Rozważmy prośbę w stylu: „Hej Siri, jaka jest dzisiaj pogoda?”. Agent musi zidentyfikować potrzebę wywołania interfejsu API pogody, ustalić bieżącą lokalizację użytkownika (lub umożliwić określenie lokalizacji), a następnie sformułować wywołanie interfejsu API w celu pobrania informacji o pogodzie.

Przykładowe wywołanie API w przypadku zapytania „Hej Siri, jaka jest dziś pogoda?” może wyglądać następująco:

GET /v1/weather?location=Nowy%20Jork&units=metryczny

Proces tłumaczenia wiąże się początkowo z pewnymi wyzwaniami wysokiego poziomu, w tym niejednoznacznością języka naturalnego i koniecznością zachowania kontekstu przez agenta podczas wieloetapowych interakcji.

Na przykład agent musi często „pamiętać” poprzednie części konwersacji lub wcześniejsze wyniki wywołań API, aby poinformować o bieżących działaniach. Utrata kontekstu jest powszechnym trybem awarii, jeśli nie jest jawnie zarządzana.

III. Architektura rozwiązania: kluczowe komponenty i protokoły

Tworzenie efektywnych agentów wywołujących API wymaga strukturalnego podejścia architektonicznego.

1. Definiowanie „narzędzi” dla agenta

Aby LLM mógł korzystać z API, jego możliwości muszą zostać opisane w sposób dla niego zrozumiały. Każdy punkt końcowy lub funkcja API jest często przedstawiana jako „narzędzie”. Solidna definicja narzędzia obejmuje:

• Przejrzysty, naturalny opis przeznaczenia i funkcjonalności narzędzia.
• Dokładna specyfikacja parametrów wejściowych (nazwa, typ, informacja, czy są wymagane czy opcjonalne, oraz opis).
• Opis wyników lub danych zwracanych przez narzędzie.

2. Rola protokołu kontekstu modelu (MCP)

MCP jest krytycznym czynnikiem umożliwiającym bardziej ujednolicone i solidne korzystanie z narzędzi przez LLM. Zapewnia ustrukturyzowany format definiowania sposobu, w jaki modele mogą łączyć się z zewnętrznymi narzędziami i źródłami danych.

Standaryzacja MCP jest korzystna, ponieważ umożliwia łatwiejszą integrację różnych narzędzi, promuje możliwość ponownego wykorzystania definicji narzędzi w różnych agentach lub modelach. Ponadto jest to najlepsza praktyka dla zespołów inżynieryjnych, zaczynając od dobrze zdefiniowanych specyfikacji API, takich jak specyfikacja OpenAPI. Narzędzia takie jak Stainless.ai są zaprojektowane, aby pomóc w konwersji tych specyfikacji OpenAPI na konfiguracje MCP, usprawniając proces tworzenia API „gotowych dla agentów”.

3. Ramy agentów i wybory implementacji

Kilka struktur może pomóc w zbudowaniu samego agenta. Należą do nich:

• Pydantyczny: Chociaż nie jest to wyłącznie framework agenta, Pydantic jest przydatny do definiowania struktur danych i zapewniania bezpieczeństwa typu dla danych wejściowych i wyjściowych narzędzi, co jest ważne dla niezawodności. Wiele niestandardowych implementacji agentów wykorzystuje Pydantic dla tej integralności strukturalnej.
• mcp_agent LastMile: Ta struktura została zaprojektowana specjalnie do pracy z MCP, oferując bardziej zdecydowaną strukturę, która jest zgodna z praktykami tworzenia skutecznych agentów, opisanymi w badaniach prowadzonych m.in. w Anthropic.
• Struktura wewnętrzna: Coraz częściej korzysta się również z agentów generujących kod AI (z wykorzystaniem narzędzi takich jak Cursor czy Cline), aby pomóc w napisaniu szablonowego kodu dla agenta, jego narzędzi i otaczającej go logiki. Doświadczenie Georgiana w AI Lab, zdobyte we współpracy z firmami nad implementacjami agentów, pokazuje, że może to być świetne rozwiązanie do tworzenia bardzo minimalistycznych, niestandardowych struktur.

IV. Inżynieria dla niezawodności i wydajności

Zapewnienie, że agent wykonuje wywołania API niezawodnie i dobrze działa, wymaga skoncentrowanego wysiłku inżynieryjnego. Dwa sposoby, aby to zrobić, to (1) tworzenie i walidacja zestawu danych oraz (2) szybka inżynieria i optymalizacja.

1. Tworzenie i walidacja zbioru danych

Szkolenie (jeśli dotyczy), testowanie i optymalizacja agenta wymaga wysokiej jakości zestawu danych. Zestaw danych powinien składać się z reprezentatywnych zapytań w języku naturalnym i odpowiadających im pożądanych sekwencji wywołań API lub wyników.

• Tworzenie ręczne: Ręczne porządkowanie zbioru danych zapewnia wysoką precyzję i trafność, ale może być pracochłonne.
• Generowanie syntetyczne: Generowanie danych programowo lub za pomocą LLM może skalować tworzenie zestawów danych, ale takie podejście stwarza znaczne wyzwania. Badania Georgian AI Lab wykazały, że zapewnienie poprawności i realistycznej złożoności syntetycznie generowanych wywołań i zapytań API jest bardzo trudne. Często generowane pytania były zbyt trywialne lub niemożliwie złożone, co utrudniało mierzenie niuansów wydajności agenta. Dokładna walidacja danych syntetycznych ma absolutnie krytyczne znaczenie.

W przypadku oceny krytycznej mniejszy, wysokiej jakości, ręcznie weryfikowany zbiór danych często zapewnia bardziej wiarygodne informacje niż duży, zaszumiony zbiór syntetyczny.

2. Szybka inżynieria i optymalizacja

Wydajność agenta LLM w dużym stopniu zależy od komunikatów użytych do kierowania jego rozumowaniem i wyborem narzędzi.

• Skuteczne podpowiadanie wymaga jasnego zdefiniowania zadania agenta, podania opisów dostępnych narzędzi i takiej struktury podpowiedzi, która ułatwi dokładne wyodrębnianie parametrów.
• Systematyczna optymalizacja przy użyciu ram takich jak DSPy Może znacząco poprawić wydajność. DSPy pozwala zdefiniować komponenty agenta (np. moduły generowania myśli, wyboru narzędzi, formatowania parametrów), a następnie, wykorzystując podejście podobne do kompilatora z kilkoma przykładami z zestawu danych, znaleźć zoptymalizowane monity lub konfiguracje dla tych komponentów.

V. Zalecana ścieżka do efektywnych agentów API

Opracowywanie solidnych agentów AI wywołujących API to iteracyjna dyscyplina inżynierska. Na podstawie ustaleń badań Georgian AI Lab wyniki można znacznie poprawić, stosując systematyczny przepływ pracy, taki jak poniższy:

1. Zacznij od przejrzystych definicji API: Zacznij od dobrze ustrukturyzowanego Specyfikacje OpenAPI dla interfejsów API, z którymi będzie współpracował Twój agent.
2. Standaryzacja dostępu do narzędzi: Konwertuj swoje specyfikacje OpenAPI do MCP Narzędzia takie jak Nierdzewny.ai może to ułatwić, tworząc ujednolicony sposób, w jaki Twój agent będzie mógł rozumieć i używać Twoich interfejsów API.
3. Wdrażanie agenta: Wybierz odpowiednie ramy lub podejście. Może to obejmować użycie Pydantyczny do modelowania danych w ramach niestandardowej struktury agenta lub wykorzystania struktury, takiej jak mcp_agent LastMile który jest zbudowany wokół MCP.
   • Zanim to zrobisz, rozważ połączenie MCP z narzędziem takim jak Claude Desktop lub Cline i ręczne użycie tego interfejsu, aby sprawdzić, jak dobrze agent ogólny może go używać, ile iteracji zazwyczaj potrzeba, aby poprawnie użyć MCP, a także poznać wszelkie inne szczegóły, które mogą zaoszczędzić czas podczas wdrażania.
4. Utwórz zbiór danych do oceny jakości: Ręcznie twórz lub skrupulatnie waliduj zbiór danych zapytań i oczekiwanych interakcji API. Jest to krytyczne dla niezawodnego testowania i optymalizacji.
5. Optymalizacja monitów i logiki agenta: Zastosuj ramy takie jak DSPy aby udoskonalić monity i wewnętrzną logikę agenta, wykorzystując zestaw danych w celu zwiększenia dokładności i niezawodności.

VI. Ilustrujący przykład przepływu pracy

Oto uproszczony przykład ilustrujący zalecany przepływ pracy przy tworzeniu agenta wywołującego API:

Krok 1: Zacznij od przejrzystych definicji API

Wyobraź sobie API do zarządzania prostą listą zadań do wykonania, zdefiniowaną w OpenAPI:

otwórzAPI: 3.0.0

info:

tytuł: API listy zadań do wykonania

Wersja: 1.0.0

ścieżki:

/zadania:

stanowisko:

Podsumowanie: Dodaj nowe zadanie

Treść żądania:

wymagane: prawda

treść:

aplikacja/json:

schemat:

typ: obiekt

nieruchomości:

opis:

typ: ciąg

odpowiedzi:

'201':

opis: Zadanie zostało pomyślnie utworzone

otrzymać:

podsumowanie: Pobierz wszystkie zadania

odpowiedzi:

'200':

opis: Lista zadań

Krok 2: Standaryzacja dostępu do narzędzi

Przekształć specyfikację OpenAPI w konfiguracje Model Context Protocol (MCP). Używając narzędzia takiego jak Stainless.ai, może to dać:

Krok 3: Wdrażanie agenta

Używając Pydantic do modelowania danych, utwórz funkcje odpowiadające narzędziom MCP. Następnie użyj LLM do interpretacji zapytań języka naturalnego i wybierz odpowiednie narzędzie i parametry.

Krok 4: Utwórz zbiór danych do oceny jakości

Utwórz zbiór danych:

Krok 5: Zoptymalizuj monity i logikę agenta

Użyj DSPy do udoskonalenia poleceń, skupiając się na jasnych instrukcjach, wyborze narzędzi i ekstrakcji parametrów przy użyciu wyselekcjonowanego zestawu danych do oceny i udoskonalenia.

Dzięki integracji tych elementów składowych — od ustrukturyzowanych definicji API i standardowych protokołów narzędzi po rygorystyczne praktyki dotyczące danych i systematyczną optymalizację — zespoły inżynieryjne mogą tworzyć bardziej wydajnych, niezawodnych i łatwych w utrzymaniu agentów AI wywołujących API.