官方 Claude Agent SDK：打造诚实、可审计的个人 AI 助理（2026）
Anthropic 的 Claude Agent SDK 让你在自己的 Python 或 TypeScript 应用中嵌入与 Claude Code 相同的工具循环。零基础建议：先只读，加上强调诚实的 system_prompt（缺数据就说不知道、不编造路径或命令输出），待审计日志无误后再逐步放宽 allowed_tools。
延伸阅读：Claude Code 经 SSH 使用、Cursor Rules 与 Skills 对比、Opus 4.8 Agent 基准测试。
为何从官方 SDK 起步
封装层常隐藏实际运行的工具及外发数据。SDK 在 code.claude.com 上明确文档化 Read、Edit、Bash、permissions、hooks 与 sessions。
云端 Mac 对 7×24 调度可选；搭建首个受控助手，笔记本即可。
SDK 结构概览
| 层级 | 作用 | 你可配置 |
|---|---|---|
query() | Agent 循环（计划 → 工具 → 观察） | agent.py |
| Tools | 文件、Shell、搜索、网页 | allowed_tools |
| Permissions | 批准 / 拒绝 / 提示 | permission_mode |
| Policy | 诚实、范围 | system_prompt、CLAUDE.md |
| Audit | 记录工具使用 | hooks |
自 2026 年 6 月 15 日 起，订阅计划通过独立额度池计量 Agent SDK——请为无人值守循环预留预算。
八步受控操作手册
步骤 1 — 前置条件
python3 --version # 3.10+
pip install claude-agent-sdk步骤 2–3 — 项目与安装
mkdir my-guarded-agent && cd my-guarded-agent
python3 -m venv .venv && source .venv/bin/activate
pip install claude-agent-sdk步骤 4 — API 密钥
# .env (gitignore this file)
ANTHROPIC_API_KEY=sk-ant-...步骤 5–6 — 诚实提示 + 只读运行
from claude_agent_sdk import query, ClaudeAgentOptions
HONEST = """Say "I don't know" when data is missing.
Never invent paths or command output."""
options = ClaudeAgentOptions(
allowed_tools=["Read", "Glob", "Grep"],
permission_mode="dontAsk",
system_prompt=HONEST,
)运行：python3 agent.py — 见 quickstart。
步骤 7–8 — 审计 hook，再开放编辑
在启用 Edit 且设置 permission_mode="acceptEdits" 之前，先为 PostToolUse 添加写入 audit.log 的 hooks。可选：AskUserQuestion 用于澄清。
故障排除
找不到 API 密钥
修复：在同一 Shell 中 export ANTHROPIC_API_KEY；切勿提交 .env。
pip: No matching distribution
修复：使用 Python 3.10+；重建 .venv。
thinking.type.enabled not supported
修复：将 Agent SDK 升级至 v0.2.111+ 以支持 Opus 4.7+（[quickstart](https://code.claude.com/docs/en/agent-sdk/quickstart)）。
出现意外文件编辑
修复：用 git 回滚；在 hooks 证明安全前，恢复 dontAsk 与只读工具。
常见问题
query() 与 ClaudeAgentOptions 使用。dontAsk，且仅允许 Read、Glob、Grep。