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

Rola sztucznej inteligencji w firmach technologicznych ewoluuje w szybkim tempie; przypadki użycia sztucznej inteligencji przeszły od biernego przetwarzania informacji do aktywnych agentów zdolnych do wykonywania zadań. Zgodnie z badaniem przeprowadzonym w marcu 2025 roku na temat globalnego wdrożenia sztucznej inteligencji przez Georgian i NewtonX, 91% dyrektorów technicznych w firmach na etapie wzrostu i przedsiębiorstwach korzysta lub planuje korzystać z agentywnych sztucznych inteligencji.

Agenci wywołujący API są podstawowym przykładem tego przejścia do agentów. Agenci wywołujący API wykorzystują duże modele językowe (LLM) do interakcji z systemami oprogramowania za pośrednictwem ich interfejsów programistycznych (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 lub nawet kontrolować inne systemy oprogramowania. Ta zdolność przekształca agenty sztucznej inteligencji w użyteczne pośredników między intencją ludzką a funkcjonalnością oprogramowania.

Firmy obecnie wykorzystują agenci wywołujące API w różnych dziedzinach, w tym:

• Aplikacje konsumenckie: Asystenci tacy jak Siri od Apple lub Alexa od Amazon zostały zaprojektowane w celu uproszczenia codziennych zadań, takich jak kontrola urządzeń inteligentnych w domu i robienie rezerwacji.
• Przepływy pracy w przedsiębiorstwach: Przedsiębiorstwa wdrożyły agenci API w celu zautomatyzowania powtarzalnych zadań, takich jak pobieranie danych z systemów CRM, generowanie raportów lub konsolidacja informacji z wewnętrznych systemów.
• Pobieranie i analiza danych: Przedsiębiorstwa wykorzystują agenci API do uproszczenia dostępu do własnych zestawów danych, zasobów opartych na subskrypcji i publicznych API w celu generowania informacji.

W tym artykule użyję podejścia inżynierskiego do zrozumienia, budowy i optymalizacji agentów wywołujących API. Materiał w tym artykule oparty jest częściowo na praktycznych badaniach i rozwoju prowadzonym przez laboratorium sztucznej inteligencji Georgian. Pytanie motywujące wiele badań laboratorium sztucznej inteligencji w dziedzinie agentów wywołujących API brzmi: “Jeśli organizacja ma API, jaki jest najskuteczniejszy sposób budowy agenta, który może komunikować się z tym API przy użyciu języka naturalnego?”

Wyjaśnię, jak działają agenci wywołujący API i jak pomyślnie architektować i inżyniersko budować te agenci dla wydajności. Na końcu przedstawię systematyczny przepływ pracy, który zespoły inżynierskie mogą wykorzystać do wdrożenia agentów wywołujących API.

I. Kluczowe definicje:

• API lub Interfejs Programistyczny Aplikacji: Zestaw reguł i protokołów umożliwiających różnym aplikacjom oprogramowania komunikowanie się i wymianę informacji.
• Agent: System sztucznej inteligencji zaprojektowany do postrzegania swojego otoczenia, podejmowania decyzji i wykonywania działań w celu osiągnięcia określonych celów.
• Agent wywołujący API: Specjalistyczny agent sztucznej inteligencji, który tłumaczy polecenia języka naturalnego na precyzyjne wywołania API.
• Agent generujący kod: System sztucznej inteligencji, który pomaga w rozwoju oprogramowania poprzez pisanie, modyfikowanie i debugowanie kodu. Chociaż jest to pokrewne, moim głównym celem tutaj jest agent, który wywołuje API, chociaż sztuczna inteligencja może również pomóc zbudować te agenci.
• MCP (Model Context Protocol): Protokół, opracowany przez Anthropic, definiujący, jak modele mogą łączyć się z zewnętrznymi narzędziami i źródłami danych.

II. Podstawowe zadanie: Tłumaczenie języka naturalnego na akcje API

Podstawową funkcją agenta wywołującego API jest interpretacja żądania użytkownika w języku naturalnym i przekształcenie go w 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 w sposób niejasny.
2. Wybór narzędzia: Identyfikacja odpowiednich punktów końcowych API (lub “narzędzi”) z dostępnych opcji, które mogą spełnić intencję.
3. Ekstrakcja parametrów: Identyfikacja i ekstrakcja niezbędnych parametrów dla wybranych wywołań API z zapytania użytkownika.
4. Wykonanie i generowanie odpowiedzi: Wykonanie wywołań API, otrzymanie odpowiedzi i następnie synteza tej informacji w spójną odpowiedź lub wykonanie kolejnych działań.

Rozważmy żądanie takie jak “Hey Siri, jaka jest pogoda dzisiaj?” Agent musi zidentyfikować potrzebę wywołania API pogody, określić bieżącą lokalizację użytkownika (lub umożliwić określenie lokalizacji) i sformułować wywołanie API w celu pobrania informacji o pogodzie.

Dla żądania “Hey Siri, jaka jest pogoda dzisiaj?”, przykładowe wywołanie API może wyglądać następująco:

GET /v1/weather?location=New%20York&units=metric

Początkowe wyzwania na wysokim poziomie są wrodzone w tym procesie tłumaczenia, w tym niejasność języka naturalnego i potrzeba, aby agent utrzymywał kontekst w interakcjach wieloetapowych.

Na przykład, agent musi często “pamiętać” wcześniejsze części rozmowy lub wcześniejsze wyniki wywołań API, aby poinformować bieżące działania. Utrata kontekstu jest powszechnym trybem awaryjnym, jeśli nie jest jawnie zarządzany.

III. Architektura rozwiązania: Kluczowe składniki i protokoły

Budowanie skutecznych agentów wywołujących API wymaga ustrukturyzowanego podejścia architektonicznego.

1. Definiowanie “narzędzi” dla agenta

Aby LLM mógł używać API, jego możliwości muszą być opisane w sposób, który może zrozumieć. Każdy punkt końcowy API lub funkcja jest często reprezentowana jako “narzędzie”. Solidna definicja narzędzia obejmuje:

• Wyraźny, naturalny opis celu i funkcjonalności narzędzia.
• Dokładna specyfikacja parametrów wejściowych (nazwa, typ, czy jest wymagany czy opcjonalny, oraz opis).
• Opis danych wyjściowych lub danych zwracanych przez narzędzie.

2. Rola Model Context Protocol (MCP)

MCP jest krytycznym elementem umożliwiającym bardziej ustandaryzowane i solidne użycie narzędzi przez LLM. Zapewnia strukturalny format definiowania, jak modele mogą łączyć się z zewnętrznymi narzędziami i źródłami danych.

Ustandaryzowanie MCP jest korzystne, ponieważ umożliwia łatwiejsze integrowanie różnorodnych narzędzi, promuje możliwość ponownego użycia definicji narzędzi w różnych agentach lub modelach. Ponadto jest to najlepsza praktyka dla zespołów inżynierskich, rozpoczynających od dobrze zdefiniowanych specyfikacji API, takich jak specyfikacja OpenAPI. Narzędzia takie jak Stainless.ai są zaprojektowane, aby pomóc w przekształceniu tych specyfikacji OpenAPI w konfiguracje MCP, ułatwiając proces robienia API “gotowych dla agenta”.

3. Ramy agentów i wybory implementacyjne

Istnieje kilka ram, które mogą pomóc w budowaniu samego agenta. Obejmują one:

• Pydantic: Chociaż nie jest to wyłącznie rama agenta, Pydantic jest przydatny do definiowania struktur danych i zapewnienia bezpieczeństwa typów dla danych wejściowych i wyjściowych narzędzi, co jest ważne dla niezawodności. Wiele niestandardowych implementacji agentów wykorzystuje Pydantic do tej strukturalnej integralności.
• mcp_agent LastMile: Ta rama jest specjalnie zaprojektowana do pracy z MCP, oferując bardziej ustandaryzowaną strukturę, która odpowiada praktykom budowy skutecznych agentów, jak opisano w badaniach z miejsc takich jak Anthropic.
• Wewnętrzna rama: Coraz częściej używa się również agentów generujących kod sztucznej inteligencji (korzystając z narzędzi takich jak Cursor lub Cline), aby pomóc w napisaniu kodu boilerplate dla agenta, jego narzędzi i otaczającej logiki. Doświadczenie laboratorium sztucznej inteligencji Georgian pokazuje, że może to być bardzo pomocne w tworzeniu bardzo minimalnych, niestandardowych ram.

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

Gwarantowanie, że agent wywołuje API w sposób niezawodny i wydajny, wymaga ukierunkowanego wysiłku inżynierskiego. Dwa sposoby osiągnięcia tego to (1) tworzenie zestawu danych i walidacja oraz (2) inżynieria i optymalizacja podpowiedzi.

1. Tworzenie zestawu danych i walidacja

Szkolenie (jeśli dotyczy), testowanie i optymalizacja agenta wymaga wysokiej jakości zestawu danych. Zestaw danych powinien składać się z reprezentatywnych zapytań języka naturalnego i ich odpowiednich sekwencji wywołań API lub wyników.

• Tworzenie ręczne: Ręczne tworzenie zestawu danych zapewnia wysoką precyzję i odpowiedniość, ale może być czasochłonne.
• Generowanie syntetyczne: Generowanie danych programowo lub przy użyciu LLM może skalować tworzenie zestawu danych, ale podejście to przedstawia znaczne wyzwania. Badania laboratorium sztucznej inteligencji Georgian wykazały, że zapewnienie poprawności i realistycznej złożoności syntetycznie generowanych wywołań API i zapytań jest bardzo trudne. Często generowane pytania były albo zbyt trywialne, albo niemożliwie złożone, co utrudniało pomiar nuansowanego działania agenta. Staranne sprawdzanie danych syntetycznych jest absolutnie krytyczne.

Do celów oceny ważne jest, aby mniejszy, wysokiej jakości, ręcznie zweryfikowany zestaw danych często dostarczał bardziej niezawodne informacje niż duży, hałaśliwy syntetyczny.

2. Inżynieria i optymalizacja podpowiedzi

Wydajność agenta opartego na LLM jest silnie wpływana przez podpowiedzi używane do kierowania jego rozumowaniem i wyborem narzędzi.

• Skuteczne podpowiedzi obejmują wyraźne definiowanie zadania agenta, dostarczanie opisów dostępnych narzędzi i strukturyzowanie podpowiedzi w celu zachęcenia do dokładnej ekstrakcji parametrów.
• Systematyczna optymalizacja przy użyciu ram takich jak DSPy może znacznie poprawić wydajność. DSPy pozwala zdefiniować składniki agenta (np. moduły do generowania myśli, wyboru narzędzi, formatowania parametrów) i następnie użyć podejścia podobnego do kompilatora z kilkoma przykładami z zestawu danych, aby znaleźć zoptymalizowane podpowiedzi lub konfiguracje tych składników.

V. Zalecany ścieżka do skutecznych agentów API

Rozwój solidnych agentów wywołujących AI jest dyscypliną inżynierską o charakterze iteracyjnym. Na podstawie wyników badań laboratorium sztucznej inteligencji Georgian, wyniki mogą być znacznie poprawione przy użyciu systematycznego przepływu pracy, takiego jak:

1. Rozpocznij od jasnych definicji API: Zacznij od dobrze ustrukturyzowanych specyfikacji OpenAPI dla API, z którymi agent będzie współpracował.
2. Ustandaryzuj dostęp do narzędzi: Przekonwertuj swoje specyfikacje OpenAPI na MCP. Narzędzia takie jak Stainless.ai mogą ułatwić to, tworząc ustandaryzowany sposób, w jaki agent może zrozumieć i używać API.
3. Zaimplementuj agenta: Wybierz odpowiednią ramę lub podejście. Może to obejmować użycie Pydantic do modelowania danych w ramach niestandardowej struktury agenta lub wykorzystanie ramy takiej jak mcp_agent LastMile, która jest zbudowana wokół MCP.
   • Przed tym rozważ połączenie MCP z narzędziem takim jak Claude Desktop lub Cline i ręczne użycie tego interfejsu, aby uzyskać poczucie, jak dobrze ogólny agent może używać go, ile iteracji zwykle zajmuje, aby użyć MCP poprawnie, i jakie inne szczegóły mogą zaoszczędzić czas podczas implementacji.
4. Utwórz zestaw danych do oceny: Ręcznie utwórz lub starannie sprawdź zestaw danych zapytań i oczekiwanych interakcji API. Jest to krytyczne dla niezawodnego testowania i optymalizacji.
5. Optymalizuj podpowiedzi i logikę agenta: Zastosuj ramy takie jak DSPy, aby udoskonalić podpowiedzi i wewnętrzną logikę agenta, używając zestawu danych do napędzania popraw w dokładności i niezawodności.

VI. Ilustracyjny przykład przepływu pracy

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

Krok 1: Rozpocznij od jasnych definicji API

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

openapi: 3.0.0

info:

tytuł: API listy zadań

wersja: 1.0.0

ścieżki:

/zadania:

post:

streszczenie: Dodaj nowe zadanie

treść żądania:

wymagane: prawda

zawartość:

application/json:

schema:

typ: obiekt

właściwości:

opis:

typ: ciąg

odpowiedzi:

‘201’:

opis: Zadanie utworzone pomyślnie

get:

streszczenie: Pobierz wszystkie zadania

odpowiedzi:

‘200’:

opis: Lista zadań

Krok 2: Ustandaryzuj dostęp do narzędzi

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

Krok 3: Zaimplementuj agenta

Używając Pydantic do modelowania danych, utwórz funkcje odpowiadające konfiguracjom MCP. Następnie użyj LLM, aby zinterpretować zapytania języka naturalnego i wybrać odpowiednie narzędzie i parametry.

Krok 4: Utwórz zestaw danych do oceny

Utwórz zestaw danych:

Krok 5: Optymalizuj podpowiedzi i logikę agenta

Użyj DSPy, aby udoskonalić podpowiedzi, koncentrując się na jasnych instrukcjach, wyborze narzędzi i ekstrakcji parametrów, używając zestawu danych do oceny i poprawy.

Poprzez integrację tych elementów budulcowych – od ustrukturyzowanych definicji API i ustandaryzowanych protokołów narzędzi po rygorystyczne praktyki danych i systematyczną optymalizację – zespoły inżynierskie mogą budować bardziej zdolne, niezawodne i łatwiejsze w utrzymaniu agenci wywołujące API.