Claude Agent SDK to oficjalny narzędzie programistyczne Anthropic do budowy długoterminowych agentów AI. Różni się od zwykłego API Claude tym, że ma wbudowane mechanizmy potrzebne w realnych procesach biznesowych: persystencję sesji między wywołaniami, użycie narzędzi z walidacją, sub-agentów, prompt caching oraz strumieniowanie odpowiedzi. W tym artykule pokazujemy, kiedy warto sięgnąć po SDK zamiast pisać własną integrację z API, jakie wzorce wdrażamy u klientów MŚP oraz jak ten stos technologiczny mapuje się na nasz pakiet AI Assistant V0.1.
Czym jest Claude Agent SDK
Claude Agent SDK to biblioteka udostępniana przez Anthropic w dwóch wariantach językowych: Python oraz TypeScript. Dostępna jest oficjalnie w dokumentacji Anthropic i stanowi nadbudowę nad surowym API Claude. Nadbudowa oznacza, że SDK podejmuje za nas decyzje architektoniczne, które przy własnym wdrożeniu trzeba by zaprojektować od zera: kiedy uruchomić nową sesję, jak buforować długie konteksty, jak obsłużyć błędy narzędzi.
W praktyce SDK dostarcza pięć kluczowych mechanizmów. Pierwszy to prompt caching, który redukuje koszt powtarzających się zapytań o około 90 procent. Drugi to tool use, czyli wywoływanie funkcji aplikacji w środku rozmowy modelu z użytkownikiem. Trzeci to sub-agents, czyli delegowanie zadań do osobnych instancji Claude z własnym oknem kontekstu. Czwarty to stan sesji, pozwalający zachować historię rozmowy między wywołaniami bez ręcznego sklejania kontekstu. Piąty to strumieniowanie odpowiedzi, kluczowe dla interfejsów konwersacyjnych takich jak Telegram czy WhatsApp.
SDK nie jest wymagany do pracy z Claude. Można równie dobrze wywoływać model przez czyste REST API. Różnica polega na tym, że dla agentów wielokrokowych (a takie buduje większość biznesów MŚP) SDK oszczędza tygodnie kodu i błędów. Dla pojedynczych wywołań typu „podsumuj ten dokument” SDK jest nadmiarowy.
Kiedy Claude Agent SDK, a kiedy zwykłe API Claude
Decyzja zależy od czterech zmiennych: liczby tur w rozmowie, częstotliwości wywoływania narzędzi, znaczenia kosztu tokenów oraz potrzeby orkiestracji wielu agentów jednocześnie. Im więcej z tych czynników występuje w naszym przypadku, tym mocniejszy argument za SDK.
Claude Agent SDK wybieramy gdy agent prowadzi wielokrokowe rozmowy z zachowaniem stanu (na przykład asystent operacyjny odpowiadający przez tydzień na powiązane zapytania klienta). Wybieramy go też gdy często wywołujemy narzędzia (Gmail, Kalendarz, CRM, własna baza danych) i potrzebujemy spójnej obsługi błędów. Trzeci scenariusz to projekty, w których koszt tokenów jest znaczący: prompt caching redukuje rachunek o około 90 procent, co przy 10 000 zapytań miesięcznie przekłada się na różnicę między 1 200 a 120 PLN miesięcznie na input tokens. Czwarty to potrzeba uruchamiania równoległych sub-agentów do specjalistycznych zadań (research, walidacja, generowanie).
Czyste API Claude wybieramy, gdy interesuje nas jednorazowe wywołanie („przetłumacz ten tekst”, „sklasyfikuj tę wiadomość”), gdy mamy własną orkiestrację agentów (na przykład napisaną w n8n lub w warstwie aplikacyjnej Next.js), albo gdy budujemy proste prototypy, w których koszt mniejszy niż 50 PLN miesięcznie nie wymaga optymalizacji cachowaniem. Więcej o kosztach AI w MŚP znajdziesz w naszym przewodniku wdrażania AI w firmie.
Cztery wzorce dla MŚP, w których SDK się zwraca
Z naszej praktyki wdrażania asystentów AI w firmach 5 do 30 osobowych wyłoniły się cztery powtarzalne wzorce, w których Claude Agent SDK przynosi najwięcej wartości. Każdy z nich wykorzystuje co najmniej dwa kluczowe mechanizmy SDK (prompt caching plus tool use, albo sub-agents plus stan sesji).
Wzorzec pierwszy: asystent Telegram za klient z personą. To stos pakietu AI Assistant V0.1. Bot dla pojedynczego klienta z dedykowaną personą (rzeczowy styl, dane historyczne firmy w instrukcja systemowa). SDK obsługuje stan rozmowy między wiadomościami, prompt caching trzyma 8 000 tokenów persony w pamięć podręczna na 5 minut, narzędzia łączą się z Gmail (czytaj inbox, draft replies), Kalendarzem (sprawdzaj okno czasowe, twórz spotkania) oraz CRM-em (pobieraj dane klienta, aktualizuj notatki).
Wzorzec drugi: orkiestrator proces z wieloma narzędziami. Pojedyncze polecenie biznesowe (na przykład „umów spotkanie z Janem, wyślij mu wczorajszą ofertę, zapisz notatkę w CRM”) wymaga 4 do 8 wywołań narzędzi w jednym cyklu. SDK zarządza tym ciągiem, obsługuje błędy za narzędzie i zapisuje ślad audytowy każdej akcji.
Wzorzec trzeci: pipeline przetwarzania dokumentów. Faktury PDF, umowy, dokumenty kadrowe. SDK z sub-agentami pozwala podzielić zadanie: jeden sub-agent ekstrahuje pola, drugi waliduje zgodność z bazą NIP, trzeci klasyfikuje typ kosztu. Każdy z izolowanym kontekstem, bez wzajemnego zatruwania.
Wzorzec czwarty: agent obsługi klienta z eskalacją. Standardowe pytania (status zamówienia, godziny otwarcia, polityka zwrotów) agent obsługuje sam z wykorzystaniem RAG na bazie wiedzy klienta. Pytania nieobjęte regułami eskaluje do człowieka z pełnym kontekstem rozmowy. Sub-agent ewaluacyjny decyduje o eskalacji równolegle do głównej rozmowy. Szczegółowe wzorce automatyzacji obsługi opisaliśmy w artykule o automatyzacji B2B.
Prompt caching: dlaczego jest kluczowy dla kosztu
Anthropic wprowadził prompt caching w 2024 roku i to jedna z najważniejszych funkcji ekonomicznych Claude dla zastosowań biznesowych. Mechanizm działa prosto: deklarujemy fragmenty promptu jako buforowalne (instrukcja systemowa, definicje narzędzi, długi kontekst dokumentów), a Anthropic trzyma je w pamięci przez 5 minut. Każde kolejne zapytanie w tym oknie czasowym kosztuje 10 procent standardowej stawki za input tokens.
Konkretnie: Claude Sonnet kosztuje 3 USD za milion input tokens. Bez pamięć podręczna, agent z instrukcja systemowaem 8 000 tokenów wykonujący 1 000 zapytań dziennie zużywa 8 milionów tokenów, czyli 24 USD dziennie albo 720 USD miesięcznie. Z pamięć podręczna po pierwszym wywołaniu kolejne 999 zapytań kosztuje 10 procent stawki, czyli 2,40 USD dziennie albo 72 USD miesięcznie. Różnica 648 USD miesięcznie tylko na jednym agencie.
Realny punkt odniesienia z naszej praktyki: nasz wewnętrzny system orkiestracji agentów ma instrukcja systemowa 8 000 tokenów. Po pierwszym wywołaniu w 5-minutowym oknie kolejne zapytania kosztują 5 procent pełnej stawki. Przy 50 do 200 zapytaniach dziennie różnica wynosi 90 do 95 PLN miesięcznie. Skala 5 agentów za klient razy 10 klientów to różnica między 4 500 a 450 PLN miesięcznie tylko na input tokens.
SDK robi cachowanie domyślnie. Bez SDK trzeba ręcznie ustawiać nagłówki pamięć podręczna_control w każdym wywołaniu API i pilnować, żeby fragmenty były dokładnie identyczne (każda zmiana tabulatora unieważnia pamięć podręczna). To jeden z najmocniejszych argumentów za SDK przy długoterminowych agentach.
Tool use w SDK: wzorzec wywoływania narzędzi
Tool use to mechanizm pozwalający Claude wywoływać funkcje w naszej aplikacji w środku rozmowy. Schemat każdego narzędzia opisujemy w JSON Schema: nazwa, parametry, typy, opis działania. Claude w odpowiedzi może zwrócić strukturę „wywołaj funkcję X z parametrami Y”, którą nasza aplikacja interpretuje, wykonuje i zwraca wynik z powrotem do modelu.
W praktyce wdrażania biznesowego trzy aspekty wymagają uwagi. Po pierwsze: synchroniczne kontra asynchroniczne narzędzia. Operacje szybkie (odczyt z bazy, pobranie pliku) mogą być sync. Operacje wolne (wysłanie maila, generowanie PDF, zapytanie do zewnętrznego API z latencją) powinny być async, żeby nie blokować rozmowy z użytkownikiem.
Po drugie: obsługa błędów. Każde narzędzie może zawieść (Gmail API rate limit, brak uprawnień, nieprawidłowe dane wejściowe). SDK pozwala zdefiniować strategie ponowienia za narzędzie i komunikuje błędy Claude w sposób, który pozwala mu podjąć decyzję (spróbować inaczej, eskalować do człowieka, poprosić użytkownika o uzupełnienie danych).
Po trzecie: idempotencja narzędzi z efektami ubocznymi. Wysyłka maila, zapis w CRM, naliczenie płatności. Każde takie narzędzie powinno mieć identyfikator idempotencji, żeby ponowne wywołanie przy retry nie zduplikowało akcji. To bardziej kwestia projektowania niż samego SDK, ale SDK ułatwia konsekwentne stosowanie wzorca dispatcher z centralnym audytem.
Sub-agents: kiedy delegować zadanie do osobnego agenta
Sub-agents to drugi obok prompt cachingu mechanizm SDK, który najczęściej wybieramy z całego stosu. Pozwalają stworzyć drugą instancję Claude z własnym oknem kontekstu, własnym instrukcja systemowaem i własnym zestawem narzędzi. Rodzicielski agent może uruchomić sub-agenta narzędziem Task, otrzymać jego raport końcowy i kontynuować pracę.
Cztery sytuacje, w których sub-agent się opłaca: research z dużym zakresem (sub-agent czyta 20 stron dokumentacji, rodzic dostaje 200-słowny raport), parallelizacja (5 sub-agentów równolegle analizuje 5 ofert konkurencji), specjalizacja (sub-agent z instrukcja systemowaem prawnika sprawdza umowę, sub-agent z instrukcja systemowaem księgowego sprawdza fakturę) oraz izolacja kontekstu (sub-agent debuguje błąd bez zatruwania kontekstu głównej rozmowy z klientem).
Sub-agent to wzorzec szczegółowo opisany w naszym artykule o MCP, gdzie pokazujemy jak łączyć sub-agentów z zewnętrznymi narzędziami przez protokół Model Context Protocol.
AI Assistant V0.1: nasz pakiet zbudowany na Claude Agent SDK
Wszystko powyższe to nie teoria. Od czerwca 2026 uruchamiamy pakiet AI Assistant V0.1 jako sub-produkt Hanse Studio. Telegram bot za klient z dedykowaną personą, integracjami Gmail/Kalendarz/jeden CRM oraz 4 do 8 dedykowanymi komendami biznesowymi. konfiguracja 3 000 PLN jednorazowo (kickoff, ekstrakcja stylu z 30-50 maili klienta, konfiguracja, deployment, 2-tygodniowy okres wdrożenia). Stała opieka 800 PLN miesięcznie (hosting, monitoring, comiesięczne usprawnienia, do 2 godzin drobnych poprawek).
Pod spodem stos technologiczny: Claude Agent SDK jako orkiestrator, n8n jako warstwa integracji do narzędzi o niskim tempie zmian (Brevo, Mailchimp, proste webhooks), SQLite na stan za użytkownik, Telegram Bot API jako kanał wejściowy. Hosting Mac Mini lub Hetzner VPS. Stack porównywaliśmy w naszym artykule o platformach automatyzacji.
Jeśli interesuje cię konkretna wycena pod twój przypadek, zapraszamy do rozmowy. Pełną listę pakietów AI znajdziesz w naszej ofercie.
FAQ
Czym Claude Agent SDK różni się od LangChain albo LlamaIndex?
SDK jest natywny dla Claude i daje najlepszą wydajność oraz najprostszy dostęp do funkcji takich jak prompt caching i sub-agents. LangChain to narzędzie programistyczne multi-LLM (Claude, GPT, Gemini, modele lokalne) kosztem wyższej złożoności i lekkiej utraty wydajności. LlamaIndex to narzędzie programistyczne do RAG (retrieval augmented generation) na własnych dokumentach. Dla MŚP z budżetem do 5 000 PLN miesięcznie na AI rekomendujemy SDK plus prosta warstwa RAG, bez LangChain.
Ile kosztuje używanie Claude Agent SDK?
Sam SDK jest darmowy i open source. Płacimy tylko za zużyte tokeny API Claude: Sonnet kosztuje 3 USD za milion input tokens oraz 15 USD za milion output tokens. Dla typowego asystenta MŚP (1 000 do 3 000 zapytań miesięcznie z prompt cachingiem) realny koszt waha się między 50 a 250 PLN miesięcznie za tokeny. Plus hosting, który dla VPS Hetzner zaczyna się od 30 PLN miesięcznie.
Czy SDK nadaje się do aplikacji w czasie rzeczywistym?
Tak. SDK obsługuje strumieniowanie odpowiedzi: Claude wysyła tokeny po jednym, zamiast czekać na pełną odpowiedź. Dla interfejsów konwersacyjnych (Telegram, czat na stronie, WhatsApp) to standard. Pierwszy token pojawia się typowo po 200 do 500 ms, pełna odpowiedź na proste pytanie po 2 do 5 sekundach.
Mogę self-hostować SDK czy działa tylko w chmurze?
SDK to biblioteka Python lub TypeScript. Hostujemy ją gdziekolwiek mamy środowisko uruchomieniowe: VPS, dedykowany serwer w biurze klienta, AWS Lambda, Vercel, Cloudflare Workers, Mac Mini. Sam Claude działa po stronie Anthropic, ale logika agenta z SDK w 100% pod naszą kontrolą. To istotne dla klientów z Niemiec, Austrii i Szwajcarii wymagających, żeby dane nie opuszczały infrastruktury europejskiej (Anthropic ma centra danych w EU).