Korzystanie z narzędzi przez agentów AI: MCP, CLI, Skills i wykonywanie kodu

Viacheslav Dubrov

2026-03-24 · Zaktualizowano 2026-09-06 · 23 min · Agenci AI

Tłumaczenie automatyczne Ten artykuł został automatycznie przetłumaczony z angielskiego oryginału.

Aktualizacja artykułu

Pierwotnie opublikowano 24 marca 2026 r. Artykuł zrecenzowano i zaktualizowano 6 września 2026 r. Aktualizacja obejmuje zrewidowaną specyfikację MCP, programistyczne wywoływanie narzędzi oraz nowsze dane dotyczące kosztów i ograniczeń korzystania z narzędzi.

Agent potrzebuje sposobu działania: wywołania narzędzia w formacie JSON, usługi MCP, polecenia CLI albo kodu uruchamianego w sandboxie. Może też potrzebować instrukcji dotyczących wyboru i używania danego mechanizmu. Takich instrukcji dostarczają Skills. Harness to zwykły program otaczający model: buduje prompty, sprawdza proponowane wywołanie, uruchamia zatwierdzone wywołanie i decyduje, kiedy zadanie jest zakończone.

Ten trzeci artykuł z serii dodaje warstwę działania do pętli rozumowania z części 1 i pamięci z części 2. Część 4 analizuje sprawdzenie polityki przed wykonaniem, a część 6 — harness uruchamiający zarówno wywołanie, jak i to sprawdzenie.

W latach 2025–2026 podejście do narzędzi uległo zmianie. MCP, czyli Model Context Protocol, dał dostawcom jeden wspólny sposób udostępniania zewnętrznych usług. Agenci wykonujący kod pokazały, że model może czasem efektywniej złożyć mały program niż wysyłać długą sekwencję wywołań JSON. Anthropic podał 98,7% redukcji liczby tokenów dla jednego procesu Google Drive–Salesforce, a artykuł CodeAct odnotował wzrost skuteczności zadań nawet o 20 punktów procentowych w ramach swojej konfiguracji benchmarku. Wyniki te dotyczą konkretnych zadań i harnessów, a nie uniwersalnej przewagi wykonywania kodu.

Porównuję wywoływanie narzędzi w formacie JSON, MCP, narzędzia CLI i wykonywanie kodu, a następnie pokazuję, gdzie mieszczą się Skills. W późniejszej sekcji stosuję zasady projektowania Agent-Computer Interface (ACI) do Market Analyst Agent — niewielkiego agenta badawczego w LangGraph, którego zbudowałem w części 1; agent pobiera dane rynkowe i tworzy raport analityczny.

Krótki przewodnik po wyborze interfejsu znajduje się w AI Agent Tool Interfaces.

Interfejsy wykonywania i wskazówki proceduralne

Pętla rozumowania proponuje wywołanie. Harness sprawdza jego argumenty oraz to, czy wywołanie jest dozwolone, następnie przekazuje je do narzędzia lub sandboxa i zwraca wynik. Schematy JSON, transport MCP, wrappery CLI i runnery kodu mogą ograniczać dane wejściowe, ale żaden z nich samodzielnie nie decyduje, czy żądane działanie jest dozwolone. Skills dostarczają instrukcji dotyczących tej ścieżki. Poszczególne interfejsy wykonywania różnią się kompromisami dotyczącymi kosztu tokenów, elastyczności i egzekwowania zasad.

1. Wywoływanie narzędzi w formacie JSON: punkt wyjścia

Oryginalny wzorzec: definiujesz schematy narzędzi jako JSON, LLM emituje ustrukturyzowane wywołania funkcji, a twój kod je wykonuje. To dobrze poznane podejście, które sprawdza się w przypadku niewielkich zestawów narzędzi.

# Schema cost depends on its text, structure, and the model tokenizer
tools = [
    {
        "name": "get_stock_price",
        "description": "Get the current stock price for a ticker symbol",
        "input_schema": {
            "type": "object",
            "properties": {
                "ticker": {"type": "string", "description": "Stock ticker (e.g., NVDA)"}
            },
            "required": ["ticker"]
        }
    }
]

Policz tokeny w rzeczywistych schematach. Koszt zależy od ich długości i liczby schematów ładowanych przez hosta; zwięzłe wyszukiwanie ceny i głęboko zagnieżdżony kontrakt API nie są równoważnymi jednostkami. Odroczone wykrywanie może zapobiec ładowaniu całego rejestru.

2. MCP dla współdzielonych integracji

MCP to standard, ku któremu zbiegała większość dostawców. Serwer MCP jest procesem, który udostępnia listę narzędzi za pośrednictwem zdefiniowanego protokołu przewodowego — stdio dla procesu lokalnego i HTTP dla zdalnego. Agent uruchamia klienta MCP, który nawiązuje połączenie, pyta serwer o dostępne narzędzia i przekazuje do niego wywołania modelu, dzięki czemu ten sam serwer działa z każdym klientem obsługującym protokół. W grudniu 2025 r. Anthropic przekazał protokół Linux Foundation, w ramach Agentic AI Foundation założonej wspólnie z OpenAI i Block. Google, Microsoft i AWS wspierają fundację jako członkowie platynowi. OpenAI dodało obsługę MCP w Responses API. Zgodnie z ogłoszeniem Anthropic o przekazaniu protokołu z grudnia 2025 r. ekosystem obejmował ponad 10 000 aktywnych publicznych serwerów MCP i ponad 97 mln miesięcznych pobrań SDK dla SDK w Pythonie i TypeScript.

MCP pasuje do integracji SaaS między dostawcami (Figma, Notion, Salesforce), usług bez odpowiedników CLI oraz środowisk wymagających orkiestracji OAuth. Jego wartość polega na zapewnieniu współdzielonej warstwy wykrywania i transportu. Zarządzanie nadal zależy od mechanizmów uwierzytelniania, autoryzacji, logowania i wdrażania po stronie serwera.

