第 3 章：Agent SDK 是运行时，不是包装

Agent SDK 把 Claude Code 的运行时拆成了可编程的积木：你不是在“调用模型”，而是在控制一个带工具、带上下文、带状态的循环。官方把它叫作 agent loop，本质上是“输入 → 决策 → 工具 → 结果 → 下一步”的持续过程。理解这点之后，你会把 SDK 当作一个小型运行时，而不是一个轻量封装。[19][20]

工程文章给出更具体的节奏：先收集上下文，再行动，再验证，然后进入下一轮。这种节奏让 agent 不再一次性输出“最终答案”，而是把执行拆成多次可观察的迭代。只要任务存在不确定性，这种循环比单次回答更可靠，也更容易被外部系统检查与纠错。[55]

在具体使用上，SDK 提供 Python 与 TypeScript 两条参考路径，同时还有新版接口预览。语法风格不同，但运行时结构一致：工具、权限、会话、子代理、hooks 都遵循同一套机制。[21][22][23]

“给模型一台电脑”是工程文章反复强调的设计理念。Claude Code 之所以有效，是因为它能读文件、跑脚本、搜索代码；Agent SDK 延续了这个理念，让 agent 通过文件系统与工具自己找上下文，而不是被动等待用户提供。这样做的结果是：上下文不再完全依赖提示词，而是由 agent 在执行中逐步构建。[55][19]

上下文检索在 SDK 里有两条路线：一条是基于文件系统的主动搜索，另一条是语义检索。工程文章建议优先让 agent 进行“主动搜索”，因为它更透明也更容易维护；只有在检索成本过高或需要更快召回时才引入语义检索。[55]

子代理是 SDK 里重要的扩展机制。主代理可以把探索任务分给多个子代理并行处理，每个子代理用独立的上下文窗口，再把压缩后的信息返还给主代理。这种结构能在不膨胀主上下文的前提下扩大探索范围。[25][55]

运行时的“可控”来自多层结构：技能让流程可复用，hooks 允许在工具调用前后插入检查，权限配置限定可用工具。它们的目标不是限制能力，而是让行为有边界、有日志、有可复现路径。[24][26][27]

SDK 还提供自定义工具与 MCP 集成，帮助把外部系统纳入统一的工具契约。这样你可以把内部 API、外部服务、甚至自建系统都接入同一套调用逻辑，避免在不同系统间重复写胶水代码。[28][29]

输出侧的工程能力同样关键。Structured outputs 强制结构化输出，方便程序解析；成本与 usage 追踪让你理解每次调用的资源消耗；文件 checkpointing 记录写入与编辑，便于回溯与恢复；流式与单次模式的差异则决定了交互体验与吞吐策略。[30][31][32][33]

会话管理与指令扩展是 SDK 的另一层能力。Sessions 让长任务可持续，slash commands 与 plugins 让常见动作可复用，system prompt 的调整则让团队可以把运行时行为固定为稳定策略。这些能力让 agent 从单次实验进入长期运营状态。[34][35][36][37]

验证环节不应被忽略。工程文章提出三类常见验证手段：规则检查、视觉校验、模型评审。它们的共同目标是让 agent 在输出前先自查一次，从而降低“看起来完成但其实没完成”的概率。[55]