विषय सूची
- 1. AI एजेंट क्या है?
- 2. Claude Agent SDK का परिचय
- 3. एजेंट लूप कैसे काम करता है
- 4. शुरुआत: इंस्टॉलेशन और बेसिक कोड
- 5. बिल्ट-इन टूल्स की सूची
- 6. कस्टम टूल कैसे बनाएं
- 7. सबएजेंट से पैरेलल प्रोसेसिंग
- 8. परमिशन, हुक्स और सेशन
- 9. Agent SDK vs Client SDK vs Claude Code
- 10. व्यावहारिक उपयोग के उदाहरण
- 11. बेस्ट प्रैक्टिसेज़
- अक्सर पूछे जाने वाले सवाल
"काश AI को निर्देश देने के बाद वो खुद सोचकर काम पूरा कर ले..." — इसी सपने को साकार करता है AI एजेंट। Anthropic द्वारा प्रदान किया गया Claude Agent SDK एक ऐसी लाइब्रेरी है जिससे आप Claude को दिमाग के रूप में इस्तेमाल करते हुए Python या TypeScript में AI एजेंट बना सकते हैं। Claude Code (Anthropic का आधिकारिक कोडिंग एजेंट) जिन टूल्स, एजेंट लूप और कॉन्टेक्स्ट मैनेजमेंट पर चलता है, वही सब आप अपने प्रोग्राम से सीधे इस्तेमाल कर सकते हैं।
इस लेख में हम Claude Agent SDK की बुनियादी अवधारणाओं से लेकर इम्प्लीमेंटेशन और उपयोग के तरीकों तक सब कुछ व्यवस्थित रूप से समझाएंगे।
AI एजेंट क्या है?
AI एजेंट पारंपरिक "सवाल → जवाब" वाले AI से अलग होता है। इसकी खासियत है कि यह स्वायत्त रूप से कार्यों को विभाजित करता है, टूल्स का उपयोग करता है, परिणामों का मूल्यांकन करता है, और अगला कदम तय करता है।
उदाहरण के लिए, अगर आप कहें "auth.py में बग ठीक करो", तो एजेंट इस तरह काम करेगा:
- फ़ाइल पढ़कर कोड को समझना
- संबंधित फ़ाइलों को खोजकर पूरी तस्वीर समझना
- बग का कारण पहचानना
- कोड में सुधार करना
- टेस्ट चलाकर सत्यापन करना
- परिणाम की रिपोर्ट देना
बीच में इंसान के हस्तक्षेप के बिना, एजेंट इन सभी कार्यों को खुद तय करके आगे बढ़ाता है। यही एजेंट की शक्ति है।
Claude Agent SDK का परिचय
Claude Agent SDK, एजेंट बनाने के लिए Anthropic की आधिकारिक लाइब्रेरी है। आधिकारिक डॉक्यूमेंटेशन इसे ऐसी लाइब्रेरी बताता है जो Claude Code की बाइनरी चलाती है। यानी दिशा यह है: SDK, Claude Code को चलाता है, उल्टा नहीं। Python और TypeScript के SDK में यह बाइनरी पहले से शामिल होती है, इसलिए ज़्यादातर माहौल में Claude Code को अलग से इंस्टॉल करने की ज़रूरत नहीं पड़ती।
मुख्य विशेषताएं इस प्रकार हैं:
| विशेषता | विवरण |
|---|---|
| स्वचालित एजेंट लूप प्रबंधन | टूल कॉल → परिणाम प्रोसेसिंग → अगले निर्णय का लूप SDK अपने आप चलाता है |
| बिल्ट-इन टूल्स | फ़ाइल ऑपरेशन, कमांड एक्ज़ीक्यूशन, वेब सर्च जैसे तुरंत उपयोग करने योग्य टूल्स शामिल |
| कस्टम टूल्स | अपने खुद के टूल्स (API कॉल, DB ऑपरेशन आदि) आसानी से जोड़ सकते हैं |
| MCP इंटीग्रेशन | बाहरी टूल सर्वर (MCP) से कनेक्ट करके क्षमताएं बढ़ा सकते हैं |
| लागत नियंत्रण | बजट सीमा और टर्न सीमा सेट कर सकते हैं |
| सबएजेंट | कार्यों को विभाजित करके पैरेलल में चला सकते हैं |
| समर्थित भाषाएं | Python / TypeScript |
Claude के कोड (Claude Code) में चलने वाले एजेंट को उस इंटरफ़ेस से बाहर, अपने ऐप्स और स्क्रिप्ट्स में जोड़ने का तरीका यही Agent SDK है।
एजेंट लूप कैसे काम करता है
Agent SDK का मूल एजेंट लूप है। यह एक ऐसी प्रणाली है जो "Claude सोचता है, टूल इस्तेमाल करता है, परिणाम जांचता है, और फिर सोचता है" — इस चक्र को स्वचालित रूप से चलाती है।
एजेंट लूप कैसे काम करता है
विस्तृत प्रक्रिया इस प्रकार है:
- प्रॉम्प्ट प्राप्ति: उपयोगकर्ता के निर्देश Claude को भेजे जाते हैं
- Claude का निर्णय: निर्देशों का विश्लेषण करके आवश्यक कार्रवाई तय करना
- टूल एक्ज़ीक्यूशन: Bash, Edit, Read जैसे टूल्स को कॉल करके कार्य करना
- परिणाम प्रोसेसिंग: टूल के एक्ज़ीक्यूशन रिज़ल्ट को Claude को फ़ीडबैक करना
- लूप जारी या समाप्ति: अगर अभी और काम बाकी है तो स्टेप 2 पर वापस जाना। पूरा होने पर टेक्स्ट रिस्पॉन्स देना
महत्वपूर्ण बात यह है कि जब टूल कॉल बंद हो जाएं, तो काम पूरा हो गया। जब Claude तय कर लेता है कि अब किसी टूल की ज़रूरत नहीं है, तो अंतिम टेक्स्ट रिस्पॉन्स वापस आता है।
शुरुआत: इंस्टॉलेशन और बेसिक कोड
इंस्टॉलेशन
Python या TypeScript में उपलब्ध है।
# Python
pip install claude-agent-sdk
# TypeScript
npm install @anthropic-ai/claude-agent-sdk
इसके लिए Node.js 18 या उससे नया, या Python 3.10 या उससे नया चाहिए (आधिकारिक क्विकस्टार्ट)।
ऑथेंटिकेशन: API की इस्तेमाल करें (claude.ai लॉगिन नहीं)
SDK एनवायरनमेंट वेरिएबल ANTHROPIC_API_KEY में सेट की गई API की से चलता है। Amazon Bedrock, Google Cloud (Google द्वारा संचालित संस्करण) या Microsoft Foundry के ज़रिए इस्तेमाल करना हो, तो क्रमशः CLAUDE_CODE_USE_BEDROCK=1, CLAUDE_CODE_USE_VERTEX=1 या CLAUDE_CODE_USE_FOUNDRY=1 सेट करें और उस क्लाउड के क्रेडेंशियल तैयार रखें। SDK .env फ़ाइल अपने-आप नहीं पढ़ता, इसलिए वेरिएबल उसी शेल में सेट करें जहाँ एजेंट चलता है। Google Cloud पर Claude इस्तेमाल करने के चरण और कीमतें Vertex AI पर Claude कैसे इस्तेमाल करें में दी गई हैं।
claude.ai लॉगिन (Pro, Max जैसे सब्सक्रिप्शन) को लेकर सावधान रहें। आधिकारिक डॉक्यूमेंटेशन के अनुसार, पहले से मंज़ूरी न मिली हो तो थर्ड-पार्टी डेवलपर अपने प्रोडक्ट में (Agent SDK से बने एजेंट भी शामिल) claude.ai लॉगिन या उसकी उपयोग सीमाएँ नहीं दे सकते। SDK से बनने वाले ऐप्स को API की से ऑथेंटिकेट करना होता है।
न्यूनतम एजेंट (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)
if message.total_cost_usd is not None:
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 फ़ाइल पढ़ेगा, बग ढूंढेगा, ठीक करेगा, और परिणाम की रिपोर्ट देगा। लेकिन ध्यान रखें: allowed_tools "Claude कौन-से टूल इस्तेमाल कर सकता है" की सूची नहीं, बल्कि बिना पूछे अपने-आप मंज़ूर होने वाले टूल्स की सूची है। इस उदाहरण में Bash शामिल है, इसलिए Claude जो भी शेल कमांड चुनेगा वह बिना पुष्टि के चलेगी (सिवाय कुछ गिने-चुने कामों के, जैसे कुछ तरह के डिलीट, जिन्हें कोई भी सेटिंग अपने-आप मंज़ूर नहीं करती)। चूँकि इस उदाहरण में permission_mode तय नहीं है, मोड सेटिंग्स फ़ाइलों के permissions.defaultMode से, और वह न हो तो बिल्ट-इन डिफ़ॉल्ट से आता है; v2.1.285 से यह डिफ़ॉल्ट उन सेशनों में auto था जो feature flags नहीं लाते, जैसे थर्ड-पार्टी प्रोवाइडर (Bedrock, Google Cloud, Microsoft Foundry) के ज़रिए या टेलीमेट्री बंद होने पर (आधिकारिक डॉक्यूमेंटेशन)। हालाँकि v2.1.302 (16 अक्टूबर 2026) में यह बदल गया: जो Agent SDK और claude -p सेशन परमिशन मोड नहीं देते, वे थर्ड-पार्टी प्रोवाइडर के ज़रिए भी अब default से शुरू होते हैं। auto के साथ चलाने के लिए उसे साफ़ तौर पर देना होगा (CLI में --permission-mode auto; चेंजलॉग, 18 अक्टूबर 2026 को जाँचा गया)। auto मोड Bash जैसे व्यापक अलाउ नियम हटा देता है, इसलिए अगर आप ऊपर वाले व्यवहार पर निर्भर हैं तो permission_mode="default" (TS: permissionMode: "default") साफ़ तौर पर दें (आधिकारिक डॉक्यूमेंटेशन)। इसे ऐसी वर्किंग डायरेक्टरी में आज़माएँ जिसके बिगड़ने से फ़र्क न पड़े। टूल्स को असल में सीमित कैसे करें, यह अगले सेक्शन में है।
बिल्ट-इन टूल्स की सूची
Agent SDK में कई ऐसे टूल्स पहले से मौजूद हैं जिन्हें बिना कोड लिखे तुरंत उपयोग किया जा सकता है।
| टूल का नाम | कार्य | उपयोग का उदाहरण |
|---|---|---|
| Bash | शेल कमांड एक्ज़ीक्यूशन | टेस्ट चलाना, बिल्ड, git ऑपरेशन |
| Read | फ़ाइल पढ़ना | सोर्स कोड या कॉन्फ़िग फ़ाइलों की जांच |
| Edit | फ़ाइल का आंशिक संपादन | बग फिक्स, रिफैक्टरिंग |
| Write | नई फ़ाइल बनाना | नए मॉड्यूल का निर्माण |
| Glob | फ़ाइल खोज (पैटर्न) | **/*.ts से TypeScript फ़ाइलों की सूची |
| Grep | फ़ाइल कंटेंट सर्च | फ़ंक्शन डेफ़िनिशन या एरर मैसेज खोजना |
| WebSearch | वेब सर्च | नवीनतम डॉक्यूमेंट या API स्पेसिफ़िकेशन की जांच |
| WebFetch | वेब पेज प्राप्त करना | URL से जानकारी प्राप्त करना |
| Agent | सबएजेंट शुरू करना | कार्यों को विभाजित करके पैरेलल प्रोसेसिंग |
बिल्ट-इन टूल्स के लिए आपको खुद टूल प्रोसेसिंग का कोड नहीं लिखना पड़ता। ज़रूरी बात यह है कि "Claude को कौन-से टूल दिखें" और "कौन-से टूल बिना पूछे चलें" — ये दो अलग सेटिंग्स हैं। आधिकारिक डॉक्यूमेंटेशन की व्याख्या नीचे तालिका में है।
| ऑप्शन | कहाँ असर करता है | प्रभाव |
|---|---|---|
tools | Claude को दिखने वाले टूल | सिर्फ़ सूचीबद्ध बिल्ट-इन टूल ही Claude के कॉन्टेक्स्ट में आते हैं। [] देने पर सारे बिल्ट-इन टूल हट जाते हैं और सिर्फ़ आपके MCP टूल बचते हैं। |
allowed_tools(TS: allowedTools) | मंज़ूरी | सूचीबद्ध टूल बिना पूछे अपने-आप मंज़ूर होते हैं। यह टूल्स को सीमित नहीं करता। जो टूल सूची में नहीं हैं वे भी उपलब्ध रहते हैं, और जिन कॉल्स को मंज़ूरी चाहिए वे परमिशन मोड और can_use_tool (TS: canUseTool) के पास जाती हैं। |
disallowed_tools(TS: disallowedTools) | दोनों | "Bash" जैसा सिर्फ़ नाम लिखने पर टूल पूरी तरह हट जाता है। "Bash(rm *)" जैसा दायरे वाला नियम टूल को रखता है, पर मेल खाने वाली कॉल्स को हर परमिशन मोड में रोक देता है। |
उदाहरण के लिए, allowed_tools=["Read"] के साथ permission_mode="bypassPermissions" देने पर सूची में न होने वाले Bash, Write और Edit समेत सब कुछ मंज़ूर हो जाता है (आधिकारिक डॉक्यूमेंटेशन इस जोड़ी के बारे में साफ़ चेतावनी देता है)। जिस टूल को इस्तेमाल नहीं होने देना है, उसे tools या disallowed_tools से हटाएँ। अगर सिर्फ़ तय टूल्स से काम चलाना है, तो allowed_tools को permission_mode="dontAsk" के साथ इस्तेमाल करें, जो पुष्टि माँगने वाली हर कॉल को अस्वीकार कर देता है।
एक और बात: macOS, Linux और WSL पर Glob और Grep डिफ़ॉल्ट टूल्स में शामिल नहीं होते (Windows पर होते हैं)। वहाँ Claude Bash के ज़रिए find और grep से खोज करता है। tools या 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 सर्वर के रूप में बनाकर mcp_servers (TS: mcpServers) के ज़रिए एजेंट को दिया जाता है। हर टूल का पूरा नाम mcp__सर्वर-नाम__टूल-नाम बनता है, इसलिए उसे बिना पूछे चलाना हो तो यही नाम allowed_tools में डालें।
options=ClaudeAgentOptions(
mcp_servers={"weather": weather_server},
allowed_tools=["mcp__weather__get_weather"],
)
टूल के अंदर एक्सेप्शन आने पर भी एजेंट का लूप नहीं रुकता। SDK का MCP सर्वर एक्सेप्शन को पकड़कर उसका मैसेज जैसा का तैसा एरर रिज़ल्ट के रूप में Claude को दे देता है। अगर आप खुद एरर पकड़कर "is_error": True (TypeScript में isError: true) लौटाते हैं, तो Claude जो मैसेज पढ़ेगा उसे आप खुद लिख सकते हैं — कौन-सी रिक्वेस्ट फ़ेल हुई और उसकी जगह क्या आज़माया जाए। दोनों ही स्थितियों में Claude दोबारा कोशिश कर सकता है, दूसरा टूल आज़मा सकता है या विफलता समझा सकता है (आधिकारिक डॉक्यूमेंटेशन: कस्टम टूल्स)।
सबएजेंट से पैरेलल प्रोसेसिंग
बड़े कार्यों को सबएजेंट में बांटकर पैरेलल में चलाना कुशल होता है। मुख्य एजेंट के कॉन्टेक्स्ट (मेमोरी) को प्रभावित किए बिना, विशेष कार्य दूसरे एजेंट को सौंपे जा सकते हैं।
सबएजेंट कब उपयोगी होते हैं
- बड़ी मात्रा में टेस्ट चलाना: टेस्ट रिज़ल्ट के लॉग बहुत बड़े होने पर भी मुख्य कॉन्टेक्स्ट पर असर नहीं पड़ता
- पैरेलल रिसर्च: कई मॉड्यूल्स की एक साथ जांच करके केवल परिणाम प्राप्त करना
- विशेष कार्यों का पृथक्करण: "कोड रिव्यू" और "टेस्ट एक्ज़ीक्यूशन" को अलग-अलग एजेंट्स को सौंपना
Claude Code में कस्टम सबएजेंट
Claude Code (CLI) में .claude/agents/ में Markdown फ़ाइल रखने मात्र से कस्टम सबएजेंट को परिभाषित किया जा सकता है।
# .claude/agents/reviewer.md
---
name: code-reviewer
description: कोड रिव्यू विशेषज्ञ एजेंट
tools: Read, Glob, Grep
model: sonnet
---
आप एक सीनियर कोड रिव्यूअर हैं।
कोड गुणवत्ता, सुरक्षा और बेस्ट प्रैक्टिसेज़ के
दृष्टिकोण से रिव्यू करें।
टूल एक्सेस को सीमित करके (ऊपर के उदाहरण में केवल Read संबंधित) यह सुनिश्चित किया जा सकता है कि रिव्यूअर गलती से कोड में बदलाव न कर दे।
परमिशन, हुक्स और सेशन
एजेंट को प्रोडक्शन में चलाते समय सबसे ज़्यादा फ़र्क यही तीन चीज़ें डालती हैं। आधिकारिक डॉक्यूमेंटेशन इन तीनों को SDK में उपलब्ध Claude Code की क्षमताओं में गिनता है।
परमिशन: हर कॉल एक तय क्रम में जाँची जाती है
जब Claude कोई टूल माँगता है, तो SDK हुक्स → डिनाई नियम → आस्क नियम → परमिशन मोड → अलाउ नियम → can_use_tool कॉलबैक के क्रम में जाँच करता है। डिनाई नियम (जैसे disallowed_tools से) से मेल खाने वाली कॉल bypassPermissions मोड में भी रुक जाती है। एक अपवाद: mod (ऐसा plugin जिसके hooks फ़ंक्शन होते हैं) उसे लोड करने वाले Agent SDK सेशनों में भी चलता है (आधिकारिक डॉक्यूमेंटेशन), और tool.check का जवाब देने वाला mod डिनाई नियम द्वारा ठुकराई गई कॉल भी मंज़ूर कर सकता है, सिवाय मैनेज्ड सेटिंग्स वाली मशीनों या Team या Enterprise प्लान से साइन-इन के (आधिकारिक डॉक्यूमेंटेशन)। केवल भरोसेमंद लेखकों के mods ही इंस्टॉल करें; विस्तार से जानने के लिए Claude Code Mods क्या हैं देखें। परमिशन मोड permission_mode से चुना जाता है (सितंबर 2026 के आधिकारिक डॉक्यूमेंटेशन के अनुसार)।
| मोड | व्यवहार |
|---|---|
default | मोड के आधार पर कोई अपने-आप मंज़ूरी नहीं। जिन कॉल्स को मंज़ूरी चाहिए और जो किसी अलाउ नियम से मेल नहीं खातीं, वे can_use_tool के पास जाती हैं। |
acceptEdits | फ़ाइल एडिट और mkdir, rm, mv जैसे फ़ाइल सिस्टम ऑपरेशन अपने-आप मंज़ूर करता है। |
plan | सिर्फ़ जाँच-पड़ताल और योजना। सोर्स फ़ाइलों के एडिट कभी अपने-आप मंज़ूर नहीं होते। |
dontAsk | पुष्टि माँगने वाली हर कॉल को अस्वीकार करता है। can_use_tool कभी नहीं बुलाया जाता। |
bypassPermissions | बिना पूछे टूल चलाता है (कुछ ऐसे कामों को छोड़कर जिन्हें कोई मोड अपने-आप मंज़ूर नहीं करता)। सावधानी से इस्तेमाल करें। |
auto | मॉडल-आधारित क्लासिफ़ायर परमिशन अनुरोधों को मंज़ूर या अस्वीकार करता है। |
हुक्स: अहम मौक़ों पर अपना कोड चलाएँ
हुक्स ऐसे कॉलबैक हैं जो इवेंट्स पर चलते हैं — जैसे टूल चलने से पहले (PreToolUse), बाद में (PostToolUse) या निष्पादन रुकने पर (Stop)। ये परमिशन जाँच से पहले चलते हैं, इसलिए जिस काम को हर मोड में रोकना है, उसे यहीं रोका जा सकता है। नीचे का उदाहरण (आधिकारिक डॉक्यूमेंटेशन के उदाहरण का छोटा रूप) .env फ़ाइलों में लिखने से रोकता है।
from claude_agent_sdk import ClaudeAgentOptions, HookMatcher
async def protect_env_files(input_data, tool_use_id, context):
file_path = input_data["tool_input"].get("file_path", "")
if file_path.split("/")[-1] == ".env":
return {
"hookSpecificOutput": {
"hookEventName": input_data["hook_event_name"],
"permissionDecision": "deny",
"permissionDecisionReason": "Cannot modify .env files",
}
}
return {}
options = ClaudeAgentOptions(
hooks={"PreToolUse": [HookMatcher(matcher="Write|Edit", hooks=[protect_env_files])]}
)
सेशन: जहाँ छोड़ा था वहीं से शुरू करें, या शाखा बनाएँ
SDK बातचीत का इतिहास (प्रॉम्प्ट, टूल कॉल, रिज़ल्ट और जवाब) सेशन के रूप में अपने-आप डिस्क पर सहेजता है। रिज़ल्ट मैसेज का session_id सँभालकर रखें और अगले query() में resume को दें — एजेंट पढ़ी हुई फ़ाइलों और लिए गए फ़ैसलों को ध्यान में रखते हुए आगे बढ़ेगा। सबसे हाल का सेशन जारी रखना हो तो continue_conversation=True (TS: continue: true), और मूल सेशन को बचाए रखते हुए दूसरा तरीका आज़माना हो तो fork_session=True (TS: forkSession: true) इस्तेमाल करें। सेशन में सिर्फ़ बातचीत सहेजी जाती है; फ़ाइलों में हुए बदलाव वापस नहीं होते (आधिकारिक डॉक्यूमेंटेशन: सेशन)।
इसके अलावा, प्रोजेक्ट के .claude/ और ~/.claude/ में मौजूद स्किल्स, कमांड्स और मेमोरी Claude Code की तरह ही अपने-आप लोड होती हैं। स्किल्स, एजेंट्स, हुक्स और MCP सर्वर को एक साथ पैक करने वाले प्लगइन भी लोकल पाथ से लोड किए जा सकते हैं।
Agent SDK vs Client SDK vs Claude Code
आधिकारिक तुलना Claude के साथ डेवलपमेंट के चार तरीके बताती है: Agent SDK, Claude Code CLI, Client SDK और Managed Agents। यहाँ पहले उन तीन की तुलना है जिन्हें आप अपनी मशीन या सर्वर पर चलाते हैं।
Agent SDK vs Client SDK vs Claude Code CLI
| पहलू | Agent SDK | Client SDK (API) | Claude Code CLI |
|---|---|---|---|
| लूप प्रबंधन | स्वचालित | खुद बनाना पड़ता है (या बीटा tool runner) | स्वचालित |
| टूल्स | बिल्ट-इन + कस्टम | खुद परिभाषित करके चलाने होते हैं | बिल्ट-इन |
| उपयोग | ऑटोमेशन / प्रोडक्शन | पूर्ण कस्टम कंट्रोल | इंटरैक्टिव डेवलपमेंट |
| कठिनाई स्तर | मध्यम | उन्नत | शुरुआती |
| कोडिंग | आवश्यक | आवश्यक | आवश्यक नहीं |
कैसे चुनें:
- रोज़मर्रा का डेवलपमेंट कार्य → Claude Code CLI
- ऑटोमेशन सिस्टम बनाना हो → Agent SDK
- अपना AI ऐप बनाना हो → Client SDK
- लूप और सैंडबॉक्स का संचालन भी सौंपना है → Managed Agents (Anthropic द्वारा होस्ट किया गया एजेंट, जिसके सेशन Anthropic के प्रबंधित क्लाउड सैंडबॉक्स या आपके अपने सैंडबॉक्स में चलते हैं; इसे आपकी भाषा के SDK,
antCLI या REST API से इस्तेमाल किया जाता है)
व्यावहारिक उपयोग के उदाहरण
Claude एजेंट के उपयोग
कोड डेवलपमेंट का ऑटोमेशन
सबसे आम उपयोग। "यह फ़ीचर इम्प्लीमेंट करो" कहने पर एजेंट फ़ाइल स्ट्रक्चर की जांच करता है, कोड लिखता है, और टेस्ट भी चलाता है।
# बग फिक्स का ऑटोमेशन
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/xhigh/max)
)
जो मॉडल xhigh सपोर्ट नहीं करते, उन पर यह high की तरह काम करता है। कोई सीमा रन को रोक दे, तो अंतिम रिज़ल्ट मैसेज का subtype max_budget_usd के लिए "error_max_budget_usd" और max_turns के लिए "error_max_turns" होता है, और result खाली (None) रहता है। एजेंट क्यों रुका, यह subtype से पता चलता है।
ध्यान रखें कि यह रकम SDK के साथ आई मूल्य तालिका से निकाला गया अनुमान है, असली बिल नहीं। बजट सिर्फ़ उसी कॉल का खर्च गिनता है; resume से दोबारा शुरू किए गए सेशन का पिछला खर्च इसमें नहीं जुड़ता। सही आँकड़ों के लिए Claude Console का Usage पेज या Usage and Cost API देखें (आधिकारिक डॉक्यूमेंटेशन: लागत ट्रैकिंग)।
2. टूल्स न्यूनतम रखें
ग़ैर-ज़रूरी टूल्स Claude को दिखें ही नहीं, इसके लिए tools में सिर्फ़ ज़रूरी टूल्स लिखें या disallowed_tools में सिर्फ़ नाम लिखकर उन्हें हटाएँ। allowed_tools सिर्फ़ पुष्टि छोड़ने की सेटिंग है; यह टूल्स को सीमित नहीं करता। बिना पूछे चलने वाले टूल्स की सूची भी कार्य की न्यूनतम ज़रूरत तक ही रखें।
3. टूल की एरर is_error से बताएँ
कस्टम टूल में एक्सेप्शन आने पर भी एजेंट का लूप नहीं रुकता; SDK एक्सेप्शन का मैसेज एरर रिज़ल्ट के रूप में Claude को दे देता है। लेकिन सिर्फ़ कच्चे एक्सेप्शन मैसेज से Claude के लिए अगला कदम तय करना हमेशा आसान नहीं होता। एक्सेप्शन खुद पकड़ें और "is_error": True (TypeScript में isError: true) के साथ यह लिखकर लौटाएँ कि क्या फ़ेल हुआ और उसकी जगह क्या आज़माया जा सकता है — इससे Claude आसानी से संभल पाता है।
4. भारी प्रोसेसिंग सबएजेंट को सौंपें
टेस्ट एक्ज़ीक्यूशन या लॉग एनालिसिस जैसी बड़ी आउटपुट वाली प्रोसेसिंग सबएजेंट को दें। इससे मुख्य एजेंट के कॉन्टेक्स्ट पर दबाव नहीं पड़ता।
5. प्रॉम्प्ट में स्पष्ट निर्देश दें
"कोड सुधारो" के बजाय "auth.py के लॉगिन फ़ंक्शन में रेट लिमिटिंग जोड़ो और टेस्ट भी लिखो" जैसे विशिष्ट निर्देश देने से एजेंट कुशलता से काम करता है।
सारांश
Claude Agent SDK, AI एजेंट डेवलपमेंट की बाधाओं को काफ़ी कम करने वाला फ्रेमवर्क है। Claude Code के समान इंजन का उपयोग करते हुए, Python या TypeScript में स्वायत्त रूप से कार्य करने वाले एजेंट बनाए जा सकते हैं।
पहले Claude Code का उपयोग करके इंटरैक्टिव तरीके से एजेंट की कार्यप्रणाली को अनुभव करें, और जब ऑटोमेशन की आवश्यकता हो तब Agent SDK पर जाएं — यह चरणबद्ध दृष्टिकोण सबसे अच्छा है।
यदि आप लूप, सैंडबॉक्स और स्टेट को स्वयं चलाना नहीं चाहते, तो Anthropic का पूरी तरह मैनेज्ड विकल्प Claude Managed Agents है।
Claude की बुनियादी उपयोग विधि के बारे में, Claude की चैट, Cowork और कोड का अंतर भी ज़रूर पढ़ें।
अक्सर पूछे जाने वाले सवाल
क्या Claude Agent SDK मुफ़्त में उपयोग किया जा सकता है?
SDK स्वयं मुफ़्त है, लेकिन Claude API की उपयोग शुल्क लगती है (पहले से मंज़ूरी न हो तो claude.ai सब्सक्रिप्शन का लॉगिन SDK से बने प्रोडक्ट में इस्तेमाल नहीं किया जा सकता)। max_budget_usd से सीमा सेट की जा सकती है, पर यह रकम SDK का अपना अनुमान है, इसलिए असली खर्च Claude Console में जाँचें। डेवलपमेंट और टेस्टिंग के समय effort को "low" पर सेट करने से लागत कम होती है।
Agent SDK और Claude Code में क्या अंतर है?
Claude Code टर्मिनल या IDE में इंटरैक्टिव रूप से उपयोग किया जाने वाला टूल है, जबकि Agent SDK प्रोग्राम में एम्बेड करके ऑटोमेशन के लिए बनी लाइब्रेरी है। चूँकि SDK अंदर से Claude Code की बाइनरी चलाता है, बिल्ट-इन टूल्स, परमिशन, सेशन और हुक्स दोनों में एक जैसे काम करते हैं। रोज़मर्रा के डेवलपमेंट के लिए Claude Code और CI/CD या प्रोडक्शन ऑटोमेशन के लिए Agent SDK उपयुक्त है।
कौन-कौन सी प्रोग्रामिंग भाषाएं समर्थित हैं?
Python और TypeScript समर्थित हैं। एजेंट जिन चीज़ों पर काम करता है (फ़ाइल एडिटिंग और कमांड एक्ज़ीक्यूशन) में भाषा की कोई सीमा नहीं है, इसलिए Go, Rust, PHP आदि किसी भी भाषा के प्रोजेक्ट में इसका उपयोग किया जा सकता है।
MCP क्या है?
MCP (Model Context Protocol) AI मॉडल और बाहरी टूल्स को जोड़ने के लिए एक मानक प्रोटोकॉल है। डेटाबेस, ब्राउज़र ऑपरेशन, API आदि विभिन्न टूल्स को MCP सर्वर के रूप में बनाकर एजेंट से जोड़ा जा सकता है। Agent SDK MCP को सपोर्ट करता है, इसलिए थर्ड-पार्टी MCP सर्वर भी उपयोग किए जा सकते हैं।