Wersja protokołu jest obecnie praktyczną decyzją migracyjną. Rewizja z 28 lipca 2026 r. zmienia zachowanie, które zakładają starsze tutoriale:

Ta sama rewizja oznacza Roots, Sampling, Logging i OAuth Dynamic Client Registration jako przestarzałe; oznaczenie jako przestarzałe nie oznacza natychmiastowego usunięcia. Obecnie rejestracja klienta preferuje Client ID Metadata Documents. Istniejące integracje mogą nadal korzystać ze starszej rewizji, dlatego przed przyjęciem nowej funkcji sprawdź zainstalowane SDK i kontrakt serwera.

Rzeczywistość produkcyjna jest bardziej złożona, niż sugerują nagłówkowe liczby.

Projekt Vulnerable MCP Project gromadzi raporty dotyczące prompt injection, walidacji danych wejściowych, uwierzytelniania i kontroli sieciowych. Taka kolekcja pomaga identyfikować przypadki testowe; bez mianownika określającego ekspozycję nie można na jej podstawie porównywać MCP z shellem ani bezpośrednimi wywołaniami API.

Najbardziej niepokoi mnie klasa ataków polegających na zatruwaniu narzędzi. Invariant Labs pokazało, że zatrute narzędzia MCP mogą eksfiltrować dane, nawet jeśli nigdy nie zostaną wywołane. Samo odczytanie metadanych narzędzia przez model wystarcza do uruchomienia ataku. Benchmarki MCPTox, testujące 20 agentów LLM na 45 rzeczywistych serwerach MCP, odnotowały średni współczynnik skuteczności ataku 72,8% dla o1-mini w konfiguracji obejmującej zatruwanie narzędzi. To wynik benchmarku dla jednego modelu, a nie średnia dla 20 agentów ani wskaźnik incydentów w środowisku rzeczywistym.

Problemem operacyjnym jest narzut tokenów. Jeden zespół uruchamiający serwery MCP dla GitHub, Slacka i Sentry (łącznie około 40 narzędzi) stwierdził, że 55 000 tokenów definicji schematów jest wstrzykiwanych, zanim użytkownik zada jakiekolwiek pytanie. Inny zespół zgłosił, że same definicje narzędzi zużywały 143 000 z 200 000 dostępnych tokenów (72%).

Raport Anthropic o Tool Search Tool podawał przybliżone rozmiary kontekstu: 77 000 tokenów przed rozpoczęciem pracy oraz 8700 po odroczonym wykrywaniu, przy około 72 000 tokenów definicji narzędzi w tradycyjnej konfiguracji. Ładowane są tylko trzy do pięciu narzędzi potrzebnych dla danego żądania, ale przed wywołaniem dochodzi krok wykrywania; rozwiązanie jest mniej użyteczne w przypadku małych, zwięzłych zestawów narzędzi, które są często używane w każdej sesji.

3. Skills pakują wiedzę ekspercką, a nie mechanizm wykonywania

Agent skills to otwarty format pakowania instrukcji i plików pomocniczych. Narzędzia zapewniają możliwości — czyli to, co agenci mogą robić — natomiast Skills dostarczają wiedzy eksperckiej, czyli informacji o tym, jak wykonywać złożone zadania.

Format SKILL.md definiuje skill jako plik markdown z frontmatterem YAML. Otwarty standard wymaga jedynie name i description; poniższy przykład korzysta także z dwóch rozszerzeń Claude Code, argument-hint i user-invocable, oraz z jego placeholdera argumentu pozycyjnego $0:

---
name: deploy
description: Deploy the application to production
argument-hint: "[environment]"
user-invocable: true
---
Deploy the application to the $0 environment (default: staging).
Steps:
1. Run the test suite
2. Build the production bundle
3. Deploy using the deploy script
4. Verify the deployment health check

Skills wykorzystują progressive disclosure. Przy uruchomieniu agent otrzymuje około 100 tokenów name i description. Pełny SKILL.md jest ładowany dopiero wtedy, gdy agent potrzebuje danego skilla; następnie, w razie potrzeby, ładowane są wskazane skrypty, dokumenty lub assety. Ten koszt początkowy jest znacznie mniejszy niż około 55 000 tokenów, które około 40 narzędzi MCP może zużyć przed rozpoczęciem rozumowania. Aktywny skill nadal dodaje do kontekstu swoje instrukcje i zasoby.

Skills stosuj do wiedzy domenowej, procedur wieloetapowych i powtarzalnych prac, takich jak migracje baz danych czy integracje płatności. Pasują do zadań, w których agent potrzebuje instrukcji jak korzystać z istniejącej możliwości.

4. Narzędzia CLI i shell

Interfejsy CLI mogą być znacznie tańsze pod względem kontekstu, gdy model zna już dane polecenie. Scalekit odnotował różnicę 4–32 razy w liczbie tokenów między ścieżkami CLI i MCP w 75 uruchomieniach. To studium przypadku mierzy konkretne narzędzia i zadania; nie zastępuje porównania na podstawie własnych definicji narzędzi i wyników poleceń.

Szeroko udokumentowane polecenia, takie jak git, docker, kubectl, gh, curl i jq, często wymagają niewielkiej ilości wprowadzającego tekstu schematu. Mniej popularne lub wewnętrzne CLI nadal potrzebują odkrywalnej pomocy, przykładów i stabilnego, czytelnego dla maszyn formatu wyjściowego.

Poradnik Ugo Enyiohy “Writing CLI Tools That AI Agents Actually Want to Use” sformalizował osiem zasad projektowych:

1. Ustrukturyzowane dane wyjściowe są obowiązkowe — obsługuj --json
2. Kody wyjścia sterują przepływem — używaj różnych kodów dla różnych typów błędów
3. Polecenia powinny być idempotentne
4. Samodokumentowanie --help z realistycznymi przykładami
5. Projektuj z myślą o kompozycji — --quiet dla samych wartości, obsługa stdin
6. Udostępniaj flagi --dry-run i --yes
7. Obsługuj introspekcję wersji
8. Obsługuj uwierzytelnianie za pomocą zmiennych środowiskowych

