Claude Agent SDK क्या है? AI एजेंट डेवलपमेंट की पूरी गाइड

"काश AI को निर्देश देने के बाद वो खुद सोचकर काम पूरा कर ले..." — इसी सपने को साकार करता है AI एजेंट। Anthropic द्वारा प्रदान किया गया Claude Agent SDK एक ऐसा फ्रेमवर्क है जिससे आप Claude को दिमाग के रूप में इस्तेमाल करते हुए Python या TypeScript में AI एजेंट बना सकते हैं। यही तकनीक Claude Code (Anthropic की आधिकारिक CLI) के अंदर भी काम करती है।

इस लेख में हम Claude Agent SDK की बुनियादी अवधारणाओं से लेकर इम्प्लीमेंटेशन और उपयोग के तरीकों तक सब कुछ व्यवस्थित रूप से समझाएंगे।

AI एजेंट क्या है?

AI एजेंट पारंपरिक "सवाल → जवाब" वाले AI से अलग होता है। इसकी खासियत है कि यह स्वायत्त रूप से कार्यों को विभाजित करता है, टूल्स का उपयोग करता है, परिणामों का मूल्यांकन करता है, और अगला कदम तय करता है।

उदाहरण के लिए, अगर आप कहें "auth.py में बग ठीक करो", तो एजेंट इस तरह काम करेगा:

1. फ़ाइल पढ़कर कोड को समझना
2. संबंधित फ़ाइलों को खोजकर पूरी तस्वीर समझना
3. बग का कारण पहचानना
4. कोड में सुधार करना
5. टेस्ट चलाकर सत्यापन करना
6. परिणाम की रिपोर्ट देना

बीच में इंसान के हस्तक्षेप के बिना, एजेंट इन सभी कार्यों को खुद तय करके आगे बढ़ाता है। यही एजेंट की शक्ति है।

Claude Agent SDK का परिचय

Claude Agent SDK, Anthropic द्वारा आधिकारिक रूप से प्रदान किया गया एजेंट डेवलपमेंट फ्रेमवर्क है। Claude Code को चलाने वाले उसी इंजन को आप प्रोग्रामेटिक रूप से उपयोग कर सकते हैं।

मुख्य विशेषताएं इस प्रकार हैं:

Claude के चैट, Cowork और कोड — तीन मोड्स में से Claude Code (कोड मोड) के पीछे यही Agent SDK तकनीक काम करती है।

एजेंट लूप कैसे काम करता है

Agent SDK का मूल एजेंट लूप है। यह एक ऐसी प्रणाली है जो "Claude सोचता है, टूल इस्तेमाल करता है, परिणाम जांचता है, और फिर सोचता है" — इस चक्र को स्वचालित रूप से चलाती है।

विस्तृत प्रक्रिया इस प्रकार है:

1. प्रॉम्प्ट प्राप्ति: उपयोगकर्ता के निर्देश Claude को भेजे जाते हैं
2. Claude का निर्णय: निर्देशों का विश्लेषण करके आवश्यक कार्रवाई तय करना
3. टूल एक्ज़ीक्यूशन: Bash, Edit, Read जैसे टूल्स को कॉल करके कार्य करना
4. परिणाम प्रोसेसिंग: टूल के एक्ज़ीक्यूशन रिज़ल्ट को Claude को फ़ीडबैक करना
5. लूप जारी या समाप्ति: अगर अभी और काम बाकी है तो स्टेप 2 पर वापस जाना। पूरा होने पर टेक्स्ट रिस्पॉन्स देना

महत्वपूर्ण बात यह है कि जब टूल कॉल बंद हो जाएं, तो काम पूरा हो गया। जब Claude तय कर लेता है कि अब किसी टूल की ज़रूरत नहीं है, तो अंतिम टेक्स्ट रिस्पॉन्स वापस आता है।

शुरुआत: इंस्टॉलेशन और बेसिक कोड

इंस्टॉलेशन

Python या TypeScript में उपलब्ध है।

# Python
pip install claude-agent-sdk

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

न्यूनतम एजेंट (Python)

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage

async def main():
    async for message in query(
        prompt="src/auth.py में बग ढूंढकर ठीक करो",
        options=ClaudeAgentOptions(
            allowed_tools=["Read", "Edit", "Bash", "Grep"],
            max_turns=30,
        ),
    ):
        if isinstance(message, ResultMessage):
            if message.subtype == "success":
                print(message.result)
            print(f"लागत: ${message.total_cost_usd:.4f}")

asyncio.run(main())

न्यूनतम एजेंट (TypeScript)

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

