Claude api

本条目改写自 Anthropic 官方 claude-api 技能（Apache-2.0），保留其关键约束与默认值，面向 AI Agent 直接消费。

何时使用

满足以下任一条件时使用：

• 代码 import 了 anthropic / @anthropic-ai/sdk（或 com.anthropic.* 等官方 SDK）。
• 用户要求构建、调试或优化 Claude API / Anthropic SDK / Managed Agents 应用。
• 用户在文件中新增或调参某个 Claude 特性（缓存、思考、压缩 compaction、工具调用、批处理、文件、引用、记忆）或切换模型（Opus/Sonnet/Haiku）。
• 关于提示缓存 / 缓存命中率的问题。
• 在 Claude 模型版本间迁移代码（如 4.6→4.7→4.8，或替换已退役模型）。

不该用的边界（命中即停手并说明）：

• 文件 import 了 openai 或其它厂商 SDK，文件名形如 *-openai.py / *-generic.py，或代码刻意保持 provider-neutral——本技能只产出 Claude/Anthropic 代码，应先询问用户是否切换到 Claude，不要在非 Anthropic 文件里塞入 Anthropic 调用。
• 通用编程或 ML 问题，与 Claude API 无关。
• 切勿用 OpenAI 兼容垫片（compat shim）冒充 Claude 调用。

步骤

1. 入场扫描：检查目标文件/项目是否含非 Anthropic 标记（import openai、gpt-4/5、langchain_openai 等）。命中则停手询问，不要继续。
2. 语言识别：按项目文件推断语言并读取对应官方文档——*.py→Python，*.ts/.js→TypeScript（JS 共用 TS SDK），*.java/.kt/.scala→Java，*.go→Go，*.rb→Ruby，*.cs→C#，*.php→PHP。无法判断时询问用户，默认 Python。
3. 选对调用面（surface）：
   • 单次调用（分类/摘要/抽取/问答、批处理、嵌入）→ Claude API 单请求。
   • 多步、由代码编排的流水线，或自带工具的自定义 Agent → Claude API + 工具调用（自己控制循环）。
   • 需要 Anthropic 托管 Agent 循环并提供 per-session 容器沙箱 → Managed Agents（仅一方 1P，Bedrock/Vertex/Foundry 不支持，这些平台一律用 Claude API + 工具调用）。
   • 默认从最简层级起步，只有任务确需开放式、模型自主探索时才上 Agent。
4. 写出 SDK 代码：函数名、类名、方法签名、import 路径必须来自明确文档，不得凭 cURL 形状或别的语言 SDK 臆测；缺失绑定时先 WebFetch 官方仓库再写。
5. 默认就加提示缓存（本技能产出的应用应包含缓存）。
6. 自检缓存与产物：用 usage.cache_read_input_tokens 验证缓存是否命中。

指令（默认值，除非用户另有要求）

• 模型：默认用 Claude Opus 4.8，模型串严格为 claude-opus-4-8。只用文档表中的精确模型 ID，不要追加日期后缀（用 claude-sonnet-4-6，不是 claude-sonnet-4-6-20250514）。绝不为省成本擅自降级——那是用户的决定。需要更老的模型时查 shared/models.md，不要自己拼。
• 思考：Opus 4.8/4.7 仅支持自适应思考 thinking: {type: "adaptive"}；{type: "enabled", budget_tokens: N} 会返回 400（budget_tokens、temperature、top_p、top_k 均已移除）。Opus 4.6 / Sonnet 4.6 也用 adaptive，budget_tokens 已弃用。用户说"extended thinking / 思考预算 / budget_tokens"时，一律改用 Opus 4.8 + adaptive，不要切到老模型。
• Effort：output_config: {effort: "low"|"medium"|"high"|"max"}（在 output_config 内，非顶层），默认 high；max 仅 Opus 级；Opus 4.7/4.8 新增 "xhigh"，编码/智能体任务推荐。Sonnet 4.5 / Haiku 4.5 用 effort 会报错。
• 流式：任何可能长输入、长输出或高 max_tokens 的请求默认流式，避免 HTTP 超时；用 .get_final_message() / .finalMessage() 取完整响应。128K 输出必须流式。
• max_tokens：非流式默认 ~16000，流式默认 ~64000；分类等场景才下调到 ~256。不要 lowball，否则会截断需重试。
• 结构化输出：用 output_config: {format: {...}}（旧 output_format 已弃用）；推荐 client.messages.parse() 自动校验。
• Prefill 移除：4.6/4.7/4.8 家族（含 Sonnet 4.6）最后一条 assistant 消息 prefill 会 400，改用结构化输出或 system 指令控制格式。

示例

最小 Python 调用（注意 response.content 是内容块列表，需判 .type）：

import anthropic
client = anthropic.Anthropic()  # 读 ANTHROPIC_API_KEY

response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=16000,
    thinking={"type": "adaptive"},
    messages=[{"role": "user", "content": "法国的首都是哪里？"}],
)
for block in response.content:
    if block.type == "text":
        print(block.text)

提示缓存（前缀匹配，渲染序为 tools → system → messages，把稳定内容放前、易变内容放最后一个断点之后）：

response = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=16000,
    system=[{"type": "text", "text": "<大段共享系统提示>",
             "cache_control": {"type": "ephemeral"}}],
    messages=[{"role": "user", "content": "<每次都变的问题>"}],
)
print(response.usage.cache_read_input_tokens)  # 跨请求若恒为 0 说明有静默失效源

注意事项

• 提示缓存只认前缀：前缀里任一字节变化（system 里插 datetime.now()、未排序的 JSON、变动的工具集）都会让后续全部失效。系统提示要冻结，动态上下文放到靠后的 message；工具按 name 排序、对话中途不改 tools/model。最小可缓存前缀约 1024 token，每请求最多 4 个断点。
• 不要静默截断输入：内容超窗时告知用户并讨论分块/摘要，别偷偷砍。
• 解析工具入参：4.6/4.7/4.8 家族工具调用 input 的 JSON 转义可能不同，务必 json.loads() / JSON.parse()，禁止对序列化串做裸字符串匹配。
• Compaction（beta）：长会话开启服务端压缩需 beta 头 compact-2026-01-12；每轮把整个 response.content（不只是文本）追加回 messages，否则压缩状态会静默丢失。
• 迁移先确认范围：用户说"迁移我的代码库/升级到 X"但未指明文件/目录时，先问范围再动手。
• 不要重造 SDK：用 stream.finalMessage()、SDK 类型（Anthropic.MessageParam/Tool/Message）与具名异常类（RateLimitError 等），别自定义等价类型或字符串匹配错误。
• Managed Agents 流程固定：Agent 创建一次（model/system/tools 在 Agent 上）→ 每次运行起 Session；保存 agents.create 返回的 ID 复用，不要在请求路径里反复创建。
• 遇到"最新/当前"信息或本条未覆盖的特性，用 WebFetch 查官方实时文档（源清单见 shared/live-sources.md）。

互见

• 设计 Claude 的提示词与少样本结构：见 prompt-template-designer。
• 把检索上下文喂给 Claude 做 RAG：见 rag-pipeline-builder。
• 把 Claude 工具/智能体能力封装为 MCP server：见 mcp-builder。
• 审查生成的 SDK 调用代码、排查依赖：见 code-reviewer、dependency-auditor。