CLI nie ma wykrywania na poziomie protokołu. Wywoływanie narzędzi w formacie JSON może przenosić typowane schematy, natomiast MCP standaryzuje wykrywanie narzędzi oraz — dla transportów HTTP — model autoryzacji. Żadne z tych rozwiązań samo w sobie nie zapewnia zarządzania: host, serwer lub harness musi egzekwować politykę i rejestrować wywołania wymagające audytu. Praktyczną regułą domyślną jest CLI dla programowania i operacji lokalnych oraz MCP dla współdzielonych integracji z usługami zewnętrznymi, gdy wykrywanie między klientami lub orkiestracja OAuth uzasadniają narzut serwera.

5. Wykonywanie kodu do pracy wieloetapowej

To zmiana w narzędziach agentów, którą uważam za najbardziej doniosłą. Zamiast emitować ustrukturyzowany JSON w celu wywoływania predefiniowanych funkcji pojedynczo, agent tworzy skrypt w Pythonie lub bashu. Skrypt wywołuje wiele narzędzi, przetwarza wyniki za pomocą pętli i instrukcji warunkowych, a do kontekstu modelu zwraca wyłącznie końcowe podsumowanie.

Anthropic wprowadził w becie Programmatic Tool Calling (PTC). Aktualny przewodnik API korzysta ze zwykłego Messages API z code_execution_20260120 lub nowszym; pierwotna premiera w becie jest kontekstem historycznym. Podstawą akademicką jest artykuł CodeAct (Wang i in., ICML 2024), który przetestowano na 17 LLMs i wykazał, że działania oparte na kodzie zapewniały do 20 punktów procentowych wyższą skuteczność zadań oraz 30% mniej działań niż alternatywy oparte na JSON.

Trzy studia przypadku pochodzące bezpośrednio od dostawców pokazują, gdzie ten wzorzec może pomóc: poniżej Vercel i Cloudflare, a następnie przykład analizy wydatków Anthropic. Traktuj je jako dane od dostawców i ponownie wykonaj porównanie na własnych zadaniach.

• Vercel przebudował d0, agenta przekształcającego język naturalny w zapytania SQL. W starym przykładzie kodu wymieniono 17 narzędzi, a w nowym udostępniono ExecuteCommand i ExecuteSQL. Vercel przedstawia tę przebudowę jako usunięcie 80% narzędzi, ale jest to nagłówkowa deklaracja Vercel, a nie odsetek wynikający z nazwanych narzędzi w przykładach. Dla pięciu reprezentatywnych zapytań Vercel podaje, że skuteczność zadań wzrosła z 4/5 do 5/5, średni czas wykonywania skrócił się 3,5 raza (z 274,8 s do 77,4 s), a średnie zużycie tokenów spadło o 37% (z około 102 tys. do około 61 tys.). Ich sformułowanie brzmi: „Najlepszymi agentami mogą być te, które mają najmniej narzędzi”.

• Cloudflare opracował „Code Mode”, umożliwiając agentom pisanie kodu TypeScript wywołującego ich API zamiast definiowania schematów narzędzi, co zmniejsza narzut kontekstu. Ich uzasadnienie brzmi: „LLMs mają w zbiorze treningowym ogromną ilość rzeczywistego kodu TypeScript, ale tylko niewielki zestaw sztucznych przykładów wywołań narzędzi”.

Poniżej znajduje się wzorzec z dokumentacji PTC Anthropic. W sekwencyjnym przykładzie analizy wydatków Anthropic tradycyjne wywoływanie narzędzi wymaga ponad 20 oddzielnych przebiegów inferencji, a dane pośrednie przepływają przez kontekst. Po wyszukaniu zespołu host obsługujący równoległe wywołania narzędzi może zgrupować niezależne żądania dotyczące wydatków; liczba ponad 20 nie oznacza, że jest to niemożliwe. Anthropic podaje, że wygenerowany kod odpowiadający na to samo pytanie zmniejsza ilość danych trafiających do kontekstu z 200 KB surowych wierszy wydatków — ponad 2000 pozycji — do 1 KB wyników. Poniższy skrypt ilustruje ten przepływ sterowania za pomocą własnych asynchronicznych adapterów w Pythonie: przyjmują one argumenty pozycyjne i zwracają zdekodowane listy oraz słowniki. Nie jest to natywny kontrakt wrappera PTC.

# Custom decoded Python adapters, not native Claude PTC wrappers.
import asyncio
import json

async def main() -> None:
    team = await get_team_members("engineering")
    levels = list(set(member["level"] for member in team))
    budgets = dict(zip(
        levels,
        await asyncio.gather(*(get_budget_by_level(level) for level in levels)),
    ))
    expenses = await asyncio.gather(
        *(get_expenses(member["id"], "Q3") for member in team)
    )
    over_budget = []
    for member, employee_expenses in zip(team, expenses):
        total = sum(expense["amount"] for expense in employee_expenses)
        limit = budgets[member["level"]]["travel_limit"]
        if total > limit:
            over_budget.append(
                {"name": member["name"], "spent": total, "limit": limit}
            )
    # Only this final summary returns to the LLM context
    print(json.dumps(over_budget))

asyncio.run(main())

Aby korzystać z natywnych wrapperów Claude PTC, przekaż każdemu narzędziu jeden słownik argumentów, zdekoduj zwrócony przez nie string JSON i używaj najwyższego poziomu await w zarządzanym środowisku wykonywania zamiast uruchamiać pętlę zdarzeń za pomocą asyncio.run. Powyższy przykład z własnymi adapterami zakłada zwykłe środowisko uruchamiania skryptu w Pythonie; nie jest też gotowym przykładem natywnego konektora MCP. Aktualne ograniczenia API PTC wykluczają narzędzia strict: true i natywne narzędzia konektora MCP z programistycznych wywołań oraz ograniczają rekurencyjne schematy. Własny most kod–MCP jest oddzielną integracją. allowed_callers opisuje, jak Claude wywołuje narzędzie; nie jest granicą autoryzacji. Host musi zweryfikować każde zwrócone wywołanie, w tym nieoczekiwane wywołanie bezpośrednie.

