Agent SDK: Claude Code की क्षमताओं को अपने स्वयं के प्रोग्राम में एकीकृत करना

📚 सीरीज नेविगेशन: पिछला लेख 44 GitHub Actions ने आपको सिखाया कि कैसे Claude को CI में एकीकृत करें और PR और पाइपलाइनों में काम स्वचालित करें। यह लेख एक कदम आगे बढ़ता है—केवल पाइपलाइनों में एकीकृत करने के बजाय, Claude Code की पूरी क्षमता को एक लाइब्रेरी मानकर इसे अपने प्रोग्राम और सेवाओं में एकीकृत करना。Agent SDK वह आधिकारिक तरीका है जो आपको "코드 के माध्यम से Claude एजेंट चलाने" की अनुमति देता है।

आज हम उस घटक के बारे में बात करेंगे जो आपको "केवल उपयोगकर्ता" से "विकासकर्ता" में बदल देता है।

前面四十多篇，你一直是 Claude Code 的用户——在终端敲 claude，跟它对话，看它改代码。这是它的「正面」。但它还有个「背面」你大概率没碰过：它的内核——那套读文件、跑命令、想了再做的代理循环——是可以被你的代码直接调起来的。

这就是 Agent SDK（Agent 软件开发工具包，让你在 Python / TypeScript 里编程调用 Claude Code 内核的一套库）。说白了，它把「Claude Code 是什么」从一个命令行工具，变成了你程序里的一个函数。你写几行代码，就能在自己的应用里跑出一个会自主读代码、改文件、查网络的 AI 代理。

इसकी उपयोगिता तब स्पष्ट होती है जब आप "स्वचालित PR समीक्षा बॉट" विकसित करना चाहते हैं। शुरुआत में, प्रत्यक्ष API का उपयोग करने पर, केवल "मॉडल को फ़ाइल पढ़ने की अनुमति देने" के लिए बहुत सारा जटिल कोड लिखना पड़ता था—फ़ाइल सामग्री को अनुरोध में जोड़ना, मॉडल के "X फ़ाइल पढ़ें" संकेत का पता लगाना, फ़ाइल पढ़ना, और फिर परिणाम वापस भेजना... इस चक्र में बहुत समय नष्ट होता था। Agent SDK के साथ, यह जटिलता समाप्त हो जाती है, और केवल तीन लाइनों के कोड के साथ, Claude स्वयं फ़ाइल पढ़ लेता है और बग ठीक कर देता है। आज हम इसी को स्पष्ट करेंगे।

इस लेख को पढ़ने के बाद, आपको मिलेगा:

• एक वाक्य में समझना कि Agent SDK क्या है, और यह Claude Code के किस हिस्से को प्रोग्रामिंग के लिए उपलब्ध कराता है
• यह आपके द्वारा दैनिक उपयोग किए जाने वाले CLI से कैसे भिन्न है—समान कोर, लेकिन दो अलग-अलग ट्रिगर बिंदु
• प्रत्यक्ष API (raw API) और इसमें क्या मूलभूत अंतर है
• TypeScript और Python संस्करणों में से कैसे चुनें, किस पैकेज को स्थापित करें, और क्या पूर्व आवश्यकताएं हैं
• एक न्यूनतम एजेंट कोड विन्यास और अभ्यास: इसे स्वयं एक बग खोजने और ठीक करने के लिए कहना
• यह समझना कि यह किसके लिए उपयुक्त है, और क्या आपको इसे सीखना चाहिए

---

01 先搞懂：Agent SDK 把 Claude Code 的什么「拆出来」了

पहले निष्कर्ष: Agent SDK, Claude Code कोर को एक लाइब्रेरी के रूप में प्रस्तुत करता है, जिससे आप कोड (Python या TypeScript) के माध्यम से CLI संस्करण के समान कार्यक्षमता वाले Claude एजेंट को ट्रिगर कर सकते हैं।

