1~
2Claude Agent SDK nadaie prohramnyi dostup do toho samoho tsyklu ahenta, shcho stoiit za Claude Code. Vashi ahenty mozhut chytaty faily, vykonuvaty komandy obolonky, shukaty v interneti, redahuvaty kod, vyklykaty zovnishni API cherez MCP-servery ta orkestruvaty sub-ahentiv  -  vse tse z kilkokh riadkiv TypeScript abo Python.
3~
4Na vidminu vid standartnoho Anthropic Client SDK, de vy samoshtihno buduiete tsykl instrumentiv, Agent SDK vnutrishno obrobliaie vykonannia instrumentiv, keruvannia kontekstom, povtorni sproby ta orkestruvannia. Vy opysuiete, shcho khochiete, nadaiete instrumenty, a ahent rozbyraietsia z reshtou.
5~
6## Arkhitektura
7~
8SDK sliduie prostomu tsyklu: **zbyraie kontekst, vykonuie diiu, pereviriate, povtoriuie**.
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~
36Holovnou tochkoiu vkhodu ie `query()`, yaka povertaie asynkhronnyi iterator, shcho transliuie povidomlennia pid chas roboty ahenta. Kozhne povidomlennia kazhe vam, shcho robyit ahent: mirkuie, vyklykaie instrument, otrymuie rezultat abo dostavliaie kintsevyi vyvid.
37~
38## Pochatok roboty
39~
40### Vstanovlennia
41~
42```bash
43# TypeScript
44npm install @anthropic-ai/claude-agent-sdk
45~
46# Python
47pip install claude-agent-sdk
48```
49~
50Vam potriben API-kliuch Anthropic, vstanovlenyi yak `ANTHROPIC_API_KEY` u vashomu otochenni.
51~
52### Vash pershyi ahent
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~
74Ot i vse. Ahent vykorystovuie Glob dlia poshuku failiv, Grep dlia poshuku patterniv TODO, Read dlia vyvchhennia zbihiv i povertaie strukturovane reziume. Vy ne pyshete lohiku orkestratsii  -  SDK berete tse na sebe.
75~
76### Ekvivalent na Python
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## Vbudovani instrumenty
92~
93SDK postachaietsia z tymy samymy instrumentamy, shcho dostupni v Claude Code:
94~
95| Instrument | Opys |
96|------|-------------|
97| **Read** | Chytannia vmistu failiv |
98| **Write** | Stvorennia novykh failiv |
99| **Edit** | Tsilovi pravky v isnuiuchykh failakh |
100| **Bash** | Vykonannia komand obolonky |
101| **Glob** | Poshuk failiv za patternom |
102| **Grep** | Poshuk u vmisti failiv za dopomohoiu regex |
103| **WebSearch** | Poshuk v interneti |
104| **WebFetch** | Zavantazhennia URL ta povernennia yoho vmistu |
105| **AskUserQuestion** | Zapyt vvedennia vid korystuvacha |
106~
107Vy kontroliuiete, yaki instrumenty ahent mozhe vykorystovuvaty, cherez `allowedTools`. Yakshcho instrumenta nemaie u spysku, ahent ne mozhe yoho vyklykaty.
108~
109## Rezhymy dozvoliv
110~
111Oskilky ahenty vykonuiut realni komandy na realnykh systemakh, dozvoly maiut znachennia.
112~
113| Rezhym | Povedinka | Zastosuvannia |
114|------|----------|----------|
115| `default` | Korystuvatskyj callback `canUseTool` vyrishuie pry kozhnomu vyklyku | Tonke nalashtuvannia |
116| `acceptEdits` | Avtozatverdzhemnia failovykh operatsii, zapyt dlia Bash | Robochi protsesy rozrobky |
117| `dontAsk` | Vidkhylennia vsoho, shcho ne v allowedTools | Obmezheni ahenty |
118| `bypassPermissions` | Avtomatychne zatverdzhemnia vsoho | Dovireni sandbox-seredovyshcha |
119| `auto` | Klasyfikator modeli vyrishuie pro bezpeku | Zbalansovana avtomatyzatsiia |
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~
131Dlia produktsiinoho vykorystannia zavzhdy zapuskaiite ahentiv u izolovanykh seredovyshchakh (konteinery, virtualni mashyny) ta vykorystovuiite naistrozhishyi rezhym dozvoliv, yakyi vse shche dozvoliaie ahentu vykonuvaty svoiu robotu.
132~
133## Stvorennia vlasnykh instrumentiv z MCP
134~
135Spravzhnia syla SDK poliahaie u rozshyrenni ahentiv vashymy vlasnymy instrumentamy. Vlasni instrumenty vyznachaiutsia yak in-process MCP-servery  -  bez keruvannia pidprotsesamy, bez merezhnykh nakladnykh vytrat.
136~
137### Pryklad: Instrument pohody
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~
185Vlasni instrumenty sliduiut konventsii naymenuvannia `mcp__{imia_servera}__{imia_instrumenta}`. Vy mozhete vykorystovuvaty pidstavni znaky v `allowedTools`: `"mcp__weather__*"` dozvoliaie vsi instrumenty z servera pohody.
186~
187### Pryklad: Instrument zapytiv do bazy danykh
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## Pidkliuchennia zovnishnikh MCP-serveriv
218~
219Okrim in-process instrumentiv, vy mozhete pidkliuchatysia do bud-yakoho isnuiuchoho MCP-servera  -  tykh samykh serveriv, shcho pratsiuiut z Claude Desktop, Cursor ta inshymy MCP-kliientamy.
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~
239Vy mozhete kombinuvaty kilka MCP-serveriv. Ahent bachyt vsi instrumenty z usikh pidkliuchenykh serveriv ta vykorystovuie ikh za potreboiu.
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## Orkestruvannia kilkokh ahentiv
251~
252Dlia skladnykh robochykh protsesiv vy mozhete vyznachaty spetsializovanykh sub-ahentiv, yakym batkivskyj ahent delehuie zavdannia. Kozhnyj sub-ahent maie vlasnyj prompt, instrumenty ta oblast fokusu.
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~
283Dodaite `"Agent"` do `allowedTools` batkivskoho ahenta dlia vvimknennia delehuvannia. Sub-ahenty pratsiuiut zi svoimy instrumentamy i ne maiut dostupu do instrumentiv batka, yakshcho tse ne nadano yavno.
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## Sesii ta bezperervnist
297~
298Ahenty mozhut pidtrymuvaty kontekst mizh kilkoma zapytamy za dopomohoiu sesii. Zakhopliuite `session_id` z pershoi vzaiemodii ta peredaite yoho u `resume` dlia nastupnykh zapytiv.
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~
325Yakshcho vy ne khochete samoshtiiino rozmishchuvaty infrastrukturu ahenta, **Claude Managed Agents** (zapushchenyj u kvitni 2026) nadaie povnistiu kerovanyj khmarnyi servis. Anthropic zapuskaie konteinery, obrobliaie mashcabuvannia ta nadaie streaming 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~
343Kliuchova vidminnist: z Agent SDK vy zapuskaete tsykl ahenta u vlasnii infrastrukturi. Z Managed Agents Anthropic rozmishchuie ta zapuskaie ahenta za vas. Vy vzaiemodiiete cherez API na osnovi sesii ta otrymyiete podii cherez Server-Sent Events.
344~
345**Tsiny:**
346- **Agent SDK**: tilky standartni taryfy na tokeny Claude API. Khostynh na vashii storoni.
347- **Managed Agents**: taryfy na tokeny plius 0,08 USD za hodynu sesii (taryfikatsiia pomilisekundno).
348~
349## Naikrashchi praktyky dlia produktsii
350~
351### 1. Zavzhdy izoliuite
352~
353Nikoly ne zapuskaiite ahentiv z neobmezhenymy dozvolamy na produktsiinii mashyni. Vykorystovuiite konteinery (Docker, Fly.io, Modal) abo izoliovani seredovyshcha (E2B, Vercel Sandbox).
354~
355### 2. Obmezhuite dostup do instrumentiv
356~
357Dotrymujtesia pryntsypu naimenshykh pryvileiv. Ahentu, shcho heneruie zvity, ne potribni `Bash` abo `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. Vykorystovuiite hooks dlia zakhysnykh mekhanizmiv
368~
369Hooks dozvoliaiut perekhopliuvaty vyklyky instrumentiv do ta pislia vykonannia. Vykorystovuiite ikh dlia lohuvannia, validatsii ta obmezhhennia chastoty.
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. Obrobliajte pomylky elehantno
391~
392Tsykl ahenta mozhe heneruvaty pomylky  -  zboi instrumentiv, limity API, perepovnennia kontekstnoho vikna. Zavzhdy pereviriate typy povidomlen.
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. Monitorte vykorystannia tokeniv
413~
414Tsykly ahentiv mozhut spozhyvaty znachnu kilkist tokeniv, osoblyvo z velykymy bazamy kodu. SDK vkliuchaie avtomatychnu kompaktsiiu kontekstu, ale vy vse odno povynni monitory vykorystannia.
415~
416## Vysnovok
417~
418Claude Agent SDK peretvoriuie LLM z mashyny dlia vidpovidei na pytannia u shchos blyzhche do junior-rozrobnyka. Vashi ahenty mozhut chytaty, pysaty, vykonuvaty, pereviryaty ta iteruvaty  -  toi samyi workflow, yakoho dotrymuietsia liudyna.
419~
420Pochnit z maloho: stvori ahenta z kilkoma vbudovanymy instrumentamy. Potim dodaite vlasni MCP-instrumenty dlia vashoi konkretNoi oblasti. Mashchanuiite do orkestratsii kilkokh ahentiv, koly vashi protsesy vymahaeiut spetsializatsii.
421~
422Tsykl ahenta  -  toi samyi, shcho stoiit za Claude Code. Yakshcho vin mozhe stvoriuvaty prohramne zabezpechennia, vashi ahenty tezh zmozhut.
423~
424> **Chek-lyst dlia pochatku:**
425>
426> - [x] Vstanovit SDK (`npm install @anthropic-ai/claude-agent-sdk`)
427> - [x] Vstanovit `ANTHROPIC_API_KEY` u vashomu otochenni
428> - [x] Stvority prostoho ahenta z vbudovanymy instrumentamy (Read, Glob, Grep)
429> - [x] Dodaty vlasnyj instrument cherez in-process MCP-server
430> - [x] Pidkliuchyty zovnishnij MCP-server (GitHub, PostgreSQL, toshcho)
431> - [x] Realizuvaty orkestruvannia kilkokh ahentiv z sub-ahentamy
432> - [x] Nalashtuvy izoliovane seredovyshche dlia produktsii
433> - [x] Dodaty hooks dlia lohuvannia ta zakhysnykh mekhanizmiv
434~