for await (const message of query({
  prompt: "src/auth.py में बग ढूंढकर ठीक करो",
  options: {
    allowedTools: ["Read", "Edit", "Bash", "Grep"],
    maxTurns: 30,
  }
})) {
  if (message.type === "result" && message.subtype === "success") {
    console.log(message.result);
  }
}

बस इतना ही कोड चाहिए — और Claude फ़ाइल पढ़ेगा, बग ढूंढेगा, ठीक करेगा, और परिणाम की रिपोर्ट देगा।

बिल्ट-इन टूल्स की सूची

Agent SDK में कई ऐसे टूल्स पहले से मौजूद हैं जिन्हें बिना कोड लिखे तुरंत उपयोग किया जा सकता है।

इन टूल्स को बस allowed_tools में अनुमति देकर उपयोग किया जा सकता है। आपको खुद टूल प्रोसेसिंग का कोड लिखने की ज़रूरत नहीं है।

कस्टम टूल कैसे बनाएं

अगर बिल्ट-इन टूल्स पर्याप्त नहीं हैं, तो आप अपने खुद के टूल्स बना सकते हैं। उदाहरण के लिए, मौसम API से जुड़ा एक टूल बनाते हैं।

Python संस्करण

from claude_agent_sdk import tool, create_sdk_mcp_server

@tool(
    "get_weather",
    "निर्दिष्ट शहर का वर्तमान मौसम प्राप्त करें",
    {"city": str}
)
async def get_weather(args: dict) -> dict:
    city = args["city"]
    # वास्तव में API को कॉल किया जाएगा
    weather_data = await fetch_weather_api(city)
    return {
        "content": [
            {"type": "text", "text": f"{city} का मौसम: {weather_data}"}
        ]
    }

weather_server = create_sdk_mcp_server(
    name="weather",
    version="1.0.0",
    tools=[get_weather]
)

TypeScript संस्करण

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

const getWeather = tool(
  "get_weather",
  "निर्दिष्ट शहर का वर्तमान मौसम प्राप्त करें",
  { city: z.string().describe("शहर का नाम") },
  async (args) => {
    const data = await fetchWeatherApi(args.city);
    return {
      content: [{ type: "text", text: `${args.city} का मौसम: ${data}` }]
    };
  }
);

कस्टम टूल्स को MCP सर्वर के रूप में बनाकर एजेंट से जोड़ा जाता है। एरर होने पर एक्सेप्शन थ्रो करने के बजाय isError: true रिटर्न करना ज़रूरी है। इससे एजेंट का लूप रुकता नहीं और Claude रिट्राई या दूसरा तरीका आज़मा सकता है।

सब-एजेंट से पैरेलल प्रोसेसिंग

बड़े कार्यों को सब-एजेंट में बांटकर पैरेलल में चलाना कुशल होता है। मुख्य एजेंट के कॉन्टेक्स्ट (मेमोरी) को प्रभावित किए बिना, विशेष कार्य दूसरे एजेंट को सौंपे जा सकते हैं।

सब-एजेंट कब उपयोगी होते हैं

• बड़ी मात्रा में टेस्ट चलाना: टेस्ट रिज़ल्ट के लॉग बहुत बड़े होने पर भी मुख्य कॉन्टेक्स्ट पर असर नहीं पड़ता
• पैरेलल रिसर्च: कई मॉड्यूल्स की एक साथ जांच करके केवल परिणाम प्राप्त करना
• विशेष कार्यों का पृथक्करण: "कोड रिव्यू" और "टेस्ट एक्ज़ीक्यूशन" को अलग-अलग एजेंट्स को सौंपना

Claude Code में कस्टम सब-एजेंट

Claude Code (CLI) में .claude/agents/ में Markdown फ़ाइल रखने मात्र से कस्टम सब-एजेंट को परिभाषित किया जा सकता है।

# .claude/agents/reviewer.md
---
name: code-reviewer
description: कोड रिव्यू विशेषज्ञ एजेंट
tools: Read, Glob, Grep
model: sonnet
---

आप एक सीनियर कोड रिव्यूअर हैं।
कोड गुणवत्ता, सुरक्षा और बेस्ट प्रैक्टिसेज़ के
दृष्टिकोण से रिव्यू करें।

टूल एक्सेस को सीमित करके (ऊपर के उदाहरण में केवल Read संबंधित) यह सुनिश्चित किया जा सकता है कि रिव्यूअर गलती से कोड में बदलाव न कर दे।

Agent SDK vs Client SDK vs Claude Code