LLM widzi wyłącznie końcowe podsumowanie JSON, a nie tysiące pozycji wydatków przetwarzanych w sandboxie. Oszczędność nie dotyczy wyłącznie raportów wydatków: oddzielny artykuł Anthropic o wykonywaniu kodu podaje najbardziej wyrazistą liczbę dla tego wzorca — proces Google Drive–Salesforce zmniejszył liczbę tokenów z około 150 000 do około 2000, czyli o 98,7%.

Aktualny przewodnik PTC podaje również kontrprzykład: w zadaniach lotniczych, detalicznych i telekomunikacyjnych tau2-bench PTC nie zmieniło wyników, a koszt wzrósł o około 8%. W oddzielnym benchmarku zarządzania projektami z 75 narzędziami zmniejszyło rozliczane tokeny wejściowe o około 38%, bez zmiany dokładności. Te wewnętrzne ewaluacje wymieniają wyłącznie produkcyjny model Claude, bez dokładnego identyfikatora. Małe sekwencyjne przepływy pracy mogą nie zapewniać oszczędności wystarczających do zrównoważenia narzutu uruchomienia kontenera i generowania kodu.

Efektywność tokenowa jest potencjalną korzyścią. Pętle i instrukcje warunkowe nie generują dodatkowego kosztu, a wykonywanie kodu może obsługiwać błędy za pomocą jawnych handlerów, zamiast zmuszać model do rozumowania o awariach w języku naturalnym. Ścieżka wykonywania kodu może utrzymywać wrażliwe dane pośrednie poza kontekstem modelu, ale nie oznacza to poufności: izolacja, kontrola egress, ograniczone poświadczenia i logowanie wymagają osobnego egzekwowania.

Kiedy wywoływanie narzędzi w formacie JSON nadal ma sens: pojedyncze operacje atomowe, środowiska bez infrastruktury sandboxów, mniejsze modele ze słabym generowaniem kodu lub wymagania audytowe, w których trzeba rejestrować każde pojedyncze wywołanie narzędzia.

Porównanie wykonywania narzędzi przez agentów AI

Wywoływanie narzędzi w formacie JSON, MCP, CLI i wykonywanie kodu to interfejsy wykonywania. Skills są instrukcjami kierującymi jednym z tych interfejsów, dlatego ich opóźnienie, kontekst i konfiguracja zależą od wybranego mechanizmu. „Meta-tools” oznaczają kilka ogólnych punktów wejścia, których potrzebuje agent wykonujący kod — na przykład ExecuteCommand i ExecuteSQL firmy Vercel — zamiast osobnego schematu dla każdej operacji. Wiersze dotyczące kompozycyjności i opóźnienia opisują wywołania, których późniejsze argumenty zależą od wcześniejszych wyników. Wywoływanie narzędzi w formacie JSON i MCP może wykonywać niezależne wywołania równolegle, ale zależne wywołania zwykle wymagają kolejnej tury modelu. PTC przenosi zależny przepływ sterowania i filtrowanie do skryptu, a następnie zwraca modelowi podsumowanie. Komórki dotyczące tokenów i skuteczności zadań podsumowują cytowane przykłady, a nie jeden kontrolowany benchmark obejmujący wszystkie pięć kolumn.

Agent-Computer Interface (ACI) dla narzędzi agentów AI

Termin „Agent-Computer Interface” (ACI) został ukuty przez Johna Yanga, Carlosa E. Jimeneza i współpracowników z Princeton w ich artykule o SWE-agent (NeurIPS 2024). Jakości interfejsów dla ludzi poświęcono całą dziedzinę — interakcję człowiek–komputer, czyli HCI. Autorzy artykułu argumentują, że agenci opierający się na modelach językowych zasługują na takie samo podejście: są „nową kategorią użytkowników końcowych z własnymi potrzebami i możliwościami, którzy skorzystaliby ze specjalnie zaprojektowanych interfejsów”.

Ich wyniki ablation nadają temu konkretny wymiar liczbowy. Przy użyciu tego samego bazowego modelu GPT-4 Turbo ablation SWE-bench Lite z artykułu osiągnęło 18,0% z pełnym ACI SWE-agent na 300 zadaniach, w porównaniu z 7,3% dla warunku obejmującego wyłącznie shell, bez przykładu demonstracyjnego, oraz 11,0% z jednym przykładem. Porównanie pokazuje, że interfejs i warunki demonstracji istotnie zmieniły wyniki w tej konfiguracji; nie izoluje ono projektowania interfejsu od wszystkich pozostałych różnic ani nie dowodzi, że model nie wykonał żadnej pracy. W obrębie tej samej ablation włączenie lintingu podniosło wynik warunku edycji z 15,0% do 18,0%; w całym zbiorze testowym SWE-bench 51,7% uruchomień SWE-agent obejmowało co najmniej jedną edycję odrzuconą przez linter, zanim mogła zostać zastosowana dalej.

Anthropic przyjął ACI jako podstawową koncepcję w przewodniku “Building Effective Agents”, wymieniając ją jako jedną z trzech głównych zasad: „Starannie zaprojektuj interfejs agent–komputer, wykorzystując dokładną dokumentację i testowanie narzędzi”. Praktyczna wskazówka brzmi: „Jedną z reguł orientacyjnych jest zastanowienie się, ile wysiłku poświęca się interfejsom człowiek–komputer, i zaplanowanie takiej samej inwestycji w tworzenie dobrych interfejsów agent–komputer”.

Cztery zasady ACI w praktyce