回想第 03 篇讲的「代理循环」——Claude 干活的本质是「想 → 做 → 看」转圈：想清楚下一步、调个工具去做（读文件、跑命令）、看结果再决定下一步。你在终端里用 claude 时，享受的就是这套循环加一堆内置工具（Read、Edit、Bash 这些，详见第 03 篇）。

关键认知：这套循环和工具，不是 CLI 独有的，它是可以被你的代码直接调起来的。 官方把这件事说得很直白：

Agent SDK 为您提供了与 Claude Code 相同的工具、代理循环和上下文管理，可在 Python 和 TypeScript 中编程。

एनालॉजी: कॉफी शॉप से ​​स्वचालित कॉफी मशीन को अपनी रसोई में लाना। 你天天去楼下咖啡馆点咖啡（这是用 CLI），喝得挺顺。但有一天你想在自己开的早餐店里也供应同款咖啡——你不可能让客人都跑去那家咖啡馆。于是你把同一台机器搬进自己店里：还是那个磨豆、萃取、打奶的内核，只不过现在嵌在你自己的流程里，你想什么时候出杯、出给谁、配上什么早餐套餐，全由你的代码说了算。Agent SDK 就是这台「搬得走的机器」——同款内核，装进你自己的程序里跑。

那它到底「拆出来」了什么？官方列得很清楚，CLI 里那些让 Claude 强大的东西，SDK 里一个不少：

• 内置工具：Read、Write、Edit、Bash、Glob、Grep、WebSearch 这些开箱即用，你不用自己实现工具怎么执行
• 代理循环：想→做→看那套编排，SDK 帮你转
• 上下文管理：哪些文件读过、对话历史，它替你记着
• 再往上，Hook、子代理、MCP、权限控制、会话恢复——CLI 有的扩展点，SDK 里都能编程调用

落到真实场景，你什么时候会想起它？举三个常见的念头：

• "मैं एक Slack बॉट विकसित करना चाहता हूँ, जो त्रुटि लॉग प्राप्त होने पर, कोडबेस में त्रुटि की पहचान करे और समाधान प्रस्तावित करे" — 这得把代理嵌进你的 Slack 服务
• "मैं एक अनुसूचित कार्य चलाना चाहता हूँ, जो प्रति रात कोडबेस में TODO की जांच करे और रिपोर्ट तैयार करे" — 这得用代码调起代理、还得能拿到它的输出
• "मैं अपने उत्पाद में एक एआई सहायक जोड़ना चाहता हूँ, जो उपयोगकर्ता की प्रोजेक्ट फ़ाइलों को सीधे संपादित कर सके" — 这更是非 SDK 不可

这三件物，用 CLI 都别扭——CLI 是给「人坐在终端前」设计的；而上面这些，是「程序自动调起、自动收结果」。这正是 SDK 的主场。

💡 一句话总结：Agent SDK 把 Claude Code 的内核（工具 + 代理循环 + 上下文管理）做成了一个库，让你用代码调起一个和 CLI 同款的 Claude 代理，嵌进自己的程序和服务里。

---

02 它和 CLI 到底差在哪：同一个内核，两个入口

这是最容易绕进去的一点，先把它彻底说清：Agent SDK 和你天天敲的 CLI，底下是同一套东西，区别只在「入口」——一个给人手敲，一个给程序调用。

官方那句话点得最准，我原封不动放这儿：

相同的功能，不同的界面。

एनालॉजी: समान कॉफी मशीन, काउंटर उपयोग बनाम वेंडिंग मशीन। 还是那台咖啡机（同一个内核）。摆在吧台后头，店员看着客人现点现做、随时能问「要不要加糖」——这是 CLI，适合人在场、边看边调。把同一台机器装进无人售卖机，投币、按钮、自动出杯、不用人盯——这是 SDK，适合「程序自动触发、批量跑、没人值守」。机器没变，变的是谁来按下那个按钮。

