Claude Agent SDK गाइड: Claude Code को apps में सुरक्षित जोड़ें

अगर आप Claude Code को केवल terminal assistant की तरह नहीं, बल्कि internal tools, CI, PR review, content QA या support workflow में चलाना चाहते हैं, तो आज का सही starting point Claude Agent SDK है।

पुराने examples में अभी भी @anthropic-ai/claude-code, claude-code-sdk या “Claude Code SDK” लिखा मिल सकता है। जून 2026 तक official docs TypeScript के लिए @anthropic-ai/claude-agent-sdk और Python के लिए claude-agent-sdk बताते हैं। इसलिए code copy करने से पहले official Agent SDK overview और Migration Guide देखें।

यह लेख chatbot demo नहीं है। लक्ष्य है ऐसा agent बनाना जो files पढ़ सके, repository search कर सके, MCP tool call कर सके, सीमित permission में छोटा fix कर सके, specific test चला सके, और ऐसा result दे जिसे human review कर सके।

Agent SDK को सही तरह समझना

Claude Agent SDK Claude Code के agent loop को TypeScript या Python app में इस्तेमाल करने देता है। agent loop का मतलब है: Claude अगला action चुनता है, tool चलाता है, result पढ़ता है, और फिर decide करता है कि आगे क्या करना है। यह normal chat API से अलग है, क्योंकि एक task में कई tool turns हो सकते हैं।

Topic	Current recommendation
TypeScript package	@anthropic-ai/claude-agent-sdk
Python package	claude-agent-sdk
CLI vs SDK	CLI human interaction के लिए, SDK app automation के लिए
Client SDK vs Agent SDK	Client SDK में loop खुद बनता है, Agent SDK Claude Code loop देता है
Main risk	ज्यादा permission मतलब ज्यादा usefulness और ज्यादा risk

TypeScript SDK अक्सर native Claude Code binary को optional dependency के रूप में लाता है। अगर package manager optional dependencies skip करता है, तो binary missing error आ सकता है। ऐसे में install policy ठीक करें या pathToClaudeCodeExecutable में installed claude का path दें।

Copy-paste setup

TypeScript और tsx से शुरू करते हैं ताकि examples तुरंत चलें।

mkdir claude-agent-sdk-demo
cd claude-agent-sdk-demo
npm init -y
npm install @anthropic-ai/claude-agent-sdk zod
npm install -D typescript tsx @types/node

package.json को इस form में रखें:

{
  "type": "module",
  "scripts": {
    "audit": "tsx src/read-only-audit.ts",
    "runbook": "tsx src/runbook-agent.ts",
    "fix": "tsx src/safe-fix.ts"
  },
  "dependencies": {
    "@anthropic-ai/claude-agent-sdk": "latest",
    "zod": "latest"
  },
  "devDependencies": {
    "@types/node": "latest",
    "tsx": "latest",
    "typescript": "latest"
  }
}

API key environment variable में रखें। इसे repo, article, screenshot या CI logs में न डालें।

export ANTHROPIC_API_KEY="sk-ant-..."

Windows PowerShell:

$env:ANTHROPIC_API_KEY = "sk-ant-..."

पहले src/read-only-audit.ts बनाएं। यह agent केवल पढ़ता और search करता है; edit या Bash नहीं चलाता।

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

const prompt = [
  "इस repository को read-only mode में inspect करें.",
  "TODO comments, old dependencies और weak tests वाली जगहें खोजें.",
  "Priority order में concrete file references के साथ report करें.",
].join("\n");

for await (const message of query({
  prompt,
  options: {
    cwd: process.cwd(),
    allowedTools: ["Read", "Glob", "Grep"],
    maxTurns: 4,
  },
})) {
  if (message.type === "result" && message.subtype === "success") {
    console.log(message.result);
  }
}

Run करें:

npm run audit

Read-only से शुरू करना जरूरी है। पहले signal देखें, फिर Edit, Write या Bash खोलें।

Practical use cases

Claude Agent SDK तब सबसे useful है जब task में observation, tool use और decision चाहिए। Masa के development और content workflow में ये cases practical हैं:

Use case	Tools	Output	Guardrail
PR pre-review	Read, Glob, Grep	Risk list, missing tests, review focus	Final comment human post करे
Small safe fix	Read, Edit, Bash(npm test)	Minimal diff और test result	push, deploy, delete block करें
Incident triage	MCP runbook, log search	Hypothesis और next checks	Production tools read-only रखें
Multilingual article QA	Read, Grep	mojibake, missing CTA, old links	Language human review करे

Related reading के लिए Claude Code permissions guide, MCP server guide, और Claude Code productivity tips देखें।