1. Działania powinny być proste i łatwe do zrozumienia. Najczęstszym błędem jest odwzorowywanie endpointów API jeden do jednego. Zamiast list_users, list_events i create_event zaimplementuj schedule_event, które w jednym wywołaniu sprawdza dostępność i tworzy rezerwację. Zamiast read_logs zaimplementuj search_logs, które zwraca tylko odpowiednie wiersze wraz z kontekstem.

2. Działania powinny być zwięzłe i wydajne. Konsoliduj ważne operacje w możliwie małej liczbie działań. W Market Analyst Agent łączę pobieranie cen z podstawowymi metrykami w jednym narzędziu get_stock_snapshot, zamiast wymagać osobnych wywołań dla ceny, wolumenu, kapitalizacji rynkowej i współczynnika PE.

3. Informacje zwrotne ze środowiska powinny być przydatne, ale zwięzłe. Unikaj zwracania surowego HTML-a lub pełnych payloadów API. Zastępuj nieczytelne identyfikatory nazwami semantycznymi. Testy Anthropic dodały enum response_format, dzięki któremu agent może zażądać zwięzłej (około 72 tokenów) albo szczegółowej (około 206 tokenów) odpowiedzi, co daje mniej więcej trzykrotną różnicę w koszcie tokenów.

4. Walidacja powinna ograniczać propagację błędów. Automatyczne wykrywanie błędów pomaga agentom szybko je rozpoznawać i korygować. W SWE-agent własny edytor plików ze zintegrowanym lintingiem automatycznie odrzuca błędy składni — to krok walidacji stojący za wspomnianą wyżej wartością 51,7%. Jest to walidacja danych wejściowych i wyjściowych narzędzia, a nie filtrowanie treści wokół wywołania modelu, za które odpowiadają produkty guardrails opisane w części 4; tego samego słowa używa się w obu znaczeniach. Tę samą zasadę stosuję w Market Analyst Agent, walidując argumenty narzędzi za pomocą schematów Pydantic przed wykonaniem:

from pydantic import BaseModel, Field, field_validator

from market_analyst.utils import normalize_ticker

class StockQuery(BaseModel):
    """Validated input for stock queries.

    Pydantic catches malformed tickers before the API call,
    preventing error propagation through the reasoning loop.
    """
    ticker: str = Field(description="Stock ticker symbol (e.g., NVDA)")

    @field_validator("ticker")
    @classmethod
    def validate_ticker(cls, v: str) -> str:
        return normalize_ticker(v)

class StockHistoryQuery(StockQuery):
    """Validated input for price history queries."""

    period: str = Field(default="1mo", description="Time period: 1d, 5d, 1mo, 3mo, 6mo, 1y")

    @field_validator("period")
    @classmethod
    def validate_period(cls, v: str) -> str:
        valid = {"1d", "5d", "1mo", "3mo", "6mo", "1y"}
        if v not in valid:
            raise ValueError(f"Invalid period: {v}. Must be one of {valid}")
        return v

Wspólny normalizer usuwa białe znaki i zamienia wartość na wielkie litery, a następnie akceptuje cyfry w tickerach oraz przyrostki z kropkami lub myślnikami, takie jak BRK.B i BF-B; StockHistoryQuery, a nie StockQuery, odpowiada za period.

Wzorce projektowania narzędzi agentów AI, które działają

Przewodnik Anthropic “Writing effective tools for agents” opisuje narzędzia jako „nowy rodzaj oprogramowania odzwierciedlający kontrakt między systemami deterministycznymi a niedeterministycznymi agentami”.

Traktuj opisy narzędzi jak prompt engineering

Opisy powinny mieć co najmniej trzy lub cztery zdania i obejmować sytuacje, w których należy użyć narzędzia, parametry wymagane i opcjonalne, format danych wyjściowych oraz przypadki brzegowe. Anthropic podaje, że wybór między namespacingiem opartym na prefiksie i sufiksie (asana_search versus search_asana) miał „nietrywialny wpływ” na ich własne ewaluacje korzystania z narzędzi. Nie wskazuje jednak, który schemat wygrywa, dlatego przetestuj oba na własnym zestawie narzędzi zamiast zakładać wyższość prefiksów. Anthropic przekazywał również transkrypcje swoich agentów ewaluacyjnych z powrotem do Claude Code i pozwalał mu przepisywać narzędzia. Na wydzielonych zbiorach testowych ta pętla przyniosła dalsze usprawnienia „nawet wykraczające poza to, co osiągnęliśmy dzięki „eksperckim” implementacjom narzędzi” — niezależnie od tego, czy narzędzia zostały napisane ręcznie przez badaczy, czy wygenerowane przez Claude.

# Bad: vague, no context for when to use
tools = [{
    "name": "search",
    "description": "Search for items",
}]

# Good: specific, with input examples and edge cases
tools = [{
    "name": "search_news",
    "description": (
        "Search for recent news articles about a specific stock or company. "
        "Use this tool when the user asks about recent events, earnings, "
        "announcements, or market-moving news for a specific ticker. "
        "Returns up to 10 articles sorted by relevance. "
        "For company competitors rather than news, use search_competitors instead."
    ),
    "input_schema": {
        "type": "object",
        "properties": {
            "query": {
                "type": "string",
                "description": "Search query. Examples: 'NVDA earnings Q3 2025', 'Tesla delivery numbers'"
            },
            "max_results": {
                "type": "integer",
                "description": "Max articles to return (1-10, default 5)",
                "default": 5
            }
        },
        "required": ["query"]
    }
}]

Wewnętrzne testy Anthropic wykazały, że dodanie pola input_examples zwiększyło dokładność obsługi złożonych parametrów z 72% do 90%.

Zwracaj wysokosygnałowe, czytelne maszynowo dane wyjściowe

