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 可以规划步骤、调用内置工具、读取工具结果并继续推理;调用方只需要消费异步消息流,而不是手写“模型请求 → 工具执行 → 再请求模型”的循环。

Agent SDK 的会话、权限、工具与流式消息关系

这个模型里有四个需要分开理解的对象:会话保存上下文,工具决定代理能接触什么能力,权限策略决定哪些调用可自动执行,消息流让应用实时看到进度和最终结果。它们共同构成可控的自动化程序。

准备 TypeScript 项目

Node.js 18+ 可以直接使用官方 TypeScript SDK。下面创建 ESM 项目并安装 SDK 与 tsx,后续示例文件命名为 agent.ts。

bash
npm init -y
npm pkg set type=module
npm install @anthropic-ai/claude-agent-sdk
npm install --save-dev tsx

预期输出中的包数量会随依赖版本变化:

text
Wrote to <PATH>/package.json
added <VALUE> packages
added <VALUE> packages

如果依赖已经存在,npm 可能显示 up to date。运行代理前,把 ANTHROPIC_API_KEY 注入进程环境,不要写进源文件;SDK 不会自动读取 .env,使用 .env 时需要由应用自行加载。

构建带会话和权限的流式代理

创建 agent.ts。这个示例只允许读取仓库,不允许修改文件或执行 Shell,因此适合先作为分析型自动化基线。

ts
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
);

运行程序:

bash
npx tsx agent.ts

预期输出的正文取决于当前仓库,关键结构如下:

text
<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 才真正从“一次模型调用”变成可嵌入业务系统的受控代理运行时。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

使用 Agent SDK

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通