什么时候用哪个，官方给了张特别实在的对照表，我照搬过来：

परिदृश्य	最佳选择
交互式开发（你坐在终端边写边调）	CLI
一次性任务（临时让它干件事）	CLI
CI/CD 管道（流水线里自动跑）	SDK
自定义应用程序（嵌进你自己的产品）	SDK
生产自动化（无人值守、长期跑）	SDK

看这张表的窍门：问自己一句「这事儿是我人坐在这儿盯着，还是程序自动跑」。人盯着、要随时插话——CLI；程序自动起、自动收结果——SDK。

官方特意提了一句很关键的话，打消你「学了一个是不是另一个就白学」的顾虑：

许多团队同时使用两者：CLI 用于日常开发，SDK 用于生产。工作流在它们之间直接转换。

这话很实在。很多人就是这么用的：白天写代码，终端里 claude 随手使唤（CLI）；等某个流程被重复手敲到第五遍、烦了，就把它用 SDK 写成一个脚本挂起来自动跑。两边的「提示词」「该给哪些工具」「权限怎么配」这套思路是完全通的——你在 CLI 里攒的所有经验，搬到 SDK 里一行都不浪费。

所以别把它俩对立起来看。这么说吧：CLI 是你「亲自上手」的入口，SDK 是你「派程序去跑」的入口，背后是同一个 Claude Code。 一张图把这层关系画清楚：

这张图的意思：上面是两个不同的「入口」——人手敲走 CLI，程序调用走 SDK；但两条路汇到同一个 Claude Code 内核，最后干的活也是同一套。所以你才会看到「同内核、两入口」这个说法。

💡 一句话总结：CLI 和 SDK 同一个内核、两个入口——人坐着边看边调用 CLI、程序自动起批量跑用 SDK；两者常常一起用，你在 CLI 攒的经验搬到 SDK 完全通用。

---

03 别搞混：Agent SDK 不是「原始 API」，差在「谁来跑工具循环」

这一节是全篇最值钱的一个区分。搞不清它，你很可能以为自己在用 SDK，其实在重复造 Claude 早就给你造好的轮子。

你可能听过「Anthropic 的 API」或者「Client SDK」（直连模型 API 的那套客户端库）。它和 Agent SDK 名字像、都能调 Claude，但干的活根本不是一回事。一句话区分：

Client SDK 给你「会说话的模型」，工具循环你自己写；Agent SDK 给你「会干活的代理」，工具循环它替你跑。

官方解释得很到位：

Anthropic Client SDK 为您提供直接 API 访问：您发送提示并自己实现工具执行。Agent SDK 为您提供具有内置工具执行的 Claude。

एनालॉजी: कच्चे कॉफी बीन्स खरीदना बनाम पूरी तरह से स्वचालित कॉफी मशीन खरीदना। Client SDK 像是商家只卖给你生咖啡豆——豆子是好豆子（模型很强），但想喝上一杯，烘焙、磨粉、烧水、萃取、打奶，每一步都得你自己动手。Agent SDK 是直接给你一台全自动机——你按一下「美式」，它内部该磨磨、该萃萃，直接给你出一杯。模型是同一批豆子，区别在「中间那一堆工序谁来做」。

落到代码上，差别一眼就能看出来。这是官方给的对比（Python），你感受一下两边的代码量：

# Client SDK：工具循环得你自己写
response = client.messages.create(...)
while response.stop_reason == "tool_use":
    result = your_tool_executor(response.tool_use)   # 你自己去执行工具
    response = client.messages.create(tool_result=result, **params)  # 再把结果喂回去

# Agent SDK：Claude 自己把工具跑了
async for message in query(prompt="Fix the bug in auth.py"):
    print(message)

看出来了吗？Client SDK 那个 while 循环——「模型说要用工具 → 你去执行 → 把结果传回去 → 模型接着想」——就是开头折腾大半天的那一坨。 模型只会「说」它想读 auth.py，但真去读这个动作，得你写代码完成，读完还得手动把内容塞回去。这套「工具循环」你得从头实现。

