Claude Agent SDK کے ساتھ AI ایجنٹس بنانا: ایک عملی گائیڈ

Claude Agent SDK آپ کو اسی ایجنٹ لوپ تک پروگرامیٹک رسائی دیتا ہے جو Claude Code کو طاقت دیتا ہے۔ آپ کے ایجنٹس فائلیں پڑھ سکتے ہیں، شیل کمانڈز چلا سکتے ہیں، ویب تلاش کر سکتے ہیں، کوڈ ایڈٹ کر سکتے ہیں، MCP سرورز کے ذریعے ایکسٹرنل APIs کال کر سکتے ہیں، اور سب ایجنٹس کو آرکیسٹریٹ کر سکتے ہیں - سب کچھ TypeScript یا Python کی چند سطروں سے۔

معیاری Anthropic Client SDK کے برعکس جہاں آپ اپنا ٹول لوپ بناتے ہیں، Agent SDK ٹول ایگزیکیوشن، کانٹیکسٹ مینجمنٹ، ری ٹرائز، اور آرکیسٹریشن کو اندرونی طور پر سنبھالتا ہے۔ آپ بتائیں کہ آپ کیا چاہتے ہیں، ٹولز فراہم کریں، اور ایجنٹ باقی سمجھ لیتا ہے۔

آرکیٹیکچر

SDK ایک سادہ لوپ کی پیروی کرتا ہے: کانٹیکسٹ جمع کرو، ایکشن لو، تصدیق کرو، دہراؤ۔

بنیادی انٹری پوائنٹ query() ہے، جو ایک async iterator واپس کرتا ہے جو ایجنٹ کے کام کرتے وقت پیغامات سٹریم کرتا ہے۔ ہر پیغام آپ کو بتاتا ہے کہ ایجنٹ کیا کر رہا ہے: ریزننگ، ٹول کال کرنا، نتیجہ حاصل کرنا، یا حتمی آؤٹ پٹ دینا۔

شروع کریں

انسٹالیشن

# TypeScript
npm install @anthropic-ai/claude-agent-sdk

# Python
pip install claude-agent-sdk

آپ کو اپنے ماحول میں ANTHROPIC_API_KEY کے طور پر ایک Anthropic API key سیٹ کرنی ہوگی۔

آپ کا پہلا ایجنٹ

import { query } from "@anthropic-ai/claude-agent-sdk";

const conversation = query({
  prompt: "Find all TODO comments in the codebase and create a summary",
  options: {
    allowedTools: ["Read", "Glob", "Grep"],
  },
});

for await (const message of conversation) {
  if (message.type === "assistant") {
    process.stdout.write(message.content);
  }
  if (message.type === "result" && message.subtype === "success") {
    console.log("\nDone:", message.result);
  }
}

بس اتنا ہی۔ ایجنٹ Glob استعمال کرکے فائلیں ڈھونڈے گا، Grep سے TODO پیٹرنز تلاش کرے گا، Read سے میچز دیکھے گا، اور ایک منظم خلاصہ واپس کرے گا۔ آپ کو آرکیسٹریشن لاجک لکھنے کی ضرورت نہیں - SDK اسے سنبھالتا ہے۔

Python مساوی

from claude_agent_sdk import query

async for message in query(
    prompt="Find all TODO comments in the codebase and create a summary",
    options={"allowed_tools": ["Read", "Glob", "Grep"]},
):
    if message.type == "assistant":
        print(message.content, end="")
    if message.type == "result" and message.subtype == "success":
        print(f"\nDone: {message.result}")

بلٹ ان ٹولز

SDK میں وہی ٹولز شامل ہیں جو Claude Code میں دستیاب ہیں:

آپ allowedTools کے ذریعے کنٹرول کرتے ہیں کہ ایجنٹ کون سے ٹولز استعمال کر سکتا ہے۔ اگر کوئی ٹول فہرست میں نہیں ہے تو ایجنٹ اسے کال نہیں کر سکتا۔

پرمیشن موڈز

چونکہ ایجنٹس حقیقی سسٹمز پر حقیقی کمانڈز ایگزیکیوٹ کرتے ہیں، اجازتیں اہم ہیں۔

