Agent SDK Agent 能力

Agent SDK 可以复用 Claude Code 的项目规则、skills、hooks、MCP、subagents、todo/task tracking 和 checkpointing。问题不在于“能不能用”,而在于哪些上下文会自动加载、哪些状态落在本地磁盘、哪些能力会增加缓存前缀和成本。

运行时 API 看 Agent SDK 运行时模式。部署拓扑和隔离看 Agent SDK 生产部署。

#覆盖的官方页面

#Agent loop

一次 SDK 任务大致是这个循环:

user prompt
  -> system/init
  -> assistant thinks and emits tool calls
  -> SDK/CLI checks hooks and permissions
  -> tools execute
  -> tool results enter conversation
  -> repeat until success, max turns, max budget, or error

常见 result subtype:

#Context 来源

#settingSources

settingSources 不控制这些:

多租户和 CI 默认不要加载用户环境:

options: {
  settingSources: [],
  env: {
    ...process.env,
    CLAUDE_CONFIG_DIR: "/srv/claude-config/job-123",
    CLAUDE_CODE_DISABLE_AUTO_MEMORY: "1"
  }
}

#Sessions

跨主机恢复只靠 session ID 不够。transcript 之外的工作目录、CLAUDE.md、checkpoint blob、工具缓存和文件产物都要单独规划。

#Skills

SDK 可以加载项目或用户 skills,也可以通过 plugins 传入。

Skill 内容通常不会全部进首轮上下文,但 description 会。大型 skill 多了仍会影响 cache 前缀。

#Subagents

Programmatic agent definition 比文件定义更适合 SDK 产品。

继承边界:

工具组合建议:

#Todo 和 Task tools

新版本更推荐 Task tools,而不是旧的 TodoWrite。

实时进度 UI 应监听 TaskCreate、TaskUpdate 和 TaskList 结果,不要只解析 assistant 文本。

#File checkpointing

SDK checkpointing 适合在 agent 写文件前后创建恢复点。

限制:

高风险批量编辑前,让 agent 先创建 checkpoint,再执行迁移。

#Hosting 限制

#缓存影响

#官方参考

• How the agent loop works
• Claude Code features in SDK
• Work with sessions
• Agent Skills in SDK
• Subagents in SDK
• Todo Lists
• File checkpointing
• Hosting the Agent SDK