Claude के तीन डेवलपर-ओरिएंटेड इंटरफ़ेस हैं। हर एक की अपनी विशेषता है, इसलिए उद्देश्य के अनुसार चुनें।

कैसे चुनें:

• रोज़मर्रा का डेवलपमेंट कार्य → Claude Code CLI
• ऑटोमेशन सिस्टम बनाना हो → Agent SDK
• अपना AI ऐप बनाना हो → Client SDK

व्यावहारिक उपयोग के उदाहरण

कोड डेवलपमेंट का ऑटोमेशन

सबसे आम उपयोग। "यह फ़ीचर इम्प्लीमेंट करो" कहने पर एजेंट फ़ाइल स्ट्रक्चर की जांच करता है, कोड लिखता है, और टेस्ट भी चलाता है।

# बग फिक्स का ऑटोमेशन
async for msg in query(
    prompt="ऑथेंटिकेशन मॉड्यूल का टेस्ट फेल हो रहा है। कारण जांचकर ठीक करो",
    options=ClaudeAgentOptions(
        allowed_tools=["Read", "Edit", "Bash", "Grep"],
        max_turns=20,
        max_budget_usd=2.00,  # लागत सीमा $2
    ),
):
    pass

CI/CD पाइपलाइन में एकीकरण

GitHub Actions जैसे टूल्स के साथ जोड़कर, हर PR बनने पर ऑटोमैटिक कोड रिव्यू करना या टेस्ट फेल होने पर ऑटोमैटिक फिक्स आज़माने जैसे वर्कफ़्लो बनाए जा सकते हैं।

डेटा विश्लेषण और रिसर्च

"पिछले एक महीने के लॉग से एरर पैटर्न का विश्लेषण करो" जैसे कई चरणों वाले रिसर्च कार्य भी एजेंट को सौंपे जा सकते हैं। WebSearch टूल के साथ मिलाकर नवीनतम जानकारी भी शामिल की जा सकती है।

बेस्ट प्रैक्टिसेज़

1. लागत नियंत्रण न भूलें

एजेंट लूप में चलता है, इसलिए अपेक्षा से अधिक टोकन खर्च हो सकते हैं। हमेशा max_budget_usd या max_turns सेट करें।

options=ClaudeAgentOptions(
    max_budget_usd=5.00,   # $5 पर रुक जाएगा
    max_turns=30,           # 30 टर्न पर रुक जाएगा
    effort="medium",        # रीज़निंग की गहराई (low/medium/high/max)
)

2. टूल्स न्यूनतम रखें

ग़ैर-ज़रूरी टूल्स को अनुमति देने से कॉन्टेक्स्ट विंडो बेवजह खर्च होती है। केवल कार्य के लिए आवश्यक टूल्स ही allowed_tools में निर्दिष्ट करें।

3. एरर हैंडलिंग isError से करें

कस्टम टूल में एरर आने पर एक्सेप्शन थ्रो करने से एजेंट का पूरा लूप रुक जाता है। इसके बजाय isError: true रिटर्न करें ताकि Claude रिकवरी का प्रयास कर सके।

4. भारी प्रोसेसिंग सब-एजेंट को सौंपें

टेस्ट एक्ज़ीक्यूशन या लॉग एनालिसिस जैसी बड़ी आउटपुट वाली प्रोसेसिंग सब-एजेंट को दें। इससे मुख्य एजेंट के कॉन्टेक्स्ट पर दबाव नहीं पड़ता।

5. प्रॉम्प्ट में स्पष्ट निर्देश दें

"कोड सुधारो" के बजाय "auth.py के लॉगिन फ़ंक्शन में रेट लिमिटिंग जोड़ो और टेस्ट भी लिखो" जैसे विशिष्ट निर्देश देने से एजेंट कुशलता से काम करता है।

सारांश

Claude Agent SDK, AI एजेंट डेवलपमेंट की बाधाओं को काफ़ी कम करने वाला फ्रेमवर्क है। Claude Code के समान इंजन का उपयोग करते हुए, Python या TypeScript में स्वायत्त रूप से कार्य करने वाले एजेंट बनाए जा सकते हैं।

पहले Claude Code का उपयोग करके इंटरैक्टिव तरीके से एजेंट की कार्यप्रणाली को अनुभव करें, और जब ऑटोमेशन की आवश्यकता हो तब Agent SDK पर जाएं — यह चरणबद्ध दृष्टिकोण सबसे अच्छा है।

Claude की बुनियादी उपयोग विधि के बारे में, Claude के "चैट, Cowork और कोड" — तीन टैब की विस्तृत तुलना भी ज़रूर पढ़ें।