const conversation = query({
  prompt: "Refactor the auth module to use JWT",
  options: {
    allowedTools: ["Read", "Edit", "Glob", "Grep", "Bash"],
    permissionMode: "acceptEdits",
  },
});

پروڈکشن استعمال کے لیے، ہمیشہ ایجنٹس کو سینڈباکسڈ ماحول (کنٹینرز، VMs) میں چلائیں اور سب سے زیادہ محدود پرمیشن موڈ استعمال کریں جو ایجنٹ کو اپنا کام کرنے دے۔

MCP کے ساتھ کسٹم ٹولز بنانا

SDK کی اصل طاقت ایجنٹس کو آپ کے اپنے ٹولز سے بڑھانے میں ہے۔ کسٹم ٹولز ان پروسیس MCP سرورز کے طور پر بیان کیے جاتے ہیں - کوئی سب پروسیس مینجمنٹ نہیں، کوئی نیٹ ورک اوور ہیڈ نہیں۔

مثال: ویدر ٹول

import { tool, createSdkMcpServer, query } from "@anthropic-ai/claude-agent-sdk";
import { z } from "zod";

const getTemperature = tool(
  "get_temperature",
  "Get the current temperature at a location",
  {
    latitude: z.number().describe("Latitude"),
    longitude: z.number().describe("Longitude"),
  },
  async ({ latitude, longitude }) => {
    const res = await fetch(
      `https://api.open-meteo.com/v1/forecast?latitude=${latitude}&longitude=${longitude}&current=temperature_2m&temperature_unit=celsius`
    );
    const data = await res.json();
    return {
      content: [
        {
          type: "text",
          text: `Current temperature: ${data.current.temperature_2m}C`,
        },
      ],
    };
  }
);

const weatherServer = createSdkMcpServer({
  name: "weather",
  version: "1.0.0",
  tools: [getTemperature],
});

for await (const message of query({
  prompt: "What's the weather like in Rome?",
  options: {
    mcpServers: { weather: weatherServer },
    allowedTools: ["mcp__weather__get_temperature"],
  },
})) {
  if (message.type === "result" && message.subtype === "success") {
    console.log(message.result);
  }
}

کسٹم ٹولز mcp__{server_name}__{tool_name} نام کی روایت کی پیروی کرتے ہیں۔ آپ allowedTools میں وائلڈ کارڈز استعمال کر سکتے ہیں: "mcp__weather__*" ویدر سرور کے تمام ٹولز کی اجازت دیتا ہے۔

مثال: ڈیٹابیس کوئری ٹول

const queryDb = tool(
  "query_database",
  "Run a read-only SQL query against the application database",
  {
    sql: z.string().describe("SQL SELECT query to execute"),
  },
  async ({ sql }) => {
    // Validate: only allow SELECT queries
    if (!sql.trim().toUpperCase().startsWith("SELECT")) {
      return {
        content: [{ type: "text", text: "Error: Only SELECT queries are allowed." }],
      };
    }

    const result = await pool.query(sql);
    return {
      content: [
        {
          type: "text",
          text: JSON.stringify(result.rows, null, 2),
        },
      ],
    };
  }
);

ایکسٹرنل MCP سرورز سے کنیکٹ کرنا

ان پروسیس ٹولز کے علاوہ، آپ کسی بھی موجودہ MCP سرور سے کنیکٹ کر سکتے ہیں - وہی سرورز جو Claude Desktop، Cursor، اور دیگر MCP کلائنٹس کے ساتھ کام کرتے ہیں۔

for await (const message of query({
  prompt: "Check the latest issues in the frontend repo and summarize them",
  options: {
    mcpServers: {
      github: {
        command: "npx",
        args: ["-y", "@modelcontextprotocol/server-github"],
        env: { GITHUB_PERSONAL_ACCESS_TOKEN: process.env.GITHUB_TOKEN },
      },
    },
    allowedTools: ["mcp__github__*"],
  },
})) {
  // ...
}

آپ متعدد MCP سرورز کو ملا سکتے ہیں۔ ایجنٹ تمام کنیکٹڈ سرورز سے تمام ٹولز دیکھتا ہے اور ضرورت کے مطابق استعمال کرتا ہے۔

ملٹی ایجنٹ آرکیسٹریشن

