1~
2Claude Agent SDK, Claude Code'u calistiran ayni ajan dongusune programatik erisim saglar. Ajanlariniz dosyalari okuyabilir, shell komutlarini calistirabilir, web'de arama yapabilir, kod duzenleyebilir, MCP sunuculari uzerinden harici API'leri cagirabilir ve alt ajanlari orkestre edebilir  -  hepsi birkaç satir TypeScript veya Python ile.
3~
4Kendi arac dongunuzu olusturdugumuz standart Anthropic Client SDK'nin aksine, Agent SDK arac calistirma, context yonetimi, yeniden denemeler ve orkestrasyonu dahili olarak yonetir. Ne istediginizi tanimlarsiniz, araclari saglarsiniz ve ajan gerisini halleder.
5~
6## Mimari
7~
8SDK basit bir donguyu takip eder: **context topla, harekete gec, dogrula, tekrarla**.
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~
36Ana giris noktasi `query()` fonksiyonudur; bu fonksiyon ajan calisirken mesajlari stream eden bir async iterator dondurur. Her mesaj ajanin ne yaptigini soyler: muhakeme, arac cagrisi, sonuc alma veya nihai ciktiyi sunma.
37~
38## Baslarken
39~
40### Kurulum
41~
42```bash
43# TypeScript
44npm install @anthropic-ai/claude-agent-sdk
45~
46# Python
47pip install claude-agent-sdk
48```
49~
50Ortaminizda `ANTHROPIC_API_KEY` olarak bir Anthropic API anahtari ayarlamaniz gerekir.
51~
52### Ilk Ajaniniz
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~
74Hepsi bu kadar. Ajan dosyalari bulmak icin Glob, TODO kaliplarini aramak icin Grep, eslesen dosyalari incelemek icin Read kullanacak ve yapilandirilmis bir ozet dondurecektir. Orkestrasyon mantigi yazmak zorunda degilsiniz  -  SDK bunu halleder.
75~
76### Python Karsiligi
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## Yerlesik Araclar
92~
93SDK, Claude Code'da bulunan ayni araclarla gelir:
94~
95| Arac | Aciklama |
96|------|-------------|
97| **Read** | Dosya icerigini oku |
98| **Write** | Yeni dosyalar olustur |
99| **Edit** | Mevcut dosyalarda hedefli duzenlemeler yap |
100| **Bash** | Shell komutlarini calistir |
101| **Glob** | Kaliba gore dosya bul |
102| **Grep** | Regex ile dosya iceriginde ara |
103| **WebSearch** | Web'de ara |
104| **WebFetch** | Bir URL'yi getir ve icerigini dondur |
105| **AskUserQuestion** | Kullanicidan girdi iste |
106~
107Ajanin hangi araclari kullanabilecegini `allowedTools` ile kontrol edersiniz. Bir arac listede yoksa, ajan onu cagiramaz.
108~
109## Izin Modlari
110~
111Ajanlar gercek sistemlerde gercek komutlar calistirdigindan, izinler onemlidir.
112~
113| Mod | Davranis | Kullanim Alani |
114|------|----------|----------|
115| `default` | Ozel `canUseTool` callback'i her cagri icin karar verir | Ince ayar kontrolu |
116| `acceptEdits` | Dosya islemlerini otomatik onayla, Bash icin sor | Gelistirme is akislari |
117| `dontAsk` | allowedTools'da olmayanlarini reddet | Kisitli ajanlar |
118| `bypassPermissions` | Her seyi otomatik onayla | Guvenilir sandbox ortamlari |
119| `auto` | Model siniflandirici guvenlik kararini verir | Dengeli otomasyon |
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~
131Uretim kullanimi icin, ajanlari her zaman sandbox ortamlarinda (konteynerler, VM'ler) calistirin ve ajanin isini yapmasina izin veren en kisitlayici izin modunu kullanin.
132~
133## MCP ile Ozel Araclar Olusturma
134~
135SDK'nin gercek gucu, ajanlari kendi araclarinizla genisletmekten gelir. Ozel araclar islem ici MCP sunuculari olarak tanimlanir  -  alt islem yonetimi yok, ag yuku yok.
136~
137### Ornek: Hava Durumu Araci
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~
185Ozel araclar `mcp__{server_name}__{tool_name}` adlandirma kuralini takip eder. `allowedTools`'da joker karakter kullanabilirsiniz: `"mcp__weather__*"` hava durumu sunucusundaki tum araclara izin verir.
186~
187### Ornek: Veritabani Sorgu Araci
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## Harici MCP Sunucularina Baglanma
218~
219Islem ici araclarin otesinde, mevcut herhangi bir MCP sunucusuna baglanabilirsiniz  -  Claude Desktop, Cursor ve diger MCP istemcileriyle calisan ayni sunucular.
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~
239Birden fazla MCP sunucusunu birlestirebilirsiniz. Ajan bagli tum sunuculardaki tum araclari gorur ve gerektiginde kullanir.
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## Coklu Ajan Orkestrasyonu
251~
252Karmasik is akislari icin, ana ajanin gorev devrettigi uzmanlasmis alt ajanlar tanimlayabilirsiniz. Her alt ajanin kendi prompt'u, araclari ve odak alani vardir.
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~
283Gorev devrini etkinlestirmek icin ana ajanin `allowedTools` listesine `"Agent"` ekleyin. Alt ajanlar kendi araclariyla calisir ve acikca izin verilmedikce ana ajanin araclarina erisemez.
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## Oturumlar ve Sureklilik
297~
298Ajanlar oturumlar kullanarak birden fazla sorgu boyunca context'i koruyabilir. Ilk etkilesimden `session_id`'yi yakalayin ve sonraki sorgularda `resume` ile iletin.
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~
325Ajan altyapisini kendiniz barindirmak istemiyorsaniz, **Claude Managed Agents** (Nisan 2026'da piyasaya suruldu) tamamen yonetilen bir bulut hizmeti sunar. Anthropic konteynerleri calistirir, olceklendirmeyi yonetir ve bir streaming API saglar.
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~
343Temel fark: Agent SDK ile ajan dongusunu kendi altyapinizda calistirirsiniz. Managed Agents ile Anthropic ajaninizi sizin icin barindirir ve calistirir. Oturum tabanli bir API uzerinden etkilesim kurar ve Server-Sent Events araciligiyla olaylar alirsiniz.
344~
345**Fiyatlandirma:**
346- **Agent SDK**: yalnizca standart Claude API token ucretleri. Barindirmayi siz yonetirsiniz.
347- **Managed Agents**: token ucretleri arti oturum saati basina $0.08 (milisaniye bazinda faturalandirilir).
348~
349## Uretim En Iyi Uygulamalari
350~
351### 1. Her Zaman Sandbox Kullanin
352~
353Uretim makinesinde asla sinirlandirilmamis izinlerle ajan calistirmayin. Konteynerler (Docker, Fly.io, Modal) veya sandbox ortamlari (E2B, Vercel Sandbox) kullanin.
354~
355### 2. Arac Erisimini Sinirlandir
356~
357En az yetki ilkesini takip edin. Rapor ureten bir ajanin `Bash` veya `Write`'a ihtiyaci yoktur.
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. Koruma Kalipari Icin Hooks Kullanin
368~
369Hooks, calistirmadan once ve sonra arac cagrilarini yakalmanizi saglar. Bunlari loglama, dogrulama ve hiz sinirlamasi icin kullanin.
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. Hatalari Duzgun Sekilde Ele Alin
391~
392Ajan dongusu hatalar uretebilir  -  arac hatalari, API hiz sinirlari, context penceresi tasmasi. Her zaman mesaj tiplerini kontrol edin.
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. Token Kullanimini Izleyin
413~
414Ajan donguleri ozellikle buyuk kod tabanlariyla onemli miktarda token tuketebilir. SDK otomatik context sikistirma icerir, ancak yine de kullanimi izlemelisiniz.
415~
416## Sonuc
417~
418Claude Agent SDK, bir LLM'yi soru-cevap makinesinden bir junior gelistiriciye daha yakin bir seye donusturur. Ajanlariniz okuyabilir, yazabilir, calistirabilir, dogrulayabilir ve tekrarlayabilir  -  bir insanin takip ettigi ayni is akisi.
419~
420Kucukten baslayin: birkaç yerlesik aracla bir ajan olusturun. Ardindan kendi alaniniz icin ozel MCP araclari ekleyin. Is akislariniz uzmanlasma gerektirdiginde coklu ajan orkestrasyonuna olcekleyin.
421~
422Ajan dongusu, Claude Code'u calistiran aynidir. O yazilim gelistirebiliyorsa, ajanlariniz da gelistirebilir.
423~
424> **Baslangic Kontrol Listesi:**
425>
426> - [x] SDK'yi kurun (`npm install @anthropic-ai/claude-agent-sdk`)
427> - [x] Ortaminizda `ANTHROPIC_API_KEY` ayarlayin
428> - [x] Yerlesik araclarla (Read, Glob, Grep) basit bir ajan olusturun
429> - [x] Islem ici MCP sunucusu araciligiyla ozel bir arac ekleyin
430> - [x] Harici bir MCP sunucusu (GitHub, PostgreSQL, vb.) baglayin
431> - [x] Alt ajanlarla coklu ajan orkestrasyonu uygulayin
432> - [x] Uretim icin sandbox ortami kurun
433> - [x] Loglama ve koruma kaliplari icin hooks ekleyin
434~