1~
2يمنحك Claude Agent SDK وصولاً برمجياً إلى نفس حلقة الوكيل التي تشغل Claude Code. يمكن لوكلائك قراءة الملفات، وتنفيذ أوامر shell، والبحث في الويب، وتحرير الكود، واستدعاء واجهات API خارجية من خلال خوادم MCP، وتنسيق الوكلاء الفرعيين  -  كل ذلك من بضعة أسطر من TypeScript أو Python.
3~
4على عكس Anthropic Client SDK المعياري حيث تبني حلقة الأدوات الخاصة بك، يتولى Agent SDK تنفيذ الأدوات وإدارة السياق وإعادة المحاولات والتنسيق داخلياً. أنت تصف ما تريد، وتوفر الأدوات، والوكيل يكتشف الباقي.
5~
6## البنية المعمارية
7~
8يتبع SDK حلقة بسيطة: **اجمع السياق، اتخذ إجراءً، تحقق، كرر**.
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 يبث الرسائل أثناء عمل الوكيل. كل رسالة تخبرك بما يفعله الوكيل: التفكير، أو استدعاء أداة، أو استلام نتيجة، أو تقديم المخرج النهائي.
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~
93يأتي SDK مع نفس الأدوات المتوفرة في 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` | موافقة تلقائية على كل شيء | بيئات sandboxed موثوقة |
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للاستخدام في الإنتاج، شغل الوكلاء دائماً في بيئات معزولة (حاويات، VMs) واستخدم وضع الصلاحيات الأكثر تقييداً الذي لا يزال يسمح للوكيل بأداء عمله.
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}`. يمكنك استخدام أحرف البدل في `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لسير العمل المعقدة، يمكنك تعريف وكلاء فرعيين متخصصين يفوض إليهم الوكيل الأصلي. لكل وكيل فرعي موجهه وأدواته ومجال تركيزه الخاص.
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يمكن للوكلاء الحفاظ على السياق عبر استعلامات متعددة باستخدام الجلسات. التقط `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. استخدم العزل دائماً
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~
369تتيح لك Hooks اعتراض استدعاءات الأدوات قبل وبعد التنفيذ. استخدمها للتسجيل والتحقق وتحديد المعدل.
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، تجاوز نافذة السياق. تحقق دائماً من أنواع الرسائل.
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يمكن لحلقات الوكيل استهلاك رموز كبيرة، خاصة مع قواعد الكود الكبيرة. يتضمن SDK ضغط سياق تلقائي، لكن يجب عليك مراقبة الاستهلاك.
415~
416## الخلاصة
417~
418يحول Claude Agent SDK نموذج اللغة الكبير من آلة للإجابة على الأسئلة إلى شيء أقرب إلى مطور مبتدئ. يمكن لوكلائك القراءة والكتابة والتنفيذ والتحقق والتكرار  -  نفس سير العمل الذي يتبعه الإنسان.
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~