claude-api

使用 Claude 构建大模型应用

本 Skill 旨在协助你基于 Claude 构建大模型应用。请根据你的业务需求选择合适的接口层 (Surface)，自动识别项目开发语言，并阅读对应的语言文档。

开工前检查

请先扫描目标文件（若没有目标文件，则扫描提示词和整个项目），检查是否存在非 Anthropic 供应商的特征标识 —— 例如 import openai、from openai、langchain_openai、OpenAI(、gpt-4、gpt-5、诸如 agent-openai.py 或 *-generic.py 的文件名，或者要求保持代码供应商中立的明确指示。一旦发现此类标识，请立即停止后续操作并告知用户：本 Skill 专用于生成 Claude/Anthropic SDK 代码；询问他们是希望将文件改用 Claude 实现，还是需要非 Claude 的实现方案。切勿在非 Anthropic 项目文件中硬塞 Anthropic SDK 调用代码。

代码输出要求

当用户要求你添加、修改或实现某项 Claude 功能时，你的代码必须通过以下两种方式之一来调用 Claude：

1. 项目对应语言的 Anthropic 官方 SDK（如 anthropic、@anthropic-ai/sdk、com.anthropic.* 等）。只要项目语言有官方 SDK 支持，就必须优先默认使用该方式。
2. 原生 HTTP 请求（如 curl、requests、fetch、httpx 等）——仅当用户显式要求使用 cURL/REST/原生 HTTP、项目本身为 Shell/cURL 项目、或该语言尚无官方 SDK 时方可使用。

切勿混用这两种方式 —— 不要仅仅因为觉得更轻量，就在 Python 或 TypeScript 项目里使用 requests/fetch。严禁退而求其次去使用 OpenAI 兼容层 (shims)。

严禁凭空盲猜 SDK 用法。 函数名、类名、命名空间、方法签名以及导包路径必须严格基于官方文档 —— 可以是本 Skill 中的 {lang}/ 目录文件，或是 shared/live-sources.md 中列出的官方 SDK 仓库及文档链接。如果你所需的 API 绑定在 Skill 文件中未被明确记载，在编写代码前必须先从 shared/live-sources.md 抓取 (WebFetch) 相关的 SDK 仓库文档。切勿凭 cURL 格式或其它语言 SDK 的写法去套用 Ruby/Java/Go/PHP/C# 的 API。

默认设置

除非用户另有说明，否则请遵循以下标准：

对于 Claude 模型版本，请统一使用 Claude Opus 4.8（对应的模型字符串准确为 claude-opus-4-8）。凡是涉及一定复杂度的任务，默认开启自适应思考 (thinking: {type: "adaptive"})。最后，只要请求可能涉及长输入、长输出或较高的 max_tokens，请默认开启流式传输 (streaming) —— 这能有效防止请求超时。如果你不需要单独处理每个流式事件，直接调用 SDK 的 .get_final_message() / .finalMessage() 辅助方法即可获取完整响应。

---

子命令 (Subcommands)

如果本提示词底部的用户请求只是一个纯子命令字符串（不含常规自然语言文本），请检索本文档中所有的 Subcommands 表格（包含下文附带各章节中的表格），并直接执行匹配到的 Action 操作。用户可通过 /claude-api <subcommand> 触发指定的处理流程。若文档中的表格均无匹配项，则按普通自然语言文本处理。

子命令	操作 (Action)
migrate	将现有的 Claude API 代码迁移至新版模型。请立即阅读 shared/model-migration.md 并按顺序执行：步骤 0（确认作用域 —— 在进行任何修改前先询问哪些文件/目录需要修改）、步骤 1（对每个文件进行分类），然后阅读对应目标模型的 breaking-changes 破损性变更章节。不要概括指南内容 —— 直接按要求执行。如果用户未指定目标模型，请在询问作用域的同时，一并询问要迁移到哪个模型。

---

语言识别

在查阅代码示例之前，先确认用户使用的编程语言：

1. 检查项目文件推断项目语言：

   • *.py、requirements.txt、pyproject.toml、setup.py、Pipfile → Python —— 读取 python/ 目录
   • *.ts、*.tsx、package.json、tsconfig.json → TypeScript —— 读取 typescript/ 目录
   • *.js、*.jsx（且不存在 .ts 文件）→ TypeScript —— JS 使用相同的 SDK，读取 typescript/ 目录
   • *.java、pom.xml、build.gradle → Java —— 读取 java/ 目录
   • *.kt、*.kts、build.gradle.kts → Java —— Kotlin 使用 Java SDK，读取 java/ 目录
   • *.scala、build.sbt → Java —— Scala 使用 Java SDK，读取 java/ 目录
   • *.go、go.mod → Go —— 读取 go/ 目录
   • *.rb、Gemfile → Ruby —— 读取 ruby/ 目录
   • *.cs、*.csproj → C# —— 读取 csharp/ 目录
   • *.php、composer.json → PHP —— 读取 php/ 目录

2. 如果检测到多种语言（例如同时存在 Python 和 TypeScript 文件）：

   • 检查用户当前打开的文件或提问涉及哪种语言
   • 若仍不明确，询问：“检测到项目同时存在 Python 和 TypeScript 文件。请问你的 Claude API 集成要使用哪种语言？”

3. 若无法推断语言（空项目、无源文件或使用了暂不支持的语言）：

   • 使用 AskUserQuestion 弹出选项：Python、TypeScript、Java、Go、Ruby、cURL/原生 HTTP、C#、PHP
   • 若 AskUserQuestion 不可用，则默认提供 Python 示例并提示：“已为你展示 Python 示例。如需其他语言示例，请随时告知。”

4. 如果检测到未原生支持的语言（如 Rust、Swift、C++、Elixir 等）：

   • 推荐参考 curl/ 目录下的 cURL/原生 HTTP 示例，并说明社区可能提供相应的 SDK
   • 主动询问是否展示 Python 或 TypeScript 示例作为参考实现

5. 如果用户需要 cURL/原生 HTTP 示例，请读取 curl/ 目录。

各语言特性支持度

语言	工具运行器 (Tool Runner)	Managed Agents	说明
Python	支持 (beta)	支持 (beta)	完全支持 —— 使用 @beta_tool 装饰器
TypeScript	支持 (beta)	支持 (beta)	完全支持 —— 使用 betaZodTool + Zod
Java	支持 (beta)	支持 (beta)	类注解方式支持 Beta 工具调用
Go	支持 (beta)	支持 (beta)	toolrunner 包中的 BetaToolRunner
Ruby	支持 (beta)	支持 (beta)	Beta 版提供 BaseTool + tool_runner
C#	支持 (beta)	支持 (beta)	BetaToolRunner + 原生 JSON schema
PHP	支持 (beta)	支持 (beta)	BetaRunnableTool + toolRunner()
cURL	不适用	支持 (beta)	原生 HTTP，无 SDK 级高级特性

Managed Agents 代码示例：Python、TypeScript、Go、Ruby、PHP、Java 和 cURL 均提供了专门的语言说明文档（{lang}/managed-agents/README.md、curl/managed-agents.md）。请查阅你所用语言的 README 以及通用概念文件 shared/managed-agents-*.md。Agent 是持久化对象 —— 一次创建，多次通过 ID 引用。 保存 agents.create 返回的 Agent ID，并在后续的每次 sessions.create 调用中传入该 ID；切勿在日常请求处理流程中重复调用 agents.create。Anthropic CLI (ant) 提供了基于版本控制的 YAML 文件批量创建 Agent 和环境的便捷手段 —— 详见 shared/anthropic-cli.md。如果你需要的 API 绑定未在 README 中列出，请直接 WebFetch 抓取 shared/live-sources.md 中的对应条目，严禁主观盲猜。C# 可通过 client.Beta.Agents 及相关命名空间体验 Beta 版 Managed Agents 支持。

---

我应该选择哪种接口层 (Surface)？

从简出发。 优先选用满足需求的最简层级。单次 API 调用或工作流足以覆盖绝大多数场景 —— 只有当任务确实需要开放式、由模型驱动的自主探索时，再引入 Agent。

使用场景	层级 (Tier)	推荐接口层 (Surface)	选型依据
文本分类、摘要总结、信息提取、智能问答	单次 LLM 调用	Claude API	一问一答，极简直接
批量数据处理或向量嵌入 (embeddings)	单次 LLM 调用	Claude API	使用专属 API 端点
代码驱动逻辑的多步骤流水线	工作流 (Workflow)	Claude API + tool use	由你的代码掌控循环流程
接入自定义工具的专属 Agent	Agent	Claude API + tool use	灵活性最大化
带有工作区且托管状态的服务端 Agent	Agent	Managed Agents	Anthropic 云端运行循环逻辑并托管工具执行沙箱
需要持久化与版本控制的 Agent 配置	Agent	Managed Agents	Agent 作为存储对象，Session 锁定固定版本
长时间运行、含文件挂载的多轮对话 Agent	Agent	Managed Agents	提供单 Session 隔离容器、SSE 事件流、Skills 和 MCP 支持

注意： 当你希望 Anthropic 帮你运行 Agent 循环并且托管工具执行的容器（文件操作、Bash、代码执行均运行在单 Session 的工作区中）时， Managed Agents 是最佳选择。如果你希望自己托管算力或运行自定义工具运行时，则应选择 Claude API + tool use —— 你可以使用 tool runner 进行自动循环处理，也可以手写循环来实现细粒度控制（如人工审批闸门、自定义日志、条件执行等）。

云厂商支持。 AWS 上的 Claude Platform 由 Anthropic 官方运营，具备同日 API 特性对齐能力 —— 除了自托管沙箱外（详见 shared/claude-platform-on-aws.md），Managed Agents 以及本 Skill 中的所有功能在此均受支持。而 Amazon Bedrock、Google Vertex AI 和 Microsoft Foundry 不支持 Managed Agents 或 Anthropic 服务端工具；在这些平台上请使用 Claude API + tool use。

选型决策树

你的应用有什么具体需求？

0. 使用哪家云服务商？
   ├── 官方 API 或 AWS 上的 Claude Platform → 继续向下评估（可使用全量功能）。
   └── Amazon Bedrock、Google Vertex AI 或 Microsoft Foundry → 使用 Claude API（若需 Agent 功能配合 tool use）；这些平台暂不支持 Managed Agents。

1. 单次 LLM 调用（分类、总结、提取、问答）
   └── Claude API —— 一请求一响应

2. 是否希望由 Anthropic 运行 Agent 循环并托管单 Session
   隔离容器来执行 Claude 工具（bash、文件操作、代码运行等）？
   └── 是 → Managed Agents —— 服务端托管 Session、持久化 Agent 配置、
       SSE 事件流、Skills + MCP、文件挂载。
       例如：“每个任务独立工作区带状态的 Coding Agent”、
             “向前端 UI 实时推流事件的长运行 Research Agent”、
             “跨多个 Session 共享持久化、版本化配置的 Agent”

3. 工作流（多步骤、由代码编排、搭配自定义工具）
   └── Claude API + tool use —— 由你掌控循环逻辑

4. 开放式 Agent（由模型自主决策路径、使用你自己的工具，