Agent SDK 把这一整个 while 循环收进了那个 query() 里。你只管说「修掉 auth.py 的 bug」，它自己决定读哪个文件、自己去读、自己改、自己验，你坐着收消息流就行。

这就是开头那个教训的根儿。做 PR 审查机器人时，很容易头两天就栽在这个 while 循环上——接模型的 tool_use、自己实现「读文件」「跑 git diff」、再把结果回传，逻辑绕、还老有边界情况漏掉。一旦发现 Agent SDK 把这层全包了，那几百行胶水代码当场就能删到只剩个 query() 调用。所以这条得给你钉死：

तुलनात्मक श्रेणी	Client SDK (प्रत्यक्ष API)	Agent SDK
आपको मिलता है	访问模型的 Client	运行 Agent
工具谁执行	你自己写代码执行	Claude 自动执行
那个 while 工具循环	你从头实现	SDK 替你跑
内置工具（读写文件、跑命令）	没有，全自己来	开箱即用
适合	要极致定制、不需要文件系统操作	要一个能直接动手干活的代理

判断口诀：你要的是「一个能直接读你文件、跑你命令、动手改代码的代理」——选 Agent SDK，别去碰那个 while 循环。 只有当你压根不需要它操作文件系统、就想要个纯对话且要极致控制每一步时，才考虑 Client SDK。

💡 一句话总结：Agent SDK ≠ 原始 API——原始 API（Client SDK）给你模型、工具循环你自己写；Agent SDK 给你代理、工具循环它替你跑。要「会动手干活的 Claude」，认准 Agent SDK，省下那一大坨胶水代码。

---

04 两套语言：TypeScript 和 Python，装哪个、要什么前置

Agent SDK 官方提供两套，按你顺手的语言挑：TypeScript 和 Python。功能上两边对齐，官方文档每个示例都同时给两种写法，所以别纠结「哪个功能更全」——挑你团队和项目本来就在用的那门语言就对了。

怎么选，就一句话：你的程序用什么写，就用哪套 SDK。 后端是 Node / 前端工程化栈——TypeScript；做数据、脚本、AI 工程——Python。没有对错，跟着你的项目走。

装哪个包、要什么前置条件

两套的安装命令和前置要求不一样，我对照列清楚（全部照官方文档，没编造）：

	TypeScript	Python
安装命令	npm install @anthropic-ai/claude-agent-sdk	pip install claude-agent-sdk
前置环境	Node.js 18+	Python 3.10+
要单独装 Claude Code 吗	不用（SDK 自带一个二进制）	见下方说明

TypeScript 这边有个很省心的细节，官方专门标了出来：

TypeScript SDK 为您的平台捆绑了一个本地 Claude Code 二进制文件作为可选依赖项，因此您无需单独安装 Claude Code。

也就是说，TS SDK 装上就能跑，不用你先去装 Claude Code 本体。

Python 这边有个版本坑，官方也点了——包要求 Python 3.10 或更高。如果 pip 报 No matching distribution found for claude-agent-sdk，八成是你的 Python 太老了。先查版本：

python3 --version        # macOS / Linux
py --version             # Windows

低于 3.10 就升级。在一台老 Mac 上装很容易栽在这儿——系统自带的 python 还是 3.9，报的就是那个 No matching distribution，升到 3.11 就能秒装上。

还得有 API 密钥

不管哪套，跑之前都得有个 Anthropic 的 API 密钥（API key，调用模型的身份凭证）。官方建议在项目目录建个 .env 文件放进去：

ANTHROPIC_API_KEY=your-api-key

密钥从 Claude 控制台（platform.claude.com ）拿；它是凭证，千万别提交进 git——记得加进 .gitignore。这套 API 配置的来龙去脉，第 04 篇讲透过，不熟的回去翻。

