Claude Agent SDK: jak budować agentów AI natywnie w ekosystemie Anthropic

Claude Agent SDK to oficjalny framework Anthropic do budowania gotowych do produkcji agentów AI bezpośrednio na modelach Claude. Zamiast ręcznie programować pętlę narzędzi agenta, dostajesz w SDK gotowy harness agenta: automatyczne pętle narzędzi, natywną integrację MCP, subagentów, zarządzanie sesjami i kontekstem oraz wbudowany system uprawnień i sandbox. SDK powstało 29 września 2025 r. na bazie Claude Code SDK i korzysta z tego samego zestawu narzędzi, na którym opiera się Claude Code.

Trzy szybkie odpowiedzi

• Czym jest: natywne SDK Anthropic (Python i TypeScript), które daje modelom Claude zarządzane pętle narzędzi, sesje, sandboxing i subagentów, czyli wszystko, co w innym przypadku trzeba samodzielnie zbudować wokół surowego wywołania API modelu LLM.
• Kiedy pasuje: agenci kodujący, agenci badawczy oraz długotrwałe, wieloetapowe zadania w stacku, który świadomie stawia na modele Claude.
• Na co uważać: uzależnienie od dostawcy (Claude), API wciąż w wersji v0.x z breaking changes (stan na 2026 r.), SDK dla Pythona na licencji MIT, SDK dla TypeScriptu własnościowe, korzystanie z obu na warunkach Anthropic Commercial Terms.

Od Claude Code SDK do Claude Agent SDK

Framework nazywał się pierwotnie Claude Code SDK i był technicznym fundamentem agenta kodującego Claude Code. Zmieniając nazwę 29 września 2025 r., Anthropic świadomie pozycjonuje go szerzej: jako uniwersalny harness dla agentów korzystających z narzędzi, w którym programowanie jest już tylko jednym z zastosowań. Główna idea pozostaje ta sama, czyli tzw. „dogfooding”: programiści dostają dokładnie ten sam zestaw narzędzi i ten sam mechanizm pętli, których Anthropic używa wewnętrznie w Claude Code, w tym Read, Write, Edit, Bash, Glob, Grep, WebFetch i WebSearch.

To kluczowa różnica w porównaniu z samym Anthropic Client SDK. W Client SDK pętlę agenta piszesz samodzielnie: wywołanie modelu, odebranie wywołania narzędzia, uruchomienie narzędzia, przekazanie wyniku z powrotem, ponowne wywołanie. Agent SDK przejmuje właśnie tę orkiestrację i uzupełnia ją o elementy potrzebne w produkcji. Sama firma Anthropic radzi w „Building Effective Agents” (grudzień 2024), aby zaczynać od pracy bezpośrednio z API modelu LLM, bo wiele wzorców da się zaimplementować w kilku linijkach kodu. Jeśli korzystasz z frameworka, warto rozumieć kod, który działa pod spodem. Stoi za tym prosta zasada: najpierw najprostsze rozwiązanie, większa złożoność dopiero wtedy, gdy jest potrzebna. Jeśli potrzebujesz tylko pojedynczego wywołania API, nie potrzebujesz frameworka; harness taki jak Agent SDK opłaca się dopiero przy długich, wieloetapowych łańcuchach narzędzi.

Kluczowe elementy

Tool use i zestaw narzędzi Claude Code. SDK zawiera sprawdzone narzędzia Read, Write, Edit, Bash, Glob, Grep, WebFetch i WebSearch. Dzięki nim agent może czytać i zapisywać pliki, wykonywać polecenia powłoki i pobierać treści z sieci bez konieczności samodzielnego definiowania i zabezpieczania tych narzędzi.

Natywna integracja MCP. Model Context Protocol (MCP) jest natywnie wbudowany w Claude Agent SDK; serwery MCP mogą nawet działać in-process. MCP standaryzuje dostęp do zewnętrznych narzędzi, źródeł danych i API. Od przekazania go 9 grudnia 2025 r. do Agentic AI Foundation (AAIF) przy Linux Foundation protokół jest neutralny wobec dostawców; według Anthropic w kwietniu 2026 r. osiągnął ponad 110 milionów miesięcznych pobrań SDK i ponad 10 000 aktywnych serwerów. Dla agencji oznacza to, że integracje zbudowane raz jako serwer MCP można ponownie wykorzystać także poza ekosystemem Anthropic.

Subagenci i sesje. Zamiast klasycznego modelu grafowego (jak w LangGraph) SDK stawia na subagentów i sesje w procesach wieloetapowych i opartych na podziale pracy. Główny agent może uruchamiać wyspecjalizowanych subagentów do zadań cząstkowych; sesje utrzymują kontekst przez wiele kroków. Oficjalnie nie ma natywnej obsługi A2A (protokołu Agent-to-Agent), co odróżnia SDK od Microsoft Agent Framework, CrewAI czy Pydantic AI.

Zarządzanie kontekstem i uprawnieniami oraz sandbox. SDK zarządza kontekstem w ramach sesji i zawiera wbudowany system uprawnień oraz sandboxing. Uprawnienia określają, jakie działania agent może wykonywać, na przykład które pliki może zapisywać lub które polecenia uruchamiać. To ważna dźwignia przy wymaganiach human-in-the-loop i audytowych.

Obserwowalność przez hooki. W przeciwieństwie do LangGraph (LangSmith) czy Pydantic AI (Logfire) SDK nie ma dojrzałej, własnej platformy do obserwowalności. Działa w oparciu o hooki i integruje się z Anthropic Console. Jeśli używasz samego SDK w modelu self-hosted, musisz dodać własne ustrukturyzowane logowanie na potrzeby identyfikowalności i dowodów istotnych z punktu widzenia unijnego AI Act.