پیچیدہ ورک فلوز کے لیے، آپ خصوصی سب ایجنٹس بیان کر سکتے ہیں جن کو پیرنٹ ایجنٹ کام سونپتا ہے۔ ہر سب ایجنٹ کا اپنا پرامپٹ، ٹولز، اور فوکس ایریا ہوتا ہے۔

for await (const message of query({
  prompt: "Review the PR, check for security issues, and update the changelog",
  options: {
    allowedTools: ["Read", "Edit", "Bash", "Glob", "Grep", "Agent"],
    agents: [
      {
        name: "security-reviewer",
        description: "Reviews code for security vulnerabilities",
        prompt: "You are a security expert. Analyze code for OWASP Top 10 vulnerabilities.",
        allowedTools: ["Read", "Glob", "Grep"],
      },
      {
        name: "changelog-writer",
        description: "Updates the CHANGELOG.md file based on recent changes",
        prompt: "You maintain the project changelog. Follow Keep a Changelog format.",
        allowedTools: ["Read", "Edit", "Bash"],
      },
    ],
  },
})) {
  // The parent agent will:
  // 1. Read the PR diff
  // 2. Delegate security review to security-reviewer
  // 3. Delegate changelog update to changelog-writer
  // 4. Synthesize results
}

ڈیلیگیشن فعال کرنے کے لیے پیرنٹ کے allowedTools میں "Agent" شامل کریں۔ سب ایجنٹس اپنے ٹولز کے ساتھ چلتے ہیں اور واضح طور پر اجازت دیے بغیر پیرنٹ کے ٹولز تک رسائی نہیں رکھتے۔

سیشنز اور تسلسل

ایجنٹس سیشنز استعمال کرکے متعدد کوئریز میں کانٹیکسٹ برقرار رکھ سکتے ہیں۔ پہلی انٹرایکشن سے session_id کیپچر کریں اور بعد کی کوئریز میں resume میں پاس کریں۔

let sessionId: string | undefined;

// First query
for await (const message of query({
  prompt: "Read the project structure and understand the architecture",
  options: { allowedTools: ["Read", "Glob", "Grep"] },
})) {
  if (message.type === "init") {
    sessionId = message.session_id;
  }
}

// Follow-up query (same session, full context preserved)
for await (const message of query({
  prompt: "Now refactor the auth module based on what you learned",
  resume: sessionId,
  options: { allowedTools: ["Read", "Edit", "Bash"] },
})) {
  // Agent remembers the full project context from the first query
}

Claude Managed Agents

اگر آپ ایجنٹ انفراسٹرکچر خود ہوسٹ نہیں کرنا چاہتے، تو Claude Managed Agents (اپریل 2026 میں لانچ) ایک مکمل طور پر مینیجڈ کلاؤڈ سروس فراہم کرتا ہے۔ Anthropic کنٹینرز چلاتا ہے، سکیلنگ سنبھالتا ہے، اور ایک سٹریمنگ API فراہم کرتا ہے۔

بنیادی فرق: Agent SDK کے ساتھ، آپ اپنے انفراسٹرکچر میں ایجنٹ لوپ چلاتے ہیں۔ Managed Agents کے ساتھ، Anthropic آپ کے لیے ایجنٹ ہوسٹ اور چلاتا ہے۔ آپ سیشن پر مبنی API کے ذریعے تعامل کرتے ہیں اور Server-Sent Events کے ذریعے ایونٹس حاصل کرتے ہیں۔

قیمتیں:

• Agent SDK: صرف معیاری Claude API ٹوکن ریٹس۔ ہوسٹنگ آپ سنبھالتے ہیں۔
• Managed Agents: ٹوکن ریٹس کے علاوہ $0.08 فی سیشن گھنٹہ (فی ملی سیکنڈ بل)۔

پروڈکشن بہترین طریقے

1. ہمیشہ سینڈباکس کریں

پروڈکشن مشین پر کبھی بھی غیر محدود اجازتوں کے ساتھ ایجنٹس نہ چلائیں۔ کنٹینرز (Docker, Fly.io, Modal) یا سینڈباکسڈ ماحول (E2B, Vercel Sandbox) استعمال کریں۔