这里有个计费上的重要提醒，官方在文档开头用醒目框标了出来，我原话搬给你（涉及你的钱，不能含糊）：

从 2026 年 6 月 15 日开始，订阅计划上的 Agent SDK 和 claude -p 使用将从一项新的每月 Agent SDK 额度中扣除，该额度与您的交互式使用限额分开。

翻成大白话：你订阅套餐里那份「交互式额度」（你在终端聊天用的），和「Agent SDK 额度」从这天起是分开两本账。所以别以为「我有订阅了，SDK 随便跑」——SDK 这边走的是单独的额度。具体规则以官方那篇说明为准。

💡 一句话总结：两套 SDK 功能对齐、按语言挑——TS 用 npm install @anthropic-ai/claude-agent-sdk（Node 18+，自带二进制免装本体），Python 用 pip install claude-agent-sdk（要 3.10+）；都得配 ANTHROPIC_API_KEY，且注意 SDK 额度和交互式额度分开计费。

---

05 一段代码看懂它长啥样：query() 是入口

讲了半天，上代码你才有体感。Agent SDK 的主入口就一个东西：query()。 把它搞懂，整套 SDK 的门就推开了。

官方那个最小例子，我们逐行拆。先看 Python 版：

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions

async def main():
    async for message in query(
        prompt="Find and fix the bug in utils.py",
        options=ClaudeAgentOptions(allowed_tools=["Read", "Edit", "Bash"]),
    ):
        print(message)  # Claude 读文件、找到 bug、改掉它

async def main():
    async for message in query(
        prompt="Find and fix the bug in auth.py",
        options=ClaudeAgentOptions(allowed_tools=["Read", "Edit", "Bash"]),
    ):
        print(message)  # Claude 读文件、找到 bug、改掉它

asyncio.run(main())

TypeScript 版是一模一样的逻辑：

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

for await (const message of query({
  prompt: "Find and fix the bug in auth.ts",
  options: { allowedTools: ["Read", "Edit", "Bash"] }
})) {
  console.log(message); // Claude 读文件、找到 bug、改掉它
}

就这么点。拆开看三个关键部分（官方原话归纳）：

① query()——代理循环的主入口。 它返回一个「异步迭代器」（async iterator，可以一条条往外吐消息的对象），所以你用 async for（TS 里是 for await）来流式接住 Claude 干活过程中冒出来的每一条消息：它的思考、它调了哪个工具、工具返回了啥、最终结果。

② prompt——你想让它干啥。 跟你在 CLI 里敲的那句话没区别。这里是「找出并修掉 auth.py 里的 bug」。Claude 自己判断要用哪些工具。

③ options——这个代理的配置。 最常用的就是 allowed_tools（TS：allowedTools），预先批准它能用哪些工具。上面给了 Read、Edit、Bash，意思是「准你读文件、改文件、跑命令」。

注意那个 async for / for await 循环——它会一直转，直到 Claude 把活干完或出错。每转一圈吐一条消息，SDK 在背后默默处理工具执行、上下文管理、重试这些脏活，你只管消费这个消息流。官方原话：

SDK 处理编排（工具执行、上下文管理、重试），所以你只需使用流。

这就是它跟原始 API 最爽的地方——你看这段代码里根本没有那个 while 工具循环，全被 query() 吞了。

再说一个给工具就是给权限的关键点（呼应第 20 篇的权限）。你在 allowed_tools 里给什么，直接决定这代理能干多少事。官方给了张特别清楚的对照：

अनुमत उपकरण	एजेंट की क्षमता
Read、Glob、Grep	只读分析（能看不能改）
Read、Edit、Glob	分析 + 改代码
Read、Edit、Bash、Glob、Grep	完全自动化（能看、能改、能跑命令）

想做个「只许看不许动」的安全代理？只给它 Read、Glob、Grep 就行。 这比 CLI 里临时把关更彻底——代理压根没拿到 Edit，它想改也改不了。