Miejsce w ekosystemie Anthropic

Siłą SDK jest ścisłe powiązanie z modelami Claude i z MCP. W warstwowym modelu frameworków zajmuje ono, razem z OpenAI Agents SDK, poziom agent runtime/harness, czyli warstwę powyżej samych SDK dostawców, o innym charakterze niż warstwa frameworków (LangGraph, CrewAI, Pydantic AI). Ta bliskość jest jednocześnie zaletą i ograniczeniem: optymalizacja i zestaw narzędzi są skrojone pod Claude, ale nie ma możliwości przełączenia się na GPT, Gemini czy modele lokalne.

Popularność: według statystyk npm pakiet TypeScript osiągnął w tygodniu od 5 do 11 października 2026 r. około 12,1 mln pobrań, podczas gdy w tygodniu od 1 do 7 lutego 2026 r. było to zaledwie około 1,85 mln. Apple, jeden z najbardziej znanych producentów, natywnie zintegrował SDK z Xcode 26.3.

Perspektywa europejska: suwerenność i licencja

Dla decydentów B2B w Europie kluczowe są dwie kwestie. Po pierwsze rezydencja danych: bezpośredni endpoint Anthropic znajduje się w USA. Przy restrykcyjnych wymaganiach UE i RODO droga prowadzi przez AWS Bedrock (region UE), Google Vertex lub Azure AI Foundry. Kod SDK dla Pythona jest na licencji MIT, ale pakiet zawiera własnościowe narzędzie Claude Code CLI. SDK dla TypeScriptu jest w całości własnościowe. Oba działają lokalnie, endpoint modelu już nie. Stąd klasyfikacja „średnia suwerenność” w porównaniu z frameworkami, które można w pełni hostować samodzielnie, takimi jak n8n (niemiecki dostawca), LangGraph czy Pydantic AI.

Po drugie licencja: kod SDK dla Pythona jest objęty licencją MIT. Według README pakiet zawiera jednak dołączone narzędzie Claude Code CLI, które zgodnie z jego plikiem licencyjnym jest własnościowe (All rights reserved). SDK dla TypeScriptu jest w całości własnościowe. Korzystanie z obu SDK podlega Anthropic Commercial Terms of Service, także wtedy, gdy obsługujesz za ich pomocą produkty dla własnych klientów. To rozróżnienie powinno być jasno uwzględnione w każdej ocenie dostawcy i każdej weryfikacji zakupowej (procurement).

Konkretny przykład

Załóżmy, że agencja buduje agenta badawczego, który przy każdym zapytaniu przeszukuje wewnętrzne dokumenty Markdown, tworzy profil konkurenta i zapisuje wynik w pliku. Z Client SDK zespół musiałby samodzielnie napisać całą pętlę narzędzi, obsługę błędów i zarządzanie kontekstem; według zewnętrznych analiz porównywalnych agentów ReAct to mniej więcej od 40 do ponad 100 linii kodu orkiestracji. Z Claude Agent SDK sprowadza się to do konfiguracji i jednego wywołania (uproszczony przykład w Pythonie, stan na październik 2026, API v0.x):

```python
import asyncio
from claude_agent_sdk import ClaudeAgentOptions, ClaudeSDKClient

options = ClaudeAgentOptions(
model="claude-...", # powiązane z modelami Claude
allowed_tools=["Read", "Glob", "Grep", "WebFetch", "WebSearch", "Agent"],
permission_mode="default", # Write nie jest zatwierdzony z góry
can_use_tool=sprawdz_zgode, # pyta o zgodę przed zapisem (human-in-the-loop)
mcp_servers={"crm": crm_mcp_server}, # natywne połączenie MCP, np. CRM
agents={"badacz": agent_badacz}, # subagent wyłącznie do researchu
setting_sources=["project"], # ładuj tylko ustawienia projektu i CLAUDE.md
)

async def main():
async with ClaudeSDKClient(options=options) as client:
await client.query("Przygotuj profil konkurenta: firma X.")
async for message in client.receive_response():
print(message)

asyncio.run(main())
```

Ważne przy przejściu ze starej nazwy: ClaudeCodeOptions nazywa się teraz ClaudeAgentOptions. setting_sources określa, które pliki ustawień (user, project, local) są wczytywane. Jeśli nic nie podasz, SDK według dokumentacji referencyjnej dla Pythona wczytuje wszystkie trzy; jeśli ustawiasz wartość jawnie, musisz uwzględnić "project", aby obowiązywały reguły projektu i CLAUDE.md. Pętle narzędzi, uruchomienie subagenta badawczego, zarządzanie kontekstem sesji i pytanie o zgodę przed zapisem pliku przejmuje SDK.

Dla agencji i B2B

Claude Agent SDK to właściwy wybór, jeśli strategiczna decyzja o modelu i tak pada na Claude, a nacisk kładziony jest na agentów kodujących, badawczych lub długo działających. Dzięki sprawdzonemu harnessowi i natywnemu połączeniu z MCP znacznie skraca time-to-production. Jeśli natomiast potrzebujesz niezależności od modelu, natywnej komunikacji wieloagentowej przez A2A, dojrzałej własnej platformy obserwowalności lub pełnej suwerenności w UE bez amerykańskiego dostawcy, sprawdź LangGraph, Pydantic AI lub n8n. Blck Alpaca ocenia dla klientów z całej Europy łącznie framework, ścieżkę hostingu (Bedrock/Vertex/Azure UE) i konsekwencje licencyjne, tak aby prototyp stał się zgodnym z RODO wdrożeniem produkcyjnym. Wszystkie dane dotyczące wersji, cen i popularności odzwierciedlają stan na 2026 r. i przed rozpoczęciem projektu należy je ponownie zweryfikować.