AI Agent / 系统课时
使用 Agent SDK
使用 Agent SDK
本节用 TypeScript 把 Claude Code 的代理循环嵌入自己的程序。你会完成一个可运行的自动化入口:流式接收结果、限制工具权限、捕获会话 ID,并用 resume 继续同一上下文,而不必自己实现工具调用循环。
学习目标
- 使用
@anthropic-ai/claude-agent-sdk的query()构建流式代理 - 用
allowedTools、permissionMode控制无头自动化的工具边界 - 捕获
session_id并通过resume延续多轮任务上下文
认识 Agent SDK 的执行模型
Agent SDK 把 Claude Code 的代理循环作为 Python 或 TypeScript 库提供。应用把任务交给 query() 后,Claude 可以规划步骤、调用内置工具、读取工具结果并继续推理;调用方只需要消费异步消息流,而不是手写“模型请求 → 工具执行 → 再请求模型”的循环。

这个模型里有四个需要分开理解的对象:会话保存上下文,工具决定代理能接触什么能力,权限策略决定哪些调用可自动执行,消息流让应用实时看到进度和最终结果。它们共同构成可控的自动化程序。
准备 TypeScript 项目
Node.js 18+ 可以直接使用官方 TypeScript SDK。下面创建 ESM 项目并安装 SDK 与 tsx,后续示例文件命名为 agent.ts。
npm init -y
npm pkg set type=module
npm install @anthropic-ai/claude-agent-sdk
npm install --save-dev tsx预期输出中的包数量会随依赖版本变化:
Wrote to <PATH>/package.json
added <VALUE> packages
added <VALUE> packages如果依赖已经存在,npm 可能显示 up to date。运行代理前,把 ANTHROPIC_API_KEY 注入进程环境,不要写进源文件;SDK 不会自动读取 .env,使用 .env 时需要由应用自行加载。
构建带会话和权限的流式代理
创建 agent.ts。这个示例只允许读取仓库,不允许修改文件或执行 Shell,因此适合先作为分析型自动化基线。
import { query } from "@anthropic-ai/claude-agent-sdk";
async function run(prompt: string, resume?: string): Promise<string> {
let sessionId = resume ?? "";
for await (const message of query({
prompt,
options: {
allowedTools: ["Read", "Glob", "Grep"],
permissionMode: "dontAsk",
...(resume ? { resume } : {})
}
})) {
// assistant 消息会随着代理工作持续到达
if (message.type === "assistant") {
for (const block of message.message.content) {
if (block.type === "text") {
process.stdout.write(block.text);
}
}
}
// result 是一次 query 的终态,同时提供可恢复的会话 ID
if (message.type === "result") {
sessionId = message.session_id;
console.log(`\n[result=${message.subtype}] session=${sessionId}`);
if (message.subtype !== "success") {
throw new Error(`Agent failed: ${message.subtype}`);
}
}
}
if (!sessionId) {
throw new Error("Agent did not return a session id");
}
return sessionId;
}
const sessionId = await run(
"Inspect this repository and summarize its main modules plus one maintenance risk."
);
await run(
"Using the previous analysis, propose three focused follow-up checks.",
sessionId
);运行程序:
npx tsx agent.ts预期输出的正文取决于当前仓库,关键结构如下:
<STREAMED_ANALYSIS>
[result=success] session=<ID>
<STREAMED_FOLLOW_UP>
[result=success] session=<ID>第二次调用通过 resume 使用第一次返回的 <ID>,因此能继承前一轮的对话和工具结果上下文,不需要重新解释“之前分析了什么”。
正确理解工具与权限
allowedTools 的含义是预先批准匹配的工具,它本身不等于“只有这些工具存在”。在默认权限模式下,未列出的工具仍可能继续进入权限判断。无头自动化若想得到固定的只读能力面,可以像示例一样把 allowedTools 与 permissionMode: "dontAsk" 配对:列出的读取工具自动通过,其他未批准调用直接拒绝而不是等待人工确认。
如果任务需要修改代码,可以按最小范围加入 Edit 或 Write;需要运行构建或测试时再考虑 Bash。不要为了省事直接使用 bypassPermissions,因为它会大幅放宽自动执行范围。真正需要人工审批时,应使用默认权限模式配合 canUseTool,或者用 Hook 在工具执行前实施统一策略。
会话也有边界:session_id 保存的是代理的对话历史、工具调用与结果,不是文件系统快照。恢复会话前如果仓库内容已经改变,Claude 看到的文件仍以当前工作目录为准;需要回滚文件变更时应使用版本控制或文件检查点机制。
扩展到生产自动化
生产程序通常还要补三层能力:用 MCP 接入数据库、浏览器或内部 API;用 Hook 记录、拒绝或改写关键工具调用;把 session_id 与业务用户或任务 ID 建立映射,以便在进程重启后继续指定会话。多实例或无状态部署还需要把会话记录同步到共享存储,而不能假设本机磁盘永久存在。
当你的自动化既能持续输出进度,又能明确限制工具集合和恢复指定会话时,Agent SDK 才真正从“一次模型调用”变成可嵌入业务系统的受控代理运行时。