🔧 Co to jest Skill?
W kontekście agentów AI, skill (zwane także tool or function) jest opakowaną, wielokrotnego użytku zdolnością, którą LLM może wywołać, aby wchodzić w interakcje ze światem poza swoim oknem kontekstowym. Skills wypełniają lukę między rozumieniem języka a działaniem w świecie rzeczywistym.
Każdy skill ma cztery komponenty:
- Name — unikalny identyfikator, którego model używa do odwołania się do skilla (np.,
web_search) - Description — tekst w języku naturalnym wyjaśniający, co robi skill i kiedy go używać; LLM czyta to, aby zdecydować, kiedy wywołać skill
- Schemat wejścia — strukturalna definicja argumentów (JSON Schema); model wypełnia je w oparciu o zadanie
- Implementation — rzeczywisty kod, który jest uruchamiany: wywołanie API, zapytanie do bazy danych, polecenie shell lub inna operacja
Przykład: A get_weather skill ma opis "Pobiera aktualną pogodę dla miasta", akceptuje { "city": "string" } jako wejście i wywołuje API pogodowe. LLM nigdy nie widzi klucza API ani wywołania HTTP — otrzymuje tylko wynik zwrócony jako tekst.
⚙️ Jak działa wywoływanie narzędzi
Gdy agent ma dostęp do skills, LLM nie wywołuje ich bezpośrednio — requests wywołanie poprzez wygenerowanie strukturalnego outputu. Runtime (twój kod aplikacji) wykonuje faktyczne wywołanie i zwraca wynik. Oto pełny cykl:
- Rejestracja narzędzia — Twój kod wysyła modelowi listę dostępnych skills z ich opisami i schematami
- Rozumowanie modelu — LLM czyta zadanie i dostępne narzędzia, decyduje, które narzędzie wywołać i z jakimi argumentami
- Żądanie wywołania narzędzia — Model wypisuje strukturalną wiadomość "tool call" (np.,
{ "tool": "web_search", "args": { "query": "current Gemini models" } }) - Execution — Twój runtime wywołuje faktyczną funkcję, API lub usługę
- Wstrzyknięcie wyniku — Wynik jest dodawany z powrotem do kontekstu rozmowy
- Kontynuowane rozumowanie — Model czyta wynik i albo wywołuje kolejne narzędzie, zadaje pytanie uzupełniające, albo generuje ostateczną odpowiedź
Ta pętla może powtarzać się wiele razy w jednym obrocie. Złożone zadanie agentyczne może wywołać 10–20 narzędzi po kolei zanim wygeneruje ostateczną odpowiedź.
📊 Skills vs Plugins vs MCP Servers
Terminologia szybko ewoluowała. Oto, jak koncepcje historycznie się odnoszą:
| Era | Name | Jak to działało | Status |
|---|---|---|---|
| 2023 | ChatGPT Plugins | Rozszerzenia instalowane przez użytkownika z OpenAPI spec; ChatGPT wywoływał je przez HTTP | Przestarzałe (zastąpione przez GPTs + tools) |
| 2023 | OpenAI Function Calling | API-level JSON Schema definitions; model zwraca strukturalne wywołanie funkcji, twój kod je wykonuje | Aktywne — przemianowane na "tool use" |
| 2023– | Tool Use / Skills | Tak samo jak function calling; Anthropic ukuł termin "tool use", inni używają "skills" lub "functions" | Aktywne — obecny standard |
| 2024– | MCP Servers | Standardowy protokół (Anthropic, Dec 2024) do pakowania i dystrybucji serwerów narzędzi; dowolny klient MCP może połączyć się z dowolnym MCP server | Aktywne — rozwijający się ekosystem |
Kluczowa różnica: Tradycyjne użycie narzędzi jest definiowane inline w twoim kodzie aplikacji. MCP servers to oddzielne procesy, które udostępniają narzędzia przez standardowy protokół — czyniąc je wielokrotnego użytku dla różnych klientów AI (Claude Desktop, Cursor, VS Code, custom agents). Czytaj więcej: Co to jest MCP.
🗂️ Kategorie narzędzi i poziomy ryzyka
Nie wszystkie narzędzia niosą takie samo ryzyko. Grupowanie według poziomu ryzyka pomaga zdefiniowaćprzestrzeń działańi gdzie dodać punkty human-in-the-loop:
| Category | Examples | Risk | Recommendation |
|---|---|---|---|
| Read-only | web_search, read_file, get_weather, list_dir | Low | Zezwól na autonomiczne wykonanie; loguj wszystkie wywołania |
| Write (local) | write_file, create_dir, edit_code | Medium | Ogranicz do katalogu roboczego w sandboxie |
| Network / External | send_email, post_to_slack, call_api | Średnie–Wysokie | Zatwierdzenie HITL dla nieodwracalnych wysyłek |
| OS / Shell | run_command, execute_script, install_package | High | Ograniczyć do środowiska kontenerowego; wymagane HITL |
| Destructive | delete_file, drop_table, revoke_access | Critical | Zawsze wymagaj wyraźnego potwierdzenia człowieka |
🏗️ Anatomia dobrego Skilla
Najważniejsza decyzja projektowa dla skilla to jego description. LLM czyta opisy, aby zdecydować, które narzędzie wywołać — źle napisany opis prowadzi do błędnego wyboru narzędzia, przegapionych wywołań lub niejednoznacznych argumentów.
Co czyni opis skutecznym
- Bądź precyzyjny, kiedy go używać — "Użyj tego narzędzia, gdy użytkownik pyta o dane w czasie rzeczywistym lub bieżące wydarzenia" jest lepsze niż "Wyszukuje w sieci"
- Określ, czego NIE robi — "Nie zwraca danych historycznych starszych niż 30 dni"
- Opisz format wyjścia — "Zwraca tablicę JSON wyników wyszukiwania z polami title, url i snippet"
- Utrzymaj poniżej 200 słów — opisy dłuższe niż ~200 tokenów mogą przeciążyć uwagę modelu, gdy zarejestrowanych jest wiele narzędzi
Zasady projektowania schematu
- Wymagane vs opcjonalne — Oznacz pola jako wymagane tylko jeśli naprawdę konieczne; pola opcjonalne z domyślnymi wartościami zmniejszają błędy modelu
- Używaj enumów dla ograniczonych wartości —
"format": {"enum": ["json", "markdown", "text"]}zapobiega wartościom wytworzonym z halucynacji - Preferuj idempotentne narzędzia — Narzędzia, które można bezpiecznie ponowić (odczyty, zapytania), są bezpieczniejsze niż jednorazowe akcje (wysyłki, usunięcia)
- Zwracaj dane strukturalne — Odpowiedzi w JSON są łatwiejsze dla modelu do wnioskowania niż niestrukturalne bloki tekstu
💡 Przykłady z rzeczywistego świata
| Nazwa skilla | Co robi | Kluczowe argumenty | Risk |
|---|---|---|---|
web_search | Zapytaj silnik wyszukiwania i zwróć najlepsze wyniki | query: string, num_results?: number | Low |
read_file | Odczytaj plik z katalogu roboczego | path: string, offset?: number, limit?: number | Low |
write_file | Utwórz lub nadpisz plik | path: string, content: string | Medium |
run_tests | Uruchom testy projektu i zwróć wyniki | filter?: string | Medium |
browser_screenshot | Przejdź do URL i zwróć zrzut ekranu | url: string | Medium |
send_email | Wyślij email do jednego lub więcej odbiorców | to: string[], subject: string, body: string | Wysokie — zawsze HITL |
run_shell | Wykonaj dowolne polecenie shell | command: string, cwd?: string | Wysokie — wymagany sandbox |
✅ Dobre praktyki
Minimalne uprawnienia
Przyznaj agentowi tylko te narzędzia, których potrzebuje do swojego konkretnego zadania. Agent odpowiadający na FAQ nie potrzebuje write_file or send_email. Im mniejsza przestrzeń działań, tym mniejszy promień szkód, jeśli agent zostanie zmanipulowany. Zobacz:Nadmierna autonomia agenta.
Audytuj wszystkie wywołania narzędzi
Loguj każde wywołanie narzędzia z jego argumentami i wynikiem. Umożliwia to debugowanie, przypisywanie kosztów i wykrywanie anomalnego zachowania (np. agent czytający ~/.ssh/ gdy powinien ma mieć dostęp tylko do katalogu projektu). Platformy AgentOps takie jak LangSmith ułatwiają to.
Człowiek w pętli dla działań nieodwracalnych
Każde działanie, które jest trudne lub niemożliwe do cofnięcia — wysyłanie wiadomości, usuwanie danych, dokonywanie zakupów — powinno wymagać wyraźnego potwierdzenia człowieka przed wykonaniem. Wbuduj punkty HITL w runtime agenta, a nie tylko w prompt. Promptów można nadpisać; kodu nie.
Uważaj na tool poisoning
Jeśli pozwolisz agentom na dynamiczne instalowanie lub odkrywanie MCP servers, złośliwy serwer może zarejestrować narzędzie z opisem zawierającym ukryte instrukcje. Zawsze przeglądaj opisy narzędzi przed dodaniem ich do rejestru agenta. Zobacz:Zatrucie narzędzia (Tool Poisoning).
Zwracaj klarowne błędy
Gdy narzędzie zawiedzie, zwróć strukturalny błąd z wystarczającym kontekstem, aby model mógł się odwołać lub eskalować — a nie surowy stack trace wyjątku. Przykład: { "error": "rate_limited", "retry_after": 5 }. Dobrze opisany błąd pozwala agentowi spróbować ponownie, użyć narzędzia zapasowego lub łagodnie poinformować użytkownika.