补一句给 Python 用户的：除了一次性的 query()，Python SDK 还有个 ClaudeSDKClient——它是对 query() 的封装，让多次调用自动共享同一个 session，不用手动传 resume 参数。适合聊天界面、REPL 这类多轮对话场景；一次性任务用 query() 就够，刚上手先把它吃透。

💡 一句话总结：Agent SDK 的入口是 query()——给它 prompt（干啥）和 options（配置，最关键是 allowed_tools 决定它能用哪些工具），它返回一个消息流让你 async for 接住；那个原始 API 里的 while 工具循环，被 query() 整个吞掉了。

---

06 动手：5 分钟跑一个「自己找 bug、自己修」的代理

光看不练假把式。这一节带你亲手跑通官方那个最经典的入门代理——故意写段有 bug 的代码，让代理自己找出来、自己修掉。全程不依赖你已有的任何复杂项目，照着敲就行。下面用 Python 演示（TS 流程一样，命令在每步标了）。

前置：Node.js 18+ 或 Python 3.10+，外加一个 Anthropic API 密钥。装 SDK、调用模型都要联网；国内访问如果不通，先开「魔法上网」再试。

第一步：建个空目录，进去

mkdir my-agent
cd my-agent

第二步：装 SDK 并配密钥

Python（用自带的 venv）：

python3 -m venv .venv
source .venv/bin/activate
pip install claude-agent-sdk

TypeScript 就改成 npm install @anthropic-ai/claude-agent-sdk。

然后在 my-agent 目录里建个 .env，写进你的密钥：

ANTHROPIC_API_KEY=your-api-key

अपेक्षा: pip install 打印 Successfully installed claude-agent-sdk-...。看到 Successfully installed = SDK 装好了。 如果报 No matching distribution found，是 Python 版本低于 3.10，先升级（见第 04 节）。

第三步：造一个有 bug 的文件

在 my-agent 里新建 utils.py，原样粘进这段（这是官方的示例代码，里面埋了两个会崩的 bug）：

def calculate_average(numbers):
    total = 0
    for num in numbers:
        total += num
    return total / len(numbers)


def get_user_name(user):
    return user["name"].upper()

两个 bug 是：calculate_average([]) 传空列表会除以零崩掉；get_user_name(None) 会报 TypeError。

第四步：写那个代理

新建 agent.py，粘进这段：

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage, ResultMessage


async def main():
    # 代理循环：Claude 边干活边把消息流式吐出来
    async for message in query(
        prompt="Review utils.py for bugs that would cause crashes. Fix any issues you find.",
        options=ClaudeAgentOptions(
            allowed_tools=["Read", "Edit", "Glob"],  # 预先批准这几个工具
            permission_mode="acceptEdits",            # 自动批准文件编辑
        ),
    ):
        # 只打印人类看得懂的部分
        if isinstance(message, AssistantMessage):
            for block in message.content:
                if hasattr(block, "text"):
                    print(block.text)              # Claude 的思考
                elif hasattr(block, "name"):
                    print(f"Tool: {block.name}")   # 它正在调用的工具
        elif isinstance(message, ResultMessage):
            print(f"Done: {message.subtype}")      # 最终结果


asyncio.run(main())

这里多了个第 05 节没细讲的选项：permission_mode="acceptEdits"——自动批准文件编辑，这样代理改文件时不会停下来等你点头（适合这种你信任的脚本）。权限模式官方给了好几档，挑你眼熟的看：

许可模式	行为	适用场景
acceptEdits	自动批准文件编辑和常见文件系统命令，其他操作仍问你	受信任的开发工作流（本例用的就是它）
bypassPermissions	每个工具都不问、直接跑	沙箱 CI、完全受信任的环境
default	需要你提供回调来处理批准	要自定义批准流程
dontAsk	未预批准的工具直接拒绝，不提示	锁定的 CI、无头脚本
plan	只允许只读工具，Claude 只分析不改文件	先规划后再批准执行