W domyślnej odpowiedzi używaj etykiet semantycznych zamiast niskopoziomowych identyfikatorów (uuid, mime_type). Zachowaj ID, jeśli kolejne narzędzie będzie go potrzebować, albo zaoferuj szczegółową odpowiedź, która go zawiera. Na przykład wynik wyszukiwania dla Jane może być zwięzły i łatwy do odczytania, natomiast szczegółowy wynik może zawierać ID wymagany przez send_message. Zorganizuj odpowiedź tak, aby agent mógł na jej podstawie rozumować bez parsowania boilerplate’u:

# Bad: raw API response dumped to agent
def get_stock_snapshot(ticker: str) -> dict:
    response = api.get(f"/v1/quotes/{ticker}")
    return response.json()  # 500+ tokens of nested JSON

# Good: high-signal summary the agent can immediately reason about
def get_stock_snapshot(ticker: str) -> dict:
    data = api.get(f"/v1/quotes/{ticker}").json()
    return {
        "ticker": ticker,
        "price": data["regularMarketPrice"],
        "change_pct": round(data["regularMarketChangePercent"], 2),
        "volume": data["regularMarketVolume"],
        "market_cap_b": round(data["marketCap"] / 1e9, 1),
        "pe_ratio": data.get("trailingPE"),
        "summary": f"{ticker} at ${data['regularMarketPrice']:.2f} "
                   f"({'up' if data['regularMarketChangePercent'] > 0 else 'down'} "
                   f"{abs(data['regularMarketChangePercent']):.1f}%)"
    }

Zwracaj błędy, na podstawie których pętla może działać

Obsługa błędów wymaga czterech odrębnych mechanizmów, ponieważ każdy z nich obsługuje inną klasę awarii:

1. Ponawianie z exponential backoff dla błędów przejściowych
2. Łańcuchy fallbacków modeli w przypadku awarii dostawców
3. Routing klasyfikacji błędów — błędy przejściowe są ponawiane, błędy możliwe do naprawienia przez LLM wracają do agenta wraz z kontekstem, a błędy wymagające człowieka są eskalowane
4. Odzyskiwanie z checkpointów w celu przetrwania awarii

„Writing effective tools for agents” Anthropic zaleca czytelne błędy narzędzi i projektowanie narzędzi oparte na ewaluacji, ale nie podaje uniwersalnej liczby określającej, ile awarii odzyskują te cztery mechanizmy. Mierz współczynnik odzyskiwania, ponowienia i eskalacje na własnym zestawie zadań.

import httpx
from tenacity import retry, retry_if_exception, stop_after_attempt, wait_exponential

def is_transient_error(error: BaseException) -> bool:
    if isinstance(error, (httpx.TimeoutException, httpx.NetworkError)):
        return True
    if isinstance(error, httpx.HTTPStatusError):
        return error.response.status_code == 429 or 500 <= error.response.status_code < 600
    return False

@retry(
    retry=retry_if_exception(is_transient_error),
    stop=stop_after_attempt(3),
    wait=wait_exponential(multiplier=1, min=2, max=10),
    reraise=True,
)
def call_stock_api(ticker: str) -> dict:
    """Fetch stock data with automatic retry on transient failures.

    Mechanism 1 of the four above: exponential backoff for rate limits
    and network blips.
    This only retries transient transport failures. If attempts are exhausted,
    Tenacity re-raises the original httpx exception.
    """
    response = httpx.get(
        f"https://api.example.com/v1/quotes/{ticker}",
        timeout=10.0,
    )
    response.raise_for_status()
    return response.json()

Wywołujący lub harness nadal musi wykonać kolejny krok: przekształcić ten wyjątek w stabilny wynik informujący, która operacja się nie powiodła, czy należy ją ponowić i co zrobić dalej. Nieponawialny błąd 4xx omija ten dekorator i wymaga takiej samej obsługi. Ponowienie żądania nie klasyfikuje jego błędu ani nie odzyskuje checkpointu.

Zastosowanie wzorców do Market Analyst Agent

Market Analyst Agent z części 1 pokazuje wpływ interfejsu w praktyce.

Konsolidacja narzędzi

Pierwotne moduły narzędzi definiowały get_stock_price, get_company_metrics, get_price_history, dwa narzędzia wyszukiwania oraz execute_trade. W przypadku podstawowej analizy agent musiał wybrać zarówno wywołanie ceny, jak i metryk; kapitalizacja rynkowa i P/E były polami get_company_metrics, a nie samodzielnymi narzędziami. Kod źródłowy sprzed konsolidacji pokazuje ten wcześniejszy interfejs.

Przekształciłem interfejs danych rynkowych w 5 wysokopoziomowych narzędzi, kierując się zasadą ACI dotyczącą zwięzłych i wydajnych działań. Lista narzędzi ReAct w repozytorium zawiera obok nich jeszcze cztery — loader skilla, dwa wrappery CLI oraz ograniczony ewaluator Pythona działający w procesie (allowlista AST, a nie sandbox; część 4 omawia to szerzej) — obejmujące trzy z pięciu opisanych wyżej rodzajów narzędzi. MCP występuje jako sidecar, a nie jako narzędzie na tej liście:

To przenosi cenę i wycenę do jednej definicji ukształtowanej wokół zadania oraz dodaje sprawozdania finansowe jako jawne działanie. To, czy poprawia to wybór narzędzi, jest twierdzeniem, które należy przetestować na reprezentatywnych żądaniach i śladach.

Ustrukturyzowane dane wyjściowe wyników narzędzi

Narzędzia akcji i wiadomości zwracają odpowiedzi zwalidowane przez Pydantic. Wrappery CLI i wykonywania kodu zwracają str, dlatego poniższe modele opisują ustrukturyzowane wyniki narzędzi, a nie każdy wrapper w repozytorium:

from pydantic import BaseModel

class StockSnapshot(BaseModel):
    """Structured tool response — the agent never sees raw API noise."""
    ticker: str
    price: float
    change_pct: float
    volume: int
    market_cap_b: float
    pe_ratio: float | None
    summary: str  # Human-readable one-liner for direct use in reports

