1~
2Claude Agent SDK آپ کو اسی ایجنٹ لوپ تک پروگرامیٹک رسائی دیتا ہے جو Claude Code کو طاقت دیتا ہے۔ آپ کے ایجنٹس فائلیں پڑھ سکتے ہیں، شیل کمانڈز چلا سکتے ہیں، ویب تلاش کر سکتے ہیں، کوڈ ایڈٹ کر سکتے ہیں، MCP سرورز کے ذریعے ایکسٹرنل APIs کال کر سکتے ہیں، اور سب ایجنٹس کو آرکیسٹریٹ کر سکتے ہیں  -  سب کچھ TypeScript یا Python کی چند سطروں سے۔
3~
4معیاری Anthropic Client SDK کے برعکس جہاں آپ اپنا ٹول لوپ بناتے ہیں، Agent SDK ٹول ایگزیکیوشن، کانٹیکسٹ مینجمنٹ، ری ٹرائز، اور آرکیسٹریشن کو اندرونی طور پر سنبھالتا ہے۔ آپ بتائیں کہ آپ کیا چاہتے ہیں، ٹولز فراہم کریں، اور ایجنٹ باقی سمجھ لیتا ہے۔
5~
6## آرکیٹیکچر
7~
8SDK ایک سادہ لوپ کی پیروی کرتا ہے: **کانٹیکسٹ جمع کرو، ایکشن لو، تصدیق کرو، دہراؤ**۔
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_KEY` کے طور پر ایک 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** | شیل کمانڈز ایگزیکیوٹ کریں |
101| **Glob** | پیٹرن سے فائلیں ڈھونڈیں |
102| **Grep** | regex سے فائل مواد تلاش کریں |
103| **WebSearch** | ویب تلاش کریں |
104| **WebFetch** | ایک URL فیچ کریں اور اس کا مواد واپس کریں |
105| **AskUserQuestion** | صارف سے ان پٹ مانگیں |
106~
107آپ `allowedTools` کے ذریعے کنٹرول کرتے ہیں کہ ایجنٹ کون سے ٹولز استعمال کر سکتا ہے۔ اگر کوئی ٹول فہرست میں نہیں ہے تو ایجنٹ اسے کال نہیں کر سکتا۔
108~
109## پرمیشن موڈز
110~
111چونکہ ایجنٹس حقیقی سسٹمز پر حقیقی کمانڈز ایگزیکیوٹ کرتے ہیں، اجازتیں اہم ہیں۔
112~
113| موڈ | رویہ | استعمال کا معاملہ |
114|------|----------|----------|
115| `default` | کسٹم `canUseTool` کال بیک ہر کال پر فیصلہ کرتا ہے | باریک کنٹرول |
116| `acceptEdits` | فائل آپریشنز آٹو اپروو، Bash کے لیے پرامپٹ | ڈویلپمنٹ ورک فلوز |
117| `dontAsk` | allowedTools میں نہیں تو انکار | محدود ایجنٹس |
118| `bypassPermissions` | سب کچھ خودکار طور پر اپروو | قابل اعتماد سینڈباکسڈ ماحول |
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~
135SDK کی اصل طاقت ایجنٹس کو آپ کے اپنے ٹولز سے بڑھانے میں ہے۔ کسٹم ٹولز ان پروسیس 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ڈیلیگیشن فعال کرنے کے لیے پیرنٹ کے `allowedTools` میں `"Agent"` شامل کریں۔ سب ایجنٹس اپنے ٹولز کے ساتھ چلتے ہیں اور واضح طور پر اجازت دیے بغیر پیرنٹ کے ٹولز تک رسائی نہیں رکھتے۔
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~
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 ریٹ لمیٹس، کانٹیکسٹ ونڈو اوور فلو۔ ہمیشہ پیغام کی قسم چیک کریں۔
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~
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~