1 
2Claude Agent SDK vam dava programovy pristup ke stejne smycce agenta, ktera pohani Claude Code. Vasi agenti mohou cist soubory, spoustet shellove prikazy, prohledavat web, editovat kod, volat externi API pres MCP servery a orchestrovat sub-agenty  -  to vse z nekolika radku TypeScriptu nebo Pythonu.
3 
4Na rozdil od standardniho Anthropic Client SDK, kde si stavite vlastni smycku nastroju, Agent SDK se stara o vykonavani nastroju, spravu kontextu, opakovani pokusu a orchestraci interne. Popisete, co chcete, poskytnete nastroje a agent si zbytek vyresi sam.
5 
6## Architektura
7 
8SDK se ridi jednoduchou smyckou: **shromazdi kontext, proved akci, over, opakuj**.
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 
36Hlavnim vstupnim bodem je `query()`, ktery vraci asynchronni iterator streamujici zpravy behem prace agenta. Kazda zprava vam rika, co agent dela: uvazuje, vola nastroj, prijima vysledek nebo dorucuje finalni vystup.
37 
38## Zacatek
39 
40### Instalace
41 
42```bash
43# TypeScript
44npm install @anthropic-ai/claude-agent-sdk
45 
46# Python
47pip install claude-agent-sdk
48```
49 
50Potrebujete API klic Anthropic nastaveny jako `ANTHROPIC_API_KEY` ve vasem prostredi.
51 
52### Vas prvni 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 je vse. Agent pouzije Glob k nalezeni souboru, Grep k hledani vzoru TODO, Read k prozkoumani shod a vrati strukturovany souhrn. Nepisete logiku orchestrace  -  SDK se o to postara.
75 
76### Ekvivalent v Pythonu
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## Vestevene nastroje
92 
93SDK obsahuje stejne nastroje, ktere jsou dostupne v Claude Code:
94 
95| Nastroj | Popis |
96|------|-------------|
97| **Read** | Cte obsah souboru |
98| **Write** | Vytvari nove soubory |
99| **Edit** | Provadi cilene upravy existujicich souboru |
100| **Bash** | Spousti shellove prikazy |
101| **Glob** | Hleda soubory podle vzoru |
102| **Grep** | Prohledava obsah souboru pomoci regex |
103| **WebSearch** | Prohledava web |
104| **WebFetch** | Stahne URL a vrati jeho obsah |
105| **AskUserQuestion** | Pozada uzivatele o vstup |
106 
107Ovladate, ktere nastroje agent muze pouzivat, pomoci `allowedTools`. Pokud nastroj neni na seznamu, agent ho nemuze zavolat.
108 
109## Rezimy opravneni
110 
111Protoze agenti spousteji skutecne prikazy na skutecnych systemech, opravneni jsou dulezita.
112 
113| Rezim | Chovani | Pouziti |
114|------|----------|----------|
115| `default` | Vlastni callback `canUseTool` rozhoduje pri kazdem volani | Jemna kontrola |
116| `acceptEdits` | Automaticke schvaleni operaci se soubory, dotaz na Bash | Vyvojove workflow |
117| `dontAsk` | Zamitne cokoliv mimo allowedTools | Omezeni agenti |
118| `bypassPermissions` | Automaticke schvaleni vseho | Duveryhodna sandboxovana prostredi |
119| `auto` | Klasifikator modelu rozhodne o bezpecnosti | Vyvazena automatizace |
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 
131Pro produkcni pouziti vzdy spoustejte agenty v sandboxovanych prostredich (kontejnery, VM) a pouzivejte nejrestriktivnejsi rezim opravneni, ktery agentovi stale umoznuje vykonavat svou praci.
132 
133## Tvorba vlastnich nastroju s MCP
134 
135Skutecna sila SDK spociva v rozsireni agentu o vase vlastni nastroje. Vlastni nastroje jsou definovany jako in-process MCP servery  -  zadna sprava podprocesu, zadna sitova rezie.
136 
137### Priklad: Nastroj pro pocasi
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 
185Vlastni nastroje se ridi konvenci pojmenovani `mcp__{nazev_serveru}__{nazev_nastroje}`. V `allowedTools` muzete pouzivat zastupne znaky: `"mcp__weather__*"` povoli vsechny nastroje z weather serveru.
186 
187### Priklad: Nastroj pro databazove dotazy
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## Pripojeni externich MCP serveru
218 
219Krome in-process nastroju se muzete pripojit k libovolnemu existujicimu MCP serveru  -  stejnym serverum, ktere funguji s Claude Desktop, Cursor a dalsimi MCP klienty.
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 
239Muzete kombinovat vice MCP serveru. Agent vidi vsechny nastroje ze vsech pripojenych serveru a pouziva je podle potreby.
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## Orchestrace vice agentu
251 
252Pro slozite workflow muzete definovat specializovane sub-agenty, na ktere nadrazeny agent deleguje ukoly. Kazdy sub-agent ma svuj vlastni prompt, nastroje a oblast zameru.
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 
283Pridejte `"Agent"` do `allowedTools` nadruzeneho agenta pro umozneni delegovani. Sub-agenti bezi se svymi vlastnimi nastroji a nemaji pristup k nastrojum rodice, pokud to neni explicitne povoleno.
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## Relace a kontinuita
297 
298Agenti mohou udrzovat kontext mezi vice dotazy pomoci relaci. Zachytte `session_id` z prvni interakce a predejte ho v `resume` pro nasledujici dotazy.
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 
325Pokud nechcete hostovat infrastrukturu agenta sami, **Claude Managed Agents** (spusteno v dubnu 2026) poskytuje plne spravovanou cloudovou sluzbu. Anthropic provozuje kontejnery, stara se o skalovani a poskytuje streamovaci API.
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 
343Klicovy rozdil: s Agent SDK spoustite smycku agenta ve sve vlastni infrastrukture. S Managed Agents Anthropic hostuje a spousti agenta za vas. Komunikujete pres API zalozene na relacich a prijimate udalosti pres Server-Sent Events.
344 
345**Cenik:**
346- **Agent SDK**: pouze standardni sazby za tokeny Claude API. Hosting zajistujete vy.
347- **Managed Agents**: sazby za tokeny plus 0,08 USD za hodinu relace (uctovano po milisekundach).
348 
349## Nejlepsi postupy pro produkci
350 
351### 1. Vzdy izolujte
352 
353Nikdy nespoustejte agenty s neomezenymi opravnenimi na produkcnim stroji. Pouzivejte kontejnery (Docker, Fly.io, Modal) nebo sandboxovana prostredi (E2B, Vercel Sandbox).
354 
355### 2. Omezte pristup k nastrojum
356 
357Ridtse se principem nejmensich opravneni. Agent generujici reporty nepotrebuje `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. Pouzivejte hooky jako ochranne mechanismy
368 
369Hooky vam umoznuji zachytavat volani nastroju pred a po provedeni. Pouzivejte je pro logovani, validaci a omezeni frekvence.
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. Zvladejte chyby elegantne
391 
392Smycka agenta muze produkovat chyby  -  selhani nastroju, limity API, preteceni kontextoveho okna. Vzdy kontrolujte typy zprav.
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. Monitorujte spotreby tokenu
413 
414Smycky agentu mohou spotrebovat vyznamne mnozstvi tokenu, obzvlaste u velkych codebasi. SDK obsahuje automatickou kompakci kontextu, ale i tak byste meli monitorovat spotreby.
415 
416## Zaver
417 
418Claude Agent SDK premeni LLM z stroje na odpovidani otazek v neco blizsiho juniorinimu vyvojari. Vasi agenti mohou cist, psat, spoustet, overovat a iterovat  -  stejny workflow, jaky nasleduje clovek.
419 
420Zacnete v malem: postavte agenta s nekolika vestavenymi nastroji. Pak pridejte vlastni MCP nastroje pro svou konkretni domenu. Skalujte na orchestraci vice agentu, kdyz vase workflow vyzaduji specializaci.
421 
422Smycka agenta je stejna jako ta, ktera pohani Claude Code. Pokud dokaze stavet software, vasi agenti to dokazou take.
423 
424> **Kontrolni seznam pro zacatek:**
425>
426> - [x] Nainstalujte SDK (`npm install @anthropic-ai/claude-agent-sdk`)
427> - [x] Nastavte `ANTHROPIC_API_KEY` ve vasem prostredi
428> - [x] Postavte jednoducheho agenta s vestavenymi nastroji (Read, Glob, Grep)
429> - [x] Pridejte vlastni nastroj pres in-process MCP server
430> - [x] Pripojte externi MCP server (GitHub, PostgreSQL, atd.)
431> - [x] Implementujte orchestraci vice agentu se sub-agenty
432> - [x] Nastavte sandboxovane prostredi pro produkci
433> - [x] Pridejte hooky pro logovani a ochranne mechanismy
434