class NewsItem(BaseModel):
    """One news item pre-processed for agent consumption."""
    headline: str
    source: str
    date: str
    relevance_score: float  # Pre-ranked so the agent doesn't waste tokens sorting
    key_points: list[str]  # Extracted by the tool, not the agent

class NewsSearchResult(BaseModel):
    query: str
    results: list[NewsItem]
    summary: str

Pole summary zapewnia agentowi gotowy do użycia string na potrzeby raportu. NewsItem.key_points chronią model przed koniecznością parsowania treści artykułów. Jeśli kolejne działanie potrzebuje ID, zachowaj je w szczegółowej odpowiedzi albo zaoferuj tryby zwięzły i szczegółowy; nie usuwaj go wszędzie.

Kompromisy i kwestie do rozważenia

Poza zastrzeżeniami dotyczącymi poszczególnych wzorców kilka przekrojowych kwestii wpływa na wybór:

• Koszt operacyjny różni się w zależności od wymiaru. Wykonywanie kodu oszczędza tokeny, ale dodaje opóźnienie zimnego startu sandboxa. MCP oszczędza czas programistyczny przy integracjach SaaS, ale dodaje narzut wdrażania serwera. CLI można uruchomić niemal bezkosztowo, lecz trudniej zarządzać nim na dużą skalę. Optymalizuj rzeczywiste wąskie gardło — koszt tokenów, opóźnienie albo złożoność operacyjną.

• Umiejętności zespołu mają znaczenie. Wykonywanie kodu zakłada, że agenci — oraz stojące za nimi modele — potrafią niezawodnie generować Python lub TypeScript. CLI zakłada znajomość konwencji Uniksa. MCP wymaga rozumienia protokołów transportowych i przepływów OAuth. Dobierz mechanizm do mocnych stron zespołu.

• Konsolidacja narzędzi może posunąć się za daleko. Jeśli jedno narzędzie zgromadzi niezwiązane ze sobą tryby i argumenty, agent napotka inny problem wyboru — tym razem wewnątrz schematu. Używaj ewaluacji wyboru narzędzi i skuteczności zadań, aby znaleźć właściwy interfejs dla danego obciążenia.

• Skills opierają się na promptach i nie są egzekwowane. Skill zawiera instrukcje, których agent powinien przestrzegać, a nie guardrails, których musi przestrzegać. Pakiet skilla może zawierać dowolne pliki i wykonywalne skrypty, dlatego ufaj jego źródłu, przejrzyj pakiet i pozwól hostowi egzekwować uprawnienia dla każdego zasobu, który może odczytywać, zmieniać lub wykonywać. W krytycznych przepływach łącz Skills z deterministyczną walidacją.

• Wymagania audytowe wpływają na wybór. Ustrukturyzowane wywołania MCP i JSON są wygodnymi zdarzeniami do logowania, ale żaden z protokołów nie tworzy od razu kompletnego śladu audytowego. Host, serwer lub harness musi rejestrować wywołania i wyniki, a następnie egzekwować autoryzację, politykę, retencję i przeglądy. Wykonywanie kodu wymaga takiej samej instrumentacji wokół sandboxa; sam skrypt i jego wynik nie są zapisem zgodności.

Trzy kierunki rozwoju narzędzi agentów AI na dużą skalę

Pierwszym jest tool RAG służący do skalowania. Zanim model wybierze narzędzie, wyszukaj kilka opisów narzędzi pasujących do żądania i pozwól mu wybierać z tego podzbioru zamiast z pełnego rejestru. W zadaniach benchmarku RAG-MCP i teście obciążeniowym MCP bazowa dokładność wyboru narzędzi wynosiła 13,62%; wyszukiwanie podniosło ją do 43,13%, czyli 3,2 raza, jednocześnie zmniejszając liczbę tokenów promptu z 2133,84 do 1084 (około 49,2%). Abstrakt artykułu mówi o „ponad 50%”, a opisy generatora i ewaluatora różnią się między sekcjami; te niespójności ograniczają interpretację. Wynik jest dowodem dla tej konfiguracji ewaluacyjnej, a nie uniwersalnym wskaźnikiem naiwnego wyboru wraz ze wzrostem zestawu narzędzi.

Drugim kierunkiem są agenci tworzący własne narzędzia. Framework LATM („LLMs As Tool Makers”) ustanowił dwuetapowy paradygmat, w którym wydajny LLM tworzy wielokrotnego użytku funkcje w Pythonie, a lekki LLM z nich korzysta. W benchmarku ToolMaker obejmującym 15 zadań z artykułów posiadających publiczne repozytoria kodu, przekazanych jako adresy URL GitHub i krótkie opisy zadań, poprawnie zaimplementowano 12 z 15 zadań; benchmark zawiera łącznie ponad 100 testów. Ten niewielki benchmark zadań repozytoryjnych nie dowodzi niezawodności produkcyjnej. Oba kierunki wykraczają poza korzystanie z narzędzi — w stronę ich tworzenia, a następnie zarządzania biblioteką wygenerowanych narzędzi.

Trzecim kierunkiem jest dwuprotokołowy stos A2A + MCP. Google przekazał A2A Linux Foundation w czerwcu 2025 r. Dokumentacja protokołu A2A rozdziela te odpowiedzialności: MCP łączy agenta z narzędziami i zasobami, natomiast A2A umożliwia niezależnym agentom wzajemne wykrywanie, negocjowanie interakcji, zarządzanie współdzielonymi zadaniami i delegowanie pracy.

Porównuj interfejsy na identycznych zadaniach i przy tych samych dozwolonych operacjach. Rejestruj tokeny wykrywania, wejście z cache i bez cache, dane wyjściowe wykonania, ponowienia, opóźnienie oraz skuteczność osiągnięcia stanu końcowego. Testuj zarówno pominięte wykrywanie, jak i oszczędność tokenów; w przypadku programów generowanych zliczaj błędy składni, błędy wykonania i częściowe ukończenie.

Najważniejsze wnioski

