Claude Agent SDK के साथ AI एजेंट बनाना: एक व्यावहारिक गाइड

Claude Agent SDK आपको उसी एजेंट लूप तक प्रोग्रामेटिक एक्सेस देता है जो Claude Code को शक्ति प्रदान करता है। आपके एजेंट फाइलें पढ़ सकते हैं, शेल कमांड एक्सीक्यूट कर सकते हैं, वेब खोज सकते हैं, कोड एडिट कर सकते हैं, MCP सर्वर के माध्यम से एक्सटर्नल API कॉल कर सकते हैं, और सब-एजेंट्स को ऑर्केस्ट्रेट कर सकते हैं - सब कुछ 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 जोड़ें