MCP से Runbook tool जोड़ना

MCP यानी Model Context Protocol। आसान भाषा में, यह agent को tools और data sources देने का standard तरीका है। Official MCP guide Agent SDK में MCP server जोड़ना समझाता है। नीचे example same process में छोटा read-only tool बनाता है।

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

const runbooks: Record<string, string> = {
  billing: "Failed payments, Stripe webhooks और latest deploy देखें.",
  search: "Index time, Algolia task status और API limits देखें.",
  content: "CMS sync, locale slugs और hero image presence देखें.",
};

const lookupRunbook = tool(
  "lookup_runbook",
  "Service name से read-only operations runbook लौटाता है",
  { service: z.string().min(1) },
  async ({ service }) => {
    const text = runbooks[service] ?? "Runbook नहीं मिला.";
    return { content: [{ type: "text", text }] };
  },
  { annotations: { readOnlyHint: true, openWorldHint: false } },
);

const runbookServer = createSdkMcpServer({
  name: "runbook",
  version: "1.0.0",
  tools: [lookupRunbook],
});

for await (const message of query({
  prompt: "Content publishing incident के first checks suggest करें.",
  options: {
    mcpServers: { runbook: runbookServer },
    allowedTools: ["mcp__runbook__lookup_runbook"],
    maxTurns: 3,
  },
})) {
  if (message.type === "result" && message.subtype === "success") {
    console.log(message.result);
  }
}

Common mistake tool name है। MCP tools को mcp__serverName__toolName के रूप में allow करना होता है। सिर्फ lookup_runbook काफी नहीं है।

Edit permission को छोटा रखें

जब read-only audit useful लगे, तब छोटा fix allow करें। Production में लिखने या command चलाने वाले agent से पहले official permissions guide पढ़ें।

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

const prompt = [
  "src के अंदर केवल एक छोटा TypeScript error fix करें.",
  "Fix के बाद npm test run करें और diff summary दें.",
  "Large refactor या dependency add न करें.",
].join("\n");

for await (const message of query({
  prompt,
  options: {
    cwd: process.cwd(),
    allowedTools: [
      "Read",
      "Glob",
      "Grep",
      "Edit",
      "Bash(npm test)",
    ],
    disallowedTools: [
      "Bash(git push)",
      "Bash(git commit)",
      "Bash(rm -rf *)",
    ],
    permissionMode: "default",
    maxTurns: 6,
  },
})) {
  if (message.type === "result") {
    console.log(message.subtype, message.result ?? "");
  }
}

यह pattern agent को सब कुछ करने की छूट नहीं देता। इसका उद्देश्य reviewable diff और test evidence बनाना है।

Pitfalls

पहला pitfall पुराना package name है। @anthropic-ai/claude-code या ClaudeCodeOptions दिखे तो migration docs चेक करें।

दूसरा pitfall unrestricted Bash है। इससे test के अलावा git, deploy, cleanup या install commands भी चल सकते हैं। शुरुआत Bash(npm test) से करें।

तीसरा pitfall cwd न देना है। Local, CI और worker अलग folders से start हो सकते हैं। Production code में target repository explicit रखें।

चौथा pitfall Agent SDK को normal chat SDK समझना है। Agent कई files पढ़ सकता है और कई turns ले सकता है। Official cost tracking guide देखें, usage log करें और limits रखें।

पांचवां pitfall vague tool description है। Tool name, description, schema और read-only annotation साफ लिखें।

Checklist, CTA और tested note

• API keys और tokens logs में नहीं आते।
• First run में केवल Read, Glob, Grep हैं।
• Write agent में cwd, tool limits और maxTurns हैं।
• MCP tools read-only और destructive actions अलग रखते हैं।
• Test command specific है, free shell नहीं।
• Merge से पहले human diff और test output देखता है।

Claude Agent SDK का goal सब कुछ automate करना नहीं, बल्कि automation को reviewable बनाना है। Monetized content में यह और जरूरी है: CTA, product links, analytics events और consultation forms एक run में बदल सकते हैं।

Solo start के लिए free Claude Code cheatsheet देखें। Reusable prompts और setup templates के लिए products देखें। Team rollout, permissions, MCP और CI review gates के लिए Claude Code training और consultation बेहतर रास्ता है।

इस refresh में official overview, TypeScript reference, MCP, permissions, migration और cost tracking docs चेक किए गए। सबसे practical बदलाव यह था कि पहला example read-only रखा गया। npm run audit से पहले observe करें, फिर MCP, edit और test execution जोड़ें। Real repository में यही staged approach ज्यादा सुरक्षित है।