1. Wybieraj interfejs wykonywania na podstawie działania: wywołania JSON dla małych, typowanych operacji, MCP dla współdzielonych usług, CLI dla ugruntowanych poleceń, a kod w sandboxie dla lokalnej kompozycji. Używaj Skills do dokumentowania sposobu wyboru i korzystania z tego interfejsu.
2. Zachowuj warunki benchmarku przy wyniku. CodeAct, Anthropic, Vercel, Cloudflare, Apideck i Scalekit mierzyli różne modele, zadania, narzędzia i harnessy.
3. Jakość ACI pozostaje istotna mimo zmian protokołów. Jasne działania, zwięzłe informacje zwrotne, walidacja i użyteczne błędy pomagają w każdym rodzaju interfejsu.
4. Konsoliduj nakładające się narzędzia tylko wtedy, gdy ewaluacje pokażą, że mniejszy interfejs poprawia wybór lub skuteczność zadań.
5. Bezpieczeństwo podąża za możliwościami wykonywania. Interfejsy shell i kodu wymagają sandboxingu; MCP wymaga ograniczonej tożsamości i polityki serwera; Skills pozostają instrukcjami, a nie mechanizmem egzekwowania.

Kolejna warstwa to polityka

Część 4, AI Agent Security, omawia sprawdzenie harnessu między proponowanym wywołaniem narzędzia a jego wykonaniem. Część 5 umieszcza narzędzie i jego sandbox w środowisku umożliwiającym odzyskiwanie po awarii. Część 6 dodaje kontrakt, którego model nie widzi: kategorię skutku, regułę ponawiania i ustrukturyzowany wynik, który acceptance check może odczytać bez parsowania prozy.

Materiały referencyjne

Artykuły naukowe

• Executable Code Actions Elicit Better LLM Agents (CodeAct) — Wang i in., ICML 2024 — działania oparte na kodzie zapewniały w zadaniach z artykułu do 20 punktów procentowych wyższą skuteczność zadań
• SWE-agent: Agent-Computer Interfaces Enable Automated Software Engineering — Yang, Jimenez i in., NeurIPS 2024 — zasady projektowania ACI i ewaluacja SWE-bench (18,0% dla SWE-agent wobec 7,3% dla shell-only bez demonstracji w ablation na 300 zadaniach SWE-bench Lite; warunki interfejsu i demonstracji różnią się)
• RAG-MCP: Mitigating Prompt Bloat in LLM Tool Selection — w zadaniach benchmarku i teście obciążeniowym MCP dokładność wyboru wzrosła z 13,62% do 43,13%
• LLMs As Tool Makers (LATM) — Cai i in., 2023 — dwuetapowy paradygmat tworzenia narzędzi przez agentów
• ToolMaker: LLM Agents Making Agent Tools — Wolflein i in., ACL 2025 — 80% w benchmarku obejmującym 15 zadań z artykułów posiadających publiczne repozytoria kodu
• MCPTox: A Benchmark for Tool Poisoning Attack on Real-World MCP Servers — średnia skuteczność ataku 72,8% dla o1-mini w benchmarku obejmującym 20 agentów i 45 serwerów

Inżynieria Anthropic

• Advanced Tool Use / Programmatic Tool Calling — Tool Search (przybliżone rozmiary kontekstu ~77 tys. i ~8,7 tys.), PTC i przykłady korzystania z narzędzi
• Code Execution with MCP — 98,7% redukcji liczby tokenów (ze 150 tys. do 2 tys.) dzięki orkiestracji narzędzi opartej na kodzie
• Writing Effective Tools for Agents — projektowanie opisów narzędzi; przykłady danych wejściowych poprawiają dokładność; enum response_format (72 wobec 206 tokenów)
• Building Effective Agents — ACI jako podstawowa zasada projektowa

Specyfikacje protokołów

• Google Cloud donates A2A to Linux Foundation — ogłoszenie z 23 czerwca 2025 r. dotyczące przekazania protokołu, SDK i narzędzi
• A2A and MCP: Detailed Comparison — dokumentacja protokołu A2A dotycząca uzupełniających się odpowiedzialności agent–agent i agent–narzędzie

Studia przypadku z branży

• Vercel: We Removed 80% of Our Agent’s Tools — stary przykład wymienia 17 narzędzi; nowy udostępnia ExecuteCommand i ExecuteSQL; Vercel przedstawia przebudowę jako usunięcie 80%; skuteczność wzrosła z 4/5 do 5/5 w pięciu reprezentatywnych zapytaniach, wykonanie było 3,5 raza szybsze, a liczba tokenów spadła o 37%
• Cloudflare: Code Mode — wywołania API sterowane przez TypeScript zastępujące schematy narzędzi
• Apideck: MCP Server Eating Your Context Window — 550–1400 tokenów na narzędzie, 55 tys. tokenów dla około 40 narzędzi MCP, 143 tys. z 200 tys. tokenów kontekstu zajętych
• Scalekit: MCP vs CLI Token Benchmark — 4–32 razy większy narzut tokenów dla MCP niż CLI w 75 uruchomieniach benchmarku

Bezpieczeństwo

• Vulnerable MCP Project — raporty podatności służące do konstruowania testów modeli zagrożeń
• AuthZed: Timeline of MCP Breaches — 9 poważnych incydentów bezpieczeństwa MCP (kwiecień–październik 2025)
• Invariant Labs: MCP Tool Poisoning Attacks — zatruwanie narzędzi, rug pulls i eskalacja między originami
• Pivot Point Security: MCP Security Analysis — 43% command injection, 43% błędów uwierzytelniania OAuth

Projektowanie CLI

• Writing CLI Tools That AI Agents Actually Want to Use — Ugo Enyioha — osiem zasad projektowania przyjaznych agentom CLI

Projekt demonstracyjny

• Market Analyst Agent — pełna implementacja z konsolidacją narzędzi i wzorcami ACI

The complete Market Analyst Agent code, including the tool designs described in this post, is on GitHub.