2. ٹول تک رسائی محدود کریں

کم سے کم استحقاق کے اصول کی پیروی کریں۔ رپورٹس بنانے والے ایجنٹ کو Bash یا Write کی ضرورت نہیں۔

// Too permissive
allowedTools: ["Read", "Write", "Edit", "Bash", "Glob", "Grep"]

// Better: only what's needed
allowedTools: ["Read", "Glob", "Grep"]

3. گارڈریلز کے لیے Hooks استعمال کریں

Hooks آپ کو ایگزیکیوشن سے پہلے اور بعد میں ٹول کالز کو انٹرسیپٹ کرنے دیتے ہیں۔ ان کا استعمال لاگنگ، ویلیڈیشن، اور ریٹ لمیٹنگ کے لیے کریں۔

const conversation = query({
  prompt: "Analyze the codebase",
  options: {
    allowedTools: ["Read", "Glob", "Grep"],
    hooks: {
      PreToolUse: async (toolName, input) => {
        console.log(`Tool call: ${toolName}`, input);
        // Return false to block the call
        if (toolName === "Bash" && input.command.includes("rm")) {
          return false;
        }
        return true;
      },
    },
  },
});

4. غلطیوں کو احسن طریقے سے سنبھالیں

ایجنٹ لوپ غلطیاں پیدا کر سکتا ہے - ٹول ناکامی، API ریٹ لمیٹس، کانٹیکسٹ ونڈو اوور فلو۔ ہمیشہ پیغام کی قسم چیک کریں۔

for await (const message of conversation) {
  switch (message.type) {
    case "assistant":
      // Agent reasoning
      break;
    case "tool_use":
      // Agent is calling a tool
      break;
    case "result":
      if (message.subtype === "error") {
        console.error("Agent failed:", message.error);
      }
      break;
  }
}

5. ٹوکن استعمال کی نگرانی کریں

ایجنٹ لوپس کافی ٹوکنز خرچ کر سکتے ہیں، خاص طور پر بڑے کوڈبیسز کے ساتھ۔ SDK میں خودکار کانٹیکسٹ کمپیکشن شامل ہے، لیکن آپ کو پھر بھی استعمال کی نگرانی کرنی چاہیے۔

نتیجہ

Claude Agent SDK ایک LLM کو سوال جواب مشین سے جونیئر ڈویلپر جیسی کسی چیز میں بدل دیتا ہے۔ آپ کے ایجنٹس پڑھ سکتے ہیں، لکھ سکتے ہیں، ایگزیکیوٹ کر سکتے ہیں، تصدیق کر سکتے ہیں، اور دہرا سکتے ہیں - وہی ورک فلو جو ایک انسان اپناتا ہے۔

چھوٹے سے شروع کریں: چند بلٹ ان ٹولز کے ساتھ ایک ایجنٹ بنائیں۔ پھر اپنے مخصوص ڈومین کے لیے کسٹم MCP ٹولز شامل کریں۔ جب آپ کے ورک فلوز کو تخصص کی ضرورت ہو تو ملٹی ایجنٹ آرکیسٹریشن تک سکیل کریں۔

ایجنٹ لوپ وہی ہے جو Claude Code کو طاقت دیتا ہے۔ اگر یہ سافٹ ویئر بنا سکتا ہے، تو آپ کے ایجنٹس بھی بنا سکتے ہیں۔

شروعات کی چیکلسٹ:

• SDK انسٹال کریں (npm install @anthropic-ai/claude-agent-sdk)
• اپنے ماحول میں ANTHROPIC_API_KEY سیٹ کریں
• بلٹ ان ٹولز (Read, Glob, Grep) کے ساتھ ایک سادہ ایجنٹ بنائیں
• ان پروسیس MCP سرور کے ذریعے کسٹم ٹول شامل کریں
• ایک ایکسٹرنل MCP سرور (GitHub, PostgreSQL, وغیرہ) کنیکٹ کریں
• سب ایجنٹس کے ساتھ ملٹی ایجنٹ آرکیسٹریشن نافذ کریں
• پروڈکشن کے لیے سینڈباکسڈ ماحول سیٹ اپ کریں
• لاگنگ اور گارڈریلز کے لیے hooks شامل کریں