第五步：跑起来

python agent.py

TypeScript 是 npx tsx agent.ts。

अपेक्षा：终端会流式滚出代理的工作过程——先是它的思考（比如说要先读 utils.py）、然后 Tool: Read、Tool: Edit 这类工具调用行，最后一行 Done: success。看到 Done: success = 代理跑完了。

第六步：验收——看 utils.py 被改成啥样了

重新打开 utils.py。अपेक्षा：你会看到代理自己加了防御性代码——比如 calculate_average 里多了「空列表就返回 0（或抛个清楚的错）」的判断，get_user_name 里多了「user 为 None / 没有 name 字段时的处理」。

这就是 Agent SDK 的精髓，官方原话点破：

这就是 Agent SDK 的与众不同之处：Claude 直接执行工具，而不是要求你实现它们。

整个过程里，代理自主地：读了 utils.py 理解代码 → 分析出会崩的边界情况 → 编辑文件加上错误处理。你一行业务逻辑没写，全是它干的。

跑通这一趟，你就把「装 SDK → 配密钥 → 写 query() → 给工具和权限 → 收消息流 → 验结果」这条完整链路亲手走了一遍。以后做任何 SDK 代理，骨架都是这套——无非换个 prompt、调整 allowed_tools、按需配权限和 MCP。

顺带一提，官方还建议你换些 prompt 玩玩，体会同一套代码干不同的活："Add type hints to all functions in utils.py"（加类型标注）、"Write unit tests for utils.py, run them, and fix any failures"（写测试、跑、修挂的——这个得在 allowed_tools 里加上 Bash）。

💡 一句话总结：跑通入门代理就六步——建目录、装 SDK 配密钥、造个带 bug 的文件、写 query() 代理、python agent.py 跑、看文件被自动修好；亲手走一遍，比记十个 API 参数都管用。

---

07 这玩意儿适合谁：你该不该现在就上手

最后掏心窝子说一句：Agent SDK 不是每个人都得马上学的东西，但「想拿 Claude 干点自动化」的人迟早绕不开它。 帮你对号入座，省得学错方向。

先说什么时候你压根用不上它。 如果你就是想在终端里让 Claude 帮你写代码、改 bug、跑命令——老老实实用 CLI，别碰 SDK。SDK 是「写程序去调 Claude」，你要是没有「写程序」这个需求，它对你就是多余的复杂度。有人刚学会 CLI 就急着上 SDK，结果在 async / 异步迭代器上卡半天，正经活儿一件没干——这就是典型的方向错了。

那什么时候你该上？ 三类信号，中一条就值得学：

信号（你心里冒出的念头）	该不该上 SDK
"मैं केवल टर्मिनल में सहायता चाहता हूँ"	❌ 用 CLI 就够，别碰 SDK
"मैं एक ही प्रक्रिया को कई बार दोहरा रहा हूँ, और स्वचालन चाहता हूँ"	✅ 该上，写成 SDK 脚本挂起来
"मैं अपने उत्पाद में एआई एजेंट कार्यक्षमता जोड़ना चाहता हूँ"	✅ 必须上，这是 SDK 主场
"मैं एक स्वचालित रोबोट या अनुसूचित कार्य बनाना चाहता हूँ"	✅ 该上，CLI 干这个很别扭

官方还给了一条很实在的「成长路径」建议，适合你心里有个谱：

一个常见的路径是先使用 Agent SDK 在本地进行原型设计，然后为生产环境迁移到 Managed Agents。

这里冒出个新名词 Managed Agents（托管代理）——简单说，它是 Anthropic 替你托管运行代理和沙箱的一套 REST API，你的程序发事件、收结果，不用自己操心跑在哪、会话怎么存。而 Agent SDK 是在你自己的进程里跑代理循环。两者的取舍，官方一张表说清（我精简了关键几行）：

	Agent SDK	Managed Agents
