1 
2Claude Agent SDK daje programistyczny dostep do tej samej petli agenta, ktora napedza Claude Code. Twoi agenci moga czytac pliki, wykonywac komendy powloki, przeszukiwac internet, edytowac kod, wywolywac zewnetrzne API przez serwery MCP i koordynowac sub-agentow  -  wszystko za pomoca kilku linii TypeScript lub Python.
3 
4W przeciwienstwie do standardowego Anthropic Client SDK, gdzie samodzielnie budujesz petle narzedzi, Agent SDK obsluguje wykonywanie narzedzi, zarzadzanie kontekstem, ponawianie prob i orkiestracje wewnetrznie. Opisujesz, czego chcesz, dostarczasz narzedzia, a agent sam rozwiazuje reszte.
5 
6## Architektura
7 
8SDK opiera sie na prostej petli: **zbierz kontekst, podejmij dzialanie, zweryfikuj, powtorz**.
9 
10```mermaid
11graph TD
12    Input[User Prompt] --> Loop[Agent Loop]
13    Loop --> Reason[Claude Reasons]
14    Reason --> Tool[Call Tool]
15    Tool --> Result[Tool Result]
16    Result --> Loop
17    Reason --> Done[Final Response]
18 
19    subgraph "Built-in Tools"
20        T1[Read / Write / Edit]
21        T2[Bash / Terminal]
22        T3[Glob / Grep]
23        T4[WebSearch / WebFetch]
24    end
25 
26    subgraph "Custom Tools via MCP"
27        M1[Your API]
28        M2[Database]
29        M3[Slack / GitHub / etc.]
30    end
31 
32    Tool --> T1
33    Tool --> M1
34```
35 
36Glownym punktem wejscia jest `query()`, ktory zwraca asynchroniczny iterator strumieniujacy wiadomosci w trakcie pracy agenta. Kazda wiadomosc informuje, co agent robi: rozumuje, wywoluje narzedzie, odbiera wynik lub dostarcza koncowy rezultat.
37 
38## Pierwsze kroki
39 
40### Instalacja
41 
42```bash
43# TypeScript
44npm install @anthropic-ai/claude-agent-sdk
45 
46# Python
47pip install claude-agent-sdk
48```
49 
50Potrzebujesz klucza API Anthropic ustawionego jako `ANTHROPIC_API_KEY` w zmiennych srodowiskowych.
51 
52### Twoj pierwszy agent
53 
54```typescript
55import { query } from "@anthropic-ai/claude-agent-sdk";
56 
57const conversation = query({
58  prompt: "Find all TODO comments in the codebase and create a summary",
59  options: {
60    allowedTools: ["Read", "Glob", "Grep"],
61  },
62});
63 
64for await (const message of conversation) {
65  if (message.type === "assistant") {
66    process.stdout.write(message.content);
67  }
68  if (message.type === "result" && message.subtype === "success") {
69    console.log("\nDone:", message.result);
70  }
71}
72```
73 
74To wszystko. Agent uzyje Glob do znalezienia plikow, Grep do wyszukiwania wzorow TODO, Read do przegladania dopasowania i zwroci ustrukturyzowane podsumowanie. Nie piszesz logiki orkiestracji  -  SDK zajmuje sie tym za Ciebie.
75 
76### Odpowiednik w Pythonie
77 
78```python
79from claude_agent_sdk import query
80 
81async for message in query(
82    prompt="Find all TODO comments in the codebase and create a summary",
83    options={"allowed_tools": ["Read", "Glob", "Grep"]},
84):
85    if message.type == "assistant":
86        print(message.content, end="")
87    if message.type == "result" and message.subtype == "success":
88        print(f"\nDone: {message.result}")
89```
90 
91## Wbudowane narzedzia
92 
93SDK zawiera te same narzedzia dostepne w Claude Code:
94 
95| Narzedzie | Opis |
96|------|-------------|
97| **Read** | Odczytuje zawartosc plikow |
98| **Write** | Tworzy nowe pliki |
99| **Edit** | Wprowadza celowane zmiany w istniejacych plikach |
100| **Bash** | Wykonuje komendy powloki |
101| **Glob** | Wyszukuje pliki wedlug wzorca |
102| **Grep** | Przeszukuje zawartosc plikow za pomoca regex |
103| **WebSearch** | Przeszukuje internet |
104| **WebFetch** | Pobiera URL i zwraca jego zawartosc |
105| **AskUserQuestion** | Prosi uzytkownika o wprowadzenie danych |
106 
107Kontrolujesz, z ktorych narzedzi agent moze korzystac, za pomoca `allowedTools`. Jesli narzedzie nie znajduje sie na liscie, agent nie moze go wywolac.
108 
109## Tryby uprawnien
110 
111Poniewaz agenci wykonuja prawdziwe komendy na prawdziwych systemach, uprawnienia maja znaczenie.
112 
113| Tryb | Zachowanie | Zastosowanie |
114|------|----------|----------|
115| `default` | Niestandardowy callback `canUseTool` decyduje przy kazdym wywolaniu | Szczegolowa kontrola |
116| `acceptEdits` | Automatyczne zatwierdzanie operacji na plikach, pytanie o Bash | Procesy deweloperskie |
117| `dontAsk` | Odrzuca wszystko, co nie jest w allowedTools | Ograniczeni agenci |
118| `bypassPermissions` | Automatyczne zatwierdzanie wszystkiego | Zaufane srodowiska sandbox |
119| `auto` | Klasyfikator modelu decyduje o bezpieczenstwie | Zrownowaza automatyzacja |
120 
121```typescript
122const conversation = query({
123  prompt: "Refactor the auth module to use JWT",
124  options: {
125    allowedTools: ["Read", "Edit", "Glob", "Grep", "Bash"],
126    permissionMode: "acceptEdits",
127  },
128});
129```
130 
131W srodowisku produkcyjnym zawsze uruchamiaj agentow w izolowanych srodowiskach (kontenery, maszyny wirtualne) i uzywaj najbardziej restrykcyjnego trybu uprawnien, ktory nadal pozwala agentowi wykonywac swoja prace.
132 
133## Tworzenie wlasnych narzedzi z MCP
134 
135Prawdziwa sila SDK tkwi w rozszerzaniu agentow o wlasne narzedzia. Wlasne narzedzia sa definiowane jako serwery MCP dzialajace w procesie  -  bez zarzadzania podprocesami, bez narzutu sieciowego.
136 
137### Przyklad: Narzedzie pogodowe
138 
139```typescript
140import { tool, createSdkMcpServer, query } from "@anthropic-ai/claude-agent-sdk";
141import { z } from "zod";
142 
143const getTemperature = tool(
144  "get_temperature",
145  "Get the current temperature at a location",
146  {
147    latitude: z.number().describe("Latitude"),
148    longitude: z.number().describe("Longitude"),
149  },
150  async ({ latitude, longitude }) => {
151    const res = await fetch(
152      `https://api.open-meteo.com/v1/forecast?latitude=${latitude}&longitude=${longitude}&current=temperature_2m&temperature_unit=celsius`
153    );
154    const data = await res.json();
155    return {
156      content: [
157        {
158          type: "text",
159          text: `Current temperature: ${data.current.temperature_2m}C`,
160        },
161      ],
162    };
163  }
164);
165 
166const weatherServer = createSdkMcpServer({
167  name: "weather",
168  version: "1.0.0",
169  tools: [getTemperature],
170});
171 
172for await (const message of query({
173  prompt: "What's the weather like in Rome?",
174  options: {
175    mcpServers: { weather: weatherServer },
176    allowedTools: ["mcp__weather__get_temperature"],
177  },
178})) {
179  if (message.type === "result" && message.subtype === "success") {
180    console.log(message.result);
181  }
182}
183```
184 
185Wlasne narzedzia stosuja konwencje nazewnicza `mcp__{nazwa_serwera}__{nazwa_narzedzia}`. Mozesz uzywac symboli wieloznacznych w `allowedTools`: `"mcp__weather__*"` zezwala na wszystkie narzedzia z serwera pogodowego.
186 
187### Przyklad: Narzedzie do zapytan bazodanowych
188 
189```typescript
190const queryDb = tool(
191  "query_database",
192  "Run a read-only SQL query against the application database",
193  {
194    sql: z.string().describe("SQL SELECT query to execute"),
195  },
196  async ({ sql }) => {
197    // Validate: only allow SELECT queries
198    if (!sql.trim().toUpperCase().startsWith("SELECT")) {
199      return {
200        content: [{ type: "text", text: "Error: Only SELECT queries are allowed." }],
201      };
202    }
203 
204    const result = await pool.query(sql);
205    return {
206      content: [
207        {
208          type: "text",
209          text: JSON.stringify(result.rows, null, 2),
210        },
211      ],
212    };
213  }
214);
215```
216 
217## Podlaczanie zewnetrznych serwerow MCP
218 
219Oprocz narzedzi dzialajacych w procesie, mozesz laczyc sie z dowolnym istniejacym serwerem MCP  -  tymi samymi serwerami, ktore dzialaja z Claude Desktop, Cursor i innymi klientami MCP.
220 
221```typescript
222for await (const message of query({
223  prompt: "Check the latest issues in the frontend repo and summarize them",
224  options: {
225    mcpServers: {
226      github: {
227        command: "npx",
228        args: ["-y", "@modelcontextprotocol/server-github"],
229        env: { GITHUB_PERSONAL_ACCESS_TOKEN: process.env.GITHUB_TOKEN },
230      },
231    },
232    allowedTools: ["mcp__github__*"],
233  },
234})) {
235  // ...
236}
237```
238 
239Mozesz laczyc wiele serwerow MCP. Agent widzi wszystkie narzedzia ze wszystkich podlaczonych serwerow i uzywa ich w razie potrzeby.
240 
241```mermaid
242graph LR
243    Agent[Your Agent] --> SDK[Agent SDK]
244    SDK --> InProcess[In-process MCP\nCustom Tools]
245    SDK --> GitHub[GitHub MCP Server]
246    SDK --> Postgres[PostgreSQL MCP Server]
247    SDK --> Slack[Slack MCP Server]
248```
249 
250## Orkiestracja wielu agentow
251 
252W przypadku zlozonych procesow mozesz definiowac wyspecjalizowanych sub-agentow, do ktorych agent nadrzedny deleguje zadania. Kazdy sub-agent ma wlasny prompt, narzedzia i obszar specjalizacji.
253 
254```typescript
255for await (const message of query({
256  prompt: "Review the PR, check for security issues, and update the changelog",
257  options: {
258    allowedTools: ["Read", "Edit", "Bash", "Glob", "Grep", "Agent"],
259    agents: [
260      {
261        name: "security-reviewer",
262        description: "Reviews code for security vulnerabilities",
263        prompt: "You are a security expert. Analyze code for OWASP Top 10 vulnerabilities.",
264        allowedTools: ["Read", "Glob", "Grep"],
265      },
266      {
267        name: "changelog-writer",
268        description: "Updates the CHANGELOG.md file based on recent changes",
269        prompt: "You maintain the project changelog. Follow Keep a Changelog format.",
270        allowedTools: ["Read", "Edit", "Bash"],
271      },
272    ],
273  },
274})) {
275  // The parent agent will:
276  // 1. Read the PR diff
277  // 2. Delegate security review to security-reviewer
278  // 3. Delegate changelog update to changelog-writer
279  // 4. Synthesize results
280}
281```
282 
283Dodaj `"Agent"` do `allowedTools` agenta nadrzednego, aby umozliwic delegowanie. Sub-agenci dzialaja z wlasnymi narzedziami i nie maja dostepu do narzedzi rodzica, chyba ze zostanie to jawnie przyznane.
284 
285```mermaid
286graph TD
287    Parent[Parent Agent] --> SR[Security Reviewer\nRead, Glob, Grep]
288    Parent --> CW[Changelog Writer\nRead, Edit, Bash]
289    SR --> Report[Security Report]
290    CW --> Updated[Updated CHANGELOG]
291    Report --> Parent
292    Updated --> Parent
293    Parent --> Final[Final Summary]
294```
295 
296## Sesje i ciaglosc
297 
298Agenci moga utrzymywac kontekst miedzy wieloma zapytaniami za pomoca sesji. Przechwyc `session_id` z pierwszej interakcji i przekaz go w `resume` dla kolejnych zapytan.
299 
300```typescript
301let sessionId: string | undefined;
302 
303// First query
304for await (const message of query({
305  prompt: "Read the project structure and understand the architecture",
306  options: { allowedTools: ["Read", "Glob", "Grep"] },
307})) {
308  if (message.type === "init") {
309    sessionId = message.session_id;
310  }
311}
312 
313// Follow-up query (same session, full context preserved)
314for await (const message of query({
315  prompt: "Now refactor the auth module based on what you learned",
316  resume: sessionId,
317  options: { allowedTools: ["Read", "Edit", "Bash"] },
318})) {
319  // Agent remembers the full project context from the first query
320}
321```
322 
323## Claude Managed Agents
324 
325Jesli nie chcesz samodzielnie hostowac infrastruktury agenta, **Claude Managed Agents** (uruchomiony w kwietniu 2026) zapewnia w pelni zarzadzana usluge chmurowa. Anthropic prowadzi kontenery, obsluguje skalowanie i udostepnia API strumieniowe.
326 
327```mermaid
328graph LR
329    subgraph "Self-hosted (Agent SDK)"
330        Code[Your Code] --> SDK2[Agent SDK]
331        SDK2 --> API[Claude API]
332        SDK2 --> Tools[Your Tools]
333    end
334 
335    subgraph "Managed Agents"
336        App[Your App] --> MAPI[Managed Agents API]
337        MAPI --> Container[Anthropic-hosted Container]
338        Container --> API2[Claude API]
339        Container --> Tools2[Tools in Container]
340    end
341```
342 
343Kluczowa roznica: z Agent SDK uruchamiasz petle agenta we wlasnej infrastrukturze. Z Managed Agents Anthropic hostuje i uruchamia agenta za Ciebie. Komunikujesz sie przez API oparte na sesjach i otrzymujesz zdarzenia przez Server-Sent Events.
344 
345**Cennik:**
346- **Agent SDK**: tylko standardowe stawki za tokeny Claude API. Hosting po Twojej stronie.
347- **Managed Agents**: stawki za tokeny plus 0,08 USD za godzine sesji (rozliczane co milisekunde).
348 
349## Najlepsze praktyki produkcyjne
350 
351### 1. Zawsze izoluj
352 
353Nigdy nie uruchamiaj agentow z nieograniczonymi uprawnieniami na maszynie produkcyjnej. Uzywaj kontenerow (Docker, Fly.io, Modal) lub izolowanych srodowisk (E2B, Vercel Sandbox).
354 
355### 2. Ogranicz dostep do narzedzi
356 
357Stosuj zasade najmniejszych uprawnien. Agent generujacy raporty nie potrzebuje `Bash` ani `Write`.
358 
359```typescript
360// Too permissive
361allowedTools: ["Read", "Write", "Edit", "Bash", "Glob", "Grep"]
362 
363// Better: only what's needed
364allowedTools: ["Read", "Glob", "Grep"]
365```
366 
367### 3. Uzywaj hookow jako zabezpieczen
368 
369Hooki pozwalaja przechwytywac wywolania narzedzi przed i po wykonaniu. Uzywaj ich do logowania, walidacji i ograniczania czestotliwosci.
370 
371```typescript
372const conversation = query({
373  prompt: "Analyze the codebase",
374  options: {
375    allowedTools: ["Read", "Glob", "Grep"],
376    hooks: {
377      PreToolUse: async (toolName, input) => {
378        console.log(`Tool call: ${toolName}`, input);
379        // Return false to block the call
380        if (toolName === "Bash" && input.command.includes("rm")) {
381          return false;
382        }
383        return true;
384      },
385    },
386  },
387});
388```
389 
390### 4. Obsluguj bledy elegancko
391 
392Petla agenta moze generowac bledy  -  awarie narzedzi, limity API, przepelnienie okna kontekstu. Zawsze sprawdzaj typy wiadomosci.
393 
394```typescript
395for await (const message of conversation) {
396  switch (message.type) {
397    case "assistant":
398      // Agent reasoning
399      break;
400    case "tool_use":
401      // Agent is calling a tool
402      break;
403    case "result":
404      if (message.subtype === "error") {
405        console.error("Agent failed:", message.error);
406      }
407      break;
408  }
409}
410```
411 
412### 5. Monitoruj zuzycie tokenow
413 
414Petle agentow moga zuzyc znaczna ilosc tokenow, szczegolnie w duzych bazach kodu. SDK zawiera automatyczna kompakcje kontekstu, ale i tak powinienes monitorowac zuzycie.
415 
416## Podsumowanie
417 
418Claude Agent SDK zamienia LLM z maszyny odpowiadajacej na pytania w cos blizszego mlodszemu deweloperowi. Twoi agenci moga czytac, pisac, wykonywac, weryfikowac i iterowac  -  ten sam workflow, ktory stosuje czlowiek.
419 
420Zacznij od malego: zbuduj agenta z kilkoma wbudowanymi narzedziami. Potem dodaj wlasne narzedzia MCP dla swojej konkretnej dziedziny. Skaluj do orkiestracji wielu agentow, gdy Twoje procesy wymagaja specjalizacji.
421 
422Petla agenta jest ta sama, ktora napedza Claude Code. Jesli moze budowac oprogramowanie, Twoi agenci tez moga.
423 
424> **Lista kontrolna na start:**
425>
426> - [x] Zainstaluj SDK (`npm install @anthropic-ai/claude-agent-sdk`)
427> - [x] Ustaw `ANTHROPIC_API_KEY` w zmiennych srodowiskowych
428> - [x] Zbuduj prostego agenta z wbudowanymi narzedziami (Read, Glob, Grep)
429> - [x] Dodaj wlasne narzedzie przez serwer MCP dzialajacy w procesie
430> - [x] Podlacz zewnetrzny serwer MCP (GitHub, PostgreSQL, itp.)
431> - [x] Zaimplementuj orkiestracje wielu agentow z sub-agentami
432> - [x] Skonfiguruj izolowane srodowisko do produkcji
433> - [x] Dodaj hooki do logowania i zabezpieczen
434