16Agent SDK

Anthropic 三个层级的接口,从低到高:

Agent SDK 的核心价值:复用 Claude Code 同款的 agent harness——同一个 loop 实现、同一套 file ops/bash 工具、同样的 hooks(PreToolUse、PostToolUse、PreCompact、UserPromptSubmit、Stop)、同样的 permission 系统。让"做 agent"从 1000 行起步降到 30 行。

能力对比:

用 Client SDK 造 agent:
  - 自己写 while loop
  - 自己 parse stop_reason / tool_use / tool_result
  - 自己 retry / backoff
  - 自己管 max_steps / 死循环检测
  - 自己设计 hooks(没的话就硬编码)
  - 自己写 file ops、bash 这些常用 tool
  → 100-1000 行,典型项目几天到一周

用 Agent SDK 造 agent:
  - import query, for await msg of query({...})
  - allowedTools: ["Read", "Edit", "Bash"]
  - hooks: { PreToolUse: ... }
  → 30 行,几小时跑通

关键认知:Agent SDK 替你 own 了 loop。loop 控制、permission、context 管理这些 harness 工程的核心决策,在你用 Agent SDK 时已经被 SDK 帮你决定了。

这就引出了关键的术语区分(对应 #11 Harness 概念边界):

使用 Agent SDK 造产品  = SDK user(你做的是应用层)
扩展 Agent SDK 的能力 = harness extension(你在边缘)
造 SDK 本身 / 自写 harness = harness 工程师(你 own loop)

// TypeScript - Agent SDK 实际使用
import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const msg of query({
  prompt: "Refactor src/auth.ts to use async/await throughout",
  options: {
    allowedTools: ["Read", "Edit", "Bash"],   // 限制可用工具
    permissionMode: "ask",                     // 询问每个 write
    hooks: {
      PreToolUse: [{
        matcher: "Edit",
        hooks: [async ({ tool_input }) => {
          console.log("准备改:", tool_input.path);
          return { decision: "approve" };
        }]
      }]
    }
  }
})) {
  console.log(msg);  // 流式输出 thinking、tool_use、tool_result、text
}

// 等价的 Client SDK 实现:你要手写 agent loop、retry、
// stop_reason 解析、tool 执行、permission ask 弹窗——约 300 行