1 
2Claude Agent SDK دسترسی برنامه‌نویسی به همان حلقه ایجنت را در اختیار شما قرار می‌دهد که Claude Code را به کار می‌اندازد. ایجنت‌های شما می‌توانند فایل‌ها را بخوانند، دستورات shell را اجرا کنند، در وب جستجو کنند، کد را ویرایش کنند، از طریق سرورهای MCP با APIهای خارجی ارتباط برقرار کنند، و ایجنت‌های فرعی را هماهنگ کنند  -  همه از چند خط TypeScript یا Python.
3 
4برخلاف Anthropic Client SDK استاندارد که در آن حلقه ابزار خودتان را می‌سازید، Agent SDK اجرای ابزار، مدیریت context، تلاش‌های مجدد، و هماهنگ‌سازی را به صورت داخلی مدیریت می‌کند. شما توصیف می‌کنید که چه می‌خواهید، ابزارها را فراهم می‌کنید، و ایجنت بقیه را حل می‌کند.
5 
6## معماری
7 
8SDK از یک حلقه ساده پیروی می‌کند: **context جمع کن، اقدام کن، تایید کن، تکرار کن**.
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 
36نقطه ورود اصلی `query()` است، که یک async iterator برمی‌گرداند که در حین کار ایجنت پیام‌ها را stream می‌کند. هر پیام به شما می‌گوید ایجنت چه کار می‌کند: استدلال، فراخوانی ابزار، دریافت نتیجه، یا ارائه خروجی نهایی.
37 
38## شروع کار
39 
40### نصب
41 
42```bash
43# TypeScript
44npm install @anthropic-ai/claude-agent-sdk
45 
46# Python
47pip install claude-agent-sdk
48```
49 
50باید یک کلید Anthropic API را به عنوان `ANTHROPIC_API_KEY` در محیط خود تنظیم کنید.
51 
52### اولین ایجنت شما
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 
74همین. ایجنت از Glob برای یافتن فایل‌ها، Grep برای جستجوی الگوهای TODO، Read برای بررسی تطابق‌ها استفاده می‌کند و یک خلاصه ساختاریافته برمی‌گرداند. شما منطق هماهنگ‌سازی نمی‌نویسید  -  SDK آن را مدیریت می‌کند.
75 
76### معادل 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## ابزارهای داخلی
92 
93SDK با همان ابزارهای موجود در Claude Code عرضه می‌شود:
94 
95| ابزار | توضیحات |
96|------|-------------|
97| **Read** | خواندن محتوای فایل |
98| **Write** | ایجاد فایل‌های جدید |
99| **Edit** | ویرایش هدفمند فایل‌های موجود |
100| **Bash** | اجرای دستورات shell |
101| **Glob** | یافتن فایل‌ها بر اساس الگو |
102| **Grep** | جستجوی محتوای فایل با regex |
103| **WebSearch** | جستجو در وب |
104| **WebFetch** | دریافت یک URL و برگرداندن محتوای آن |
105| **AskUserQuestion** | درخواست ورودی از کاربر |
106 
107شما از طریق `allowedTools` کنترل می‌کنید که ایجنت از کدام ابزارها استفاده کند. اگر ابزاری در لیست نباشد، ایجنت نمی‌تواند آن را فراخوانی کند.
108 
109## حالت‌های مجوز
110 
111از آنجا که ایجنت‌ها دستورات واقعی را روی سیستم‌های واقعی اجرا می‌کنند، مجوزها اهمیت دارند.
112 
113| حالت | رفتار | مورد استفاده |
114|------|----------|----------|
115| `default` | callback سفارشی `canUseTool` در هر فراخوانی تصمیم می‌گیرد | کنترل دقیق |
116| `acceptEdits` | تایید خودکار عملیات فایل، درخواست برای Bash | جریان کار توسعه |
117| `dontAsk` | رد هر چیزی که در allowedTools نیست | ایجنت‌های محدود |
118| `bypassPermissions` | تایید خودکار همه چیز | محیط‌های sandbox قابل اعتماد |
119| `auto` | طبقه‌بند مدل ایمنی را تعیین می‌کند | اتوماسیون متعادل |
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 
131برای استفاده در محیط تولید، همیشه ایجنت‌ها را در محیط‌های ایزوله (کانتینرها، VMها) اجرا کنید و محدودکننده‌ترین حالت مجوزی را استفاده کنید که همچنان به ایجنت اجازه انجام کارش را بدهد.
132 
133## ساخت ابزارهای سفارشی با MCP
134 
135قدرت واقعی SDK از گسترش ایجنت‌ها با ابزارهای خودتان می‌آید. ابزارهای سفارشی به عنوان سرورهای MCP درون‌فرآیندی تعریف می‌شوند  -  بدون مدیریت زیرفرآیند، بدون سربار شبکه.
136 
137### مثال: ابزار آب و هوا
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 
185ابزارهای سفارشی از قرارداد نام‌گذاری `mcp__{server_name}__{tool_name}` پیروی می‌کنند. می‌توانید از wildcard در `allowedTools` استفاده کنید: `"mcp__weather__*"` تمام ابزارهای سرور آب و هوا را مجاز می‌کند.
186 
187### مثال: ابزار کوئری پایگاه داده
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## اتصال به سرورهای MCP خارجی
218 
219فراتر از ابزارهای درون‌فرآیندی، می‌توانید به هر سرور MCP موجودی متصل شوید  -  همان سرورهایی که با Claude Desktop، Cursor، و سایر کلاینت‌های 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 
239می‌توانید چندین سرور MCP را ترکیب کنید. ایجنت تمام ابزارها از تمام سرورهای متصل را می‌بیند و در صورت نیاز از آنها استفاده می‌کند.
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## هماهنگ‌سازی چند ایجنتی
251 
252برای جریان‌های کاری پیچیده، می‌توانید ایجنت‌های فرعی تخصصی تعریف کنید که ایجنت والد کار را به آنها واگذار می‌کند. هر ایجنت فرعی prompt، ابزارها، و حوزه تمرکز خود را دارد.
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 
283برای فعال‌سازی واگذاری، `"Agent"` را در `allowedTools` والد قرار دهید. ایجنت‌های فرعی با ابزارهای خود اجرا می‌شوند و نمی‌توانند به ابزارهای والد دسترسی داشته باشند مگر اینکه صراحتاً اجازه داده شود.
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## جلسات و تداوم
297 
298ایجنت‌ها می‌توانند با استفاده از جلسات، context را در چندین کوئری حفظ کنند. `session_id` را از اولین تعامل ذخیره کنید و در کوئری‌های بعدی در `resume` پاس دهید.
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 
325اگر نمی‌خواهید زیرساخت ایجنت را خودتان میزبانی کنید، **Claude Managed Agents** (راه‌اندازی شده در آوریل 2026) یک سرویس ابری کاملاً مدیریت شده ارائه می‌دهد. Anthropic کانتینرها را اجرا می‌کند، مقیاس‌بندی را مدیریت می‌کند، و یک 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 
343تفاوت اصلی: با Agent SDK، حلقه ایجنت را در زیرساخت خودتان اجرا می‌کنید. با Managed Agents، Anthropic ایجنت را برایتان میزبانی و اجرا می‌کند. از طریق API مبتنی بر جلسه تعامل می‌کنید و رویدادها را از طریق Server-Sent Events دریافت می‌کنید.
344 
345**قیمت‌گذاری:**
346- **Agent SDK**: فقط نرخ‌های استاندارد توکن Claude API. میزبانی بر عهده شماست.
347- **Managed Agents**: نرخ‌های توکن به اضافه $0.08 به ازای هر ساعت جلسه (صورتحساب به ازای میلی‌ثانیه).
348 
349## بهترین شیوه‌های تولید
350 
351### 1. همیشه Sandbox کنید
352 
353هرگز ایجنت‌ها را با مجوزهای نامحدود روی ماشین تولید اجرا نکنید. از کانتینرها (Docker, Fly.io, Modal) یا محیط‌های ایزوله (E2B, Vercel Sandbox) استفاده کنید.
354 
355### 2. دسترسی ابزار را محدود کنید
356 
357اصل حداقل امتیاز را رعایت کنید. ایجنتی که گزارش تولید می‌کند نیازی به `Bash` یا `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. از Hooks برای حفاظ‌ها استفاده کنید
368 
369Hooks به شما اجازه می‌دهند فراخوانی‌های ابزار را قبل و بعد از اجرا رهگیری کنید. از آنها برای ثبت وقایع، اعتبارسنجی، و محدود کردن نرخ استفاده کنید.
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. خطاها را به خوبی مدیریت کنید
391 
392حلقه ایجنت می‌تواند خطا تولید کند  -  شکست ابزار، محدودیت نرخ API، سرریز پنجره context. همیشه نوع پیام‌ها را بررسی کنید.
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. مصرف توکن را نظارت کنید
413 
414حلقه‌های ایجنت می‌توانند توکن‌های قابل توجهی مصرف کنند، به خصوص با codebaseهای بزرگ. SDK شامل فشرده‌سازی خودکار context است، اما همچنان باید مصرف را نظارت کنید.
415 
416## نتیجه‌گیری
417 
418Claude Agent SDK یک LLM را از ماشین پاسخ‌دهی به سوال به چیزی نزدیک‌تر به یک توسعه‌دهنده تازه‌کار تبدیل می‌کند. ایجنت‌های شما می‌توانند بخوانند، بنویسند، اجرا کنند، تایید کنند، و تکرار کنند  -  همان جریان کاری که یک انسان دنبال می‌کند.
419 
420از کوچک شروع کنید: ایجنتی با چند ابزار داخلی بسازید. سپس ابزارهای MCP سفارشی برای دامنه خاص خود اضافه کنید. وقتی جریان‌های کاری شما نیاز به تخصص دارند، به هماهنگ‌سازی چند ایجنتی مقیاس دهید.
421 
422حلقه ایجنت همان است که Claude Code را به کار می‌اندازد. اگر آن می‌تواند نرم‌افزار بسازد، ایجنت‌های شما هم می‌توانند.
423 
424> **چک‌لیست شروع:**
425>
426> - [x] SDK را نصب کنید (`npm install @anthropic-ai/claude-agent-sdk`)
427> - [x] `ANTHROPIC_API_KEY` را در محیط خود تنظیم کنید
428> - [x] یک ایجنت ساده با ابزارهای داخلی (Read, Glob, Grep) بسازید
429> - [x] یک ابزار سفارشی از طریق سرور MCP درون‌فرآیندی اضافه کنید
430> - [x] یک سرور MCP خارجی (GitHub, PostgreSQL و غیره) متصل کنید
431> - [x] هماهنگ‌سازی چند ایجنتی با ایجنت‌های فرعی را پیاده‌سازی کنید
432> - [x] محیط ایزوله برای تولید راه‌اندازی کنید
433> - [x] hooks برای ثبت وقایع و حفاظ‌ها اضافه کنید
434