कहाँ चलता है	आपके अपने सर्वर / बुनियादी संरचना पर	Anthropic 托管的基础设施
界面	Python / TypeScript 库	REST API
代理操作的文件	आपके स्थानीय कंप्यूटर की वास्तविक फ़ाइलें	每个会话一个托管沙箱
最适合	स्थानीय प्रोटोटाइप, प्रत्यक्ष फ़ाइल ऑपरेशन्स	生产级、不想自己运维沙箱和会话

对小白和大多数人来说，路径很清晰：先用 Agent SDK 在本地把想法跑通（就像第 06 节那样），等真要上线、要扛流量、不想自己运维了，再考虑迁到 Managed Agents。前者是你学习和原型的起点，后者是生产化的进阶——现在，把 Agent SDK 这一步走扎实就够了。

最后说一句。把好几个重复的手工流程改成 SDK 脚本——比如每周扫一遍几个仓库的过期依赖、自动整理成一份清单。头一回把它挂上定时任务、第二天早上看到报告自己生成好躺在那儿的时候，那种「造了个会自己干活的东西」的感觉，是用 CLI 给不了的。 如果你也有那种「同一件事手敲烦了」的时刻——那就是 SDK 在向你招手了。

💡 一句话总结：只想终端里使唤 Claude → 用 CLI 别碰 SDK；想自动化某个重复流程、或给产品加个会干活的 AI → 上 SDK；路径是「先用 Agent SDK 本地跑通，要生产化再迁 Managed Agents」，现在把第一步走扎实就行。

---

08 सारांश

这一篇我们掀开了 Claude Code 的「背面」——它的内核可以被你的代码当成一个库调起来，这就是 Agent SDK。

把核心要点串起来回顾：

वह प्रश्न जिसे आप स्पष्ट करना चाहते हैं	उत्तर	मुख्य बिंदु
Agent SDK 是什么	Claude Code 内核做成的库	同款工具+代理循环+上下文管理，可编程调用
和 CLI 啥关系	同一个内核，两个入口	人手敲用 CLI、程序调用 SDK，经验通用
和原始 API 啥区别	工具循环谁来跑	原始 API 你自己写 while，SDK 替你跑
两套语言怎么选	按你的项目语言挑	TS（Node 18+）/ Python（3.10+），功能对齐
入口是啥	query()	给 prompt + options，收消息流
该不该学	看你有没有「自动化/嵌产品」需求	只用 CLI 别碰，想自动化就上

अब आपको यह करने में सक्षम होना चाहिए: Agent SDK की मुख्य अवधारणाओं को स्पष्ट करना, CLI और प्रत्यक्ष API से इसके अंतर को जानना, विन्यास आवश्यकताओं को समझना, query() कोड संरचना की व्याख्या करना, और व्यावहारिक अभ्यास पूरा करना।

到这儿，你对 Claude Code 的认知已经从「一个命令行工具」升级成了「一套既能亲自用、又能编程嵌入的代理能力」。它不再只是你手里的工具，而是你能拿去造东西的零件。

---

अगला लेख 46 "विकास विन्यास (Development Configuration)" — SDK एजेंटों के विकास के लिए विन्यास आवश्यक है: API कुंजी सुरक्षा, विविध वातावरण (विकास बनाम उत्पादन) विन्यास, और तृतीय-पक्ष मॉडल प्रदाताओं के लिए पर्यावरण चर सेटअप。ये कदम यह सुनिश्चित करते हैं कि आपका एजेंट स्थानीय और सर्वर दोनों वातावरणों में सुचारू रूप से चल सके। अगले लेख में हम इन संवेदनशील विन्यासों को समझेंगे।

---

अनुशंसित पठन

• समानांतर कार्य: एक साथ कई सत्र चलाना
• पहला उपयोग: प्रारंभिक उदाहरण का निष्पादन
• इंटरफ़ेस और शॉर्टकट: नियंत्रण को समझना