Agent SDK 能力矩阵
Agent SDK 的权限评估、Hooks、MCP、SessionStore、成本追踪、OpenTelemetry、安全部署和 5m/1h 缓存策略。
Agent SDK 不是“把 prompt 发给模型”的薄 wrapper。它启动 Claude Code agent loop,让模型、工具、权限、Hooks、MCP、会话和 telemetry 一起工作。这个页面把官方 SDK 细分文档整理成生产选型矩阵。
运行时 API 设计,包括 custom tools、system prompt、streaming、structured output、用户审批和 SDK slash commands,见 Agent SDK 运行时模式。
如果你只需要一个人在终端里改项目,用 CLI。只有当你要把 agent 嵌进产品、CI、后台任务或多租户服务时,才需要 SDK 的权限、会话、观测和隔离设计。
#能力全景
| 能力 | 解决什么问题 | 生产注意 |
|---|---|---|
| Permission modes | 控制工具能否自动执行 | allowedTools 是预批准,不是限制工具全集 |
canUseTool | 在运行时向用户或业务系统要审批 | 可能被 allow、mode 或 deny 规则绕过,要理解评估顺序 |
| Hooks | 在工具调用、session 生命周期、停止点拦截 | 强制审计或阻断敏感动作时优先用 PreToolUse |
| MCP | 给 agent 接内部 API、数据库、浏览器、SaaS | 大型 MCP 要用 tool search,并控制认证和工具输出大小 |
| SessionStore | 跨主机恢复 transcript | 只同步 transcript,不替代工作目录、CLAUDE.md 或 checkpoint blobs |
| Cost tracking | 记录 token、model usage、估算成本 | SDK 成本是客户端估算,不能直接作为最终账单 |
| OpenTelemetry | 导出 metrics、logs、traces | SDK stdout 是消息通道,不要用 console exporter |
| Secure deployment | 隔离文件、网络、凭据和租户 | 多租户必须单独 cwd、config dir、env 和 egress |
#权限评估顺序
SDK 工具请求按这个顺序处理:
| 顺序 | 层 | 结果 |
|---|---|---|
| 1 | Hooks | 可以直接 deny,也可以记录或改写输入 |
| 2 | Deny rules | 命中即阻断,Bash(rm *) 这类 scoped deny 在 bypass 下也生效 |
| 3 | Ask rules | 命中后交给 canUseTool,需要用户或业务审批 |
| 4 | Permission mode | bypassPermissions、acceptEdits、plan、dontAsk 等全局策略 |
| 5 | Allow rules | 命中则自动批准 |
| 6 | canUseTool | 前面都没解决才调用 |
常见误区:
| 配置 | 实际行为 |
|---|---|
allowedTools: ["Read"] + bypassPermissions | Read 被 allow,其他工具落到 bypass,仍可能全部通过 |
disallowedTools: ["Bash"] | Bash 工具定义被移除,Claude 看不到 Bash |
disallowedTools: ["Bash(rm *)"] | Bash 仍可见,但匹配命令会被阻断 |
dontAsk + 少量 allowed tools | 最适合锁定只读或窄任务,未列出的动作直接拒绝 |
只靠 canUseTool | 如果前面 allow 或 mode 已批准,callback 可能不会被调用 |
#Hooks 用法
Hooks 适合把安全、审计和业务规则放到模型动作之前或之后。
| Hook 场景 | 建议 |
|---|---|
| 阻断危险命令 | PreToolUse 检查 Bash 输入,命中后 deny |
| 审计所有工具 | PreToolUse 和 PostToolUse 记录 tool name、session、agent、结果摘要 |
| 格式化或验证文件 | PostToolUse 在 Edit/Write 后运行 formatter 或 test |
| 注入短期凭据 | 在工具调用前由外部代理注入,不要把长期 secret 放进 prompt |
| 任务结束通知 | Stop 或运行结束事件发消息、webhook、ticket update |
Hook 返回 allow 不会跳过后续 deny/ask/permission rules。需要“每次都必须检查”的规则,放 PreToolUse,不要只放 canUseTool。
#MCP 接入
MCP 让 SDK agent 使用外部工具。生产环境要按工具数量、认证方式和输出大小规划。
| 设计点 | 建议 |
|---|---|
| Transport | 本地工具用 stdio,远程服务用 HTTP/SSE/WebSocket |
| Auth | OAuth 或短期 token,避免在 prompt 或仓库里暴露 secret |
| Tool search | 工具很多时开启,不要把所有 schema upfront 塞进 prompt |
| Output size | 限制大结果,给分页或摘要接口 |
| Human approval | 对高风险 MCP tool 设置 requires-user-interaction 或 ask rule |
| Gateway 场景 | 确认网关支持 tool search/deferred tools,否则缓存容易 miss |
MCP 工具输出进入 conversation 后会成为后续上下文的一部分。长日志、全表查询、完整网页 HTML 都会抬高下一轮成本。
#SessionStore
默认 transcript 在本机 ~/.claude/projects/。SessionStore 可以把 transcript mirror 到 S3、Redis、数据库或自研后端,让任意 worker 恢复同一个 session。
| 方法 | 是否必需 | 用途 |
|---|---|---|
append | 必需 | 本地写入 transcript 后,把 entries 追加到外部 store |
load | 必需 | resume 前加载历史 |
listSessions | 可选 | 支持列出或 continue 最近 session |
delete | 可选 | 删除 session,append-only 后端可实现 no-op |
listSubkeys | 可选 | 恢复 subagent transcript |
边界:
| 不由 SessionStore 接管 | 需要你自己处理 |
|---|---|
| 工作目录文件 | 用持久卷、对象存储或每任务目录 |
CLAUDE.md 和 auto memory | 独立隔离或禁用 |
| checkpoint blob | 如果要跨主机 rewind,需要单独持久化 |
| MCP server 状态 | 由 MCP server 或外部服务管理 |
监控 mirror_error。如果外部 store append 失败,agent 可能继续运行,但恢复能力已经不完整。
#成本追踪
SDK 会在 message stream 中暴露 per-step usage、per-model usage 和 query 结束时的总估算。
| 字段/概念 | 用途 |
|---|---|
| assistant message usage | 观察每一步 input/output token |
result total_cost_usd | 单次 query() 的客户端估算成本 |
result model_usage | 多模型或 fallback 时分模型统计 |
cache_creation_input_tokens | 本轮写入缓存的输入 |
cache_read_input_tokens | 本轮读取缓存的输入 |
注意:并行工具调用可能生成多个 assistant message,但它们共享同一个 message ID 和 usage。做 per-step 统计时要按 ID 去重。
SDK 的成本字段是本地估算,会受 SDK 版本、模型 ID 识别和价格表更新影响。用于开发观测和预算预警可以,不要直接作为对客户扣费或财务结算的唯一来源。
#OpenTelemetry
生产环境建议开启 OTLP,把 agent 运行过程接入现有 observability。
CLAUDE_CODE_ENABLE_TELEMETRY=1
CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1
OTEL_TRACES_EXPORTER=otlp
OTEL_METRICS_EXPORTER=otlp
OTEL_LOGS_EXPORTER=otlp
OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
OTEL_EXPORTER_OTLP_ENDPOINT=http://collector.example.com:4318| Signal | 适合看什么 |
|---|---|
| Metrics | session 数、token、cost、tool decision、lines changed |
| Log events | prompt/API/tool/error 事件摘要 |
| Traces | model request、tool call、hook、agent step 延迟链路 |
SDK 通过 stdout/stderr 和子进程通信。不要把 OTEL exporter 设置成 console,否则 telemetry 输出会污染 SDK 消息通道。
#安全部署
Agent 可以读文件、跑命令、访问网络和调用外部服务。安全设计按“最小权限 + 隔离 + 多层防御”处理。
| 资源 | 控制方式 |
|---|---|
| Filesystem | 每租户/每任务单独 cwd,必要时只读挂载 |
| Network | 出站 allowlist、代理、无网 sandbox |
| Credentials | 由外部代理注入短期凭据,不要直接给长期 key |
| Settings | 多租户服务设置 settingSources: [] 并显式给 options |
| Config dir | 每租户 CLAUDE_CONFIG_DIR |
| Auto memory | 共享环境禁用 CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 |
| Process | Docker、sandbox-runtime、gVisor、Firecracker 或 CI 隔离 |
如果 agent 处理用户上传文件、网页内容、issue 评论或仓库 README,要把 prompt injection 当作正常威胁模型处理:网络和凭据边界比“相信模型不会照做”更可靠。
#5m / 1h 缓存策略
| SDK 场景 | 缓存建议 |
|---|---|
单次 query() | 一次任务内部多 step 会自然复用前缀,不要中途切模型/effort |
多次 query() + resume | 同一 session ID、同模型、同 effort 更容易命中 |
| 多 worker + SessionStore | transcript 可恢复,但 provider-side cache 不会跨 TTL 或跨 cache key 保证存在 |
| API key / Passion8 / Bedrock / Vertex | 默认按 5 分钟 TTL 设计交互节奏 |
| Claude subscription | 计划内通常可按 1 小时 TTL 设计长间隔 |
| MCP 工具多 | tool search 稳定前缀,避免每轮重发完整 schema |
| Permission/settings 变更 | 工具集合或 system 前缀变化后,下一轮可能重建缓存 |
| 子代理 | 每个子代理独立上下文和缓存,成本按 agent 数扩张 |
在 SDK 服务里,把 /usage 思路变成 telemetry 和业务指标:按 tenant、session、agent、model、tool、cache read/write 维度记录。
#官方参考
Support / 支持
Need help? / 需要帮助？
接入、计费与模型异常可邮件联系；服务可用性以状态页为准。
For setup, billing, or model issues, email us. Check the status page for uptime.
也可使用右下角微信 / QQ 客服 · WeChat / QQ support is available at the bottom right
