使用Claude构建LLM驱动应用
此技能帮助你使用Claude构建LLM驱动应用。根据你的需求选择合适的表面,检测项目语言,然后阅读相关的语言特定文档。
开始之前
扫描目标文件(如果没有目标文件,则扫描提示和项目)中是否存在非Anthropic提供商标记——import openai、from openai、langchain_openai、OpenAI(、gpt-4、gpt-5、文件名称如agent-openai.py或*-generic.py,或任何明确指示保持代码提供商中立的指令。如果发现任何此类标记,停止并告知用户此技能生成Claude/Anthropic SDK代码;询问他们是否要将文件切换到Claude,或希望使用非Claude实现。不要使用Anthropic SDK调用编辑非Anthropic文件。
输出要求
当用户要求你添加、修改或实现Claude功能时,你的代码必须通过以下方式之一调用Claude:
- 项目语言对应的官方Anthropic SDK(
anthropic、@anthropic-ai/sdk、com.anthropic.*等)。只要项目支持相应的SDK,这就是默认选择。 - 原始HTTP(
curl、requests、fetch、httpx等)——仅当用户明确要求cURL/REST/原始HTTP、项目是shell/cURL项目,或语言没有官方SDK时使用。
切勿混合使用两者——不要仅仅因为感觉更轻量而使用Python或TypeScript项目中的requests/fetch。切勿回退到与OpenAI兼容的shim。
切勿猜测SDK用法。 函数名称、类名称、命名空间、方法签名和导入路径必须来自明确的文档——要么来自此技能中的{lang}/文件,要么来自shared/live-sources.md中列出的官方SDK仓库或文档链接。如果你需要的绑定没有在技能文件中明确记录,请在编写代码前WebFetch相关SDK仓库。不要从cURL形状或另一种语言的SDK推断Ruby/Java/Go/PHP/C# API。
如果WebFetch或仓库访问失败(网络受限、超时、克隆被阻止):不要继续重试——根据{lang}/文件中的模式和命名空间/包表编写代码,运行编译器或解释器,然后根据错误输出进行迭代。对于静态类型SDK(C#、Java、Go),针对本地错误的编译-修复循环比受阻的网络研究能更快地达到可工作代码。
默认设置
除非用户另有要求:
对于Claude模型版本,请使用Claude Opus 5,你可以通过确切的模型字符串claude-opus-5访问。对于任何稍微复杂的情况,请默认使用自适应思考(thinking: {type: "adaptive"})。最后,对于可能涉及长输入、长输出或高max_tokens的任何请求,请默认使用流式处理——它可以防止触发请求超时。如果你不需要处理单个流事件,请使用SDK的.get_final_message() / .finalMessage()辅助方法获取完整响应。
⚠️ API漂移——你的训练记忆可能已过时
几个常见的Claude API形状在2025–2026年间发生了变化。如果你回忆起训练时的模式,请在编写代码前根据此技能中的{lang}/文件进行验证——下表是最频繁的漂移点:
| 领域 | 过时的记忆 | 当前API |
|---|---|---|
| 扩展思考 | thinking: {type: "enabled", budget_tokens: N} | 在Claude 4.6+模型中:thinking: {type: "adaptive"}。budget_tokens在Opus 4.6 / Sonnet 4.6上已弃用,并且在Fable 5 / Sonnet 5 / Opus 5 / 4.8 / 4.7上会被以400错误拒绝。4.6之前的模型仍使用budget_tokens。 |
| 网络搜索/网络获取工具类型 | web_search_20250305、web_fetch_20250910 | 在Opus 5/4.8/4.7/4.6、Sonnet 5和Sonnet 4.6上:web_search_20260209、web_fetch_20260209(动态过滤)。较旧模型保留基本变体;在Vertex AI上仅基本web_search_20250305可用(网络获取在Vertex上不可用)——请参阅下面的服务器工具快速参考。 |
| PHP参数名称 | 蛇形命名法(snake_case)的线序名称作为命名参数(max_tokens) | 顶级命名参数是驼峰命名法(camelCase)(maxTokens)。嵌套数组键因功能而异(例如'taskBudget'、'skillID'、'mcp_server_name')——从记录的例子中复制确切的键;不要批量转换。 |
| Managed Agents凭据 | 通过自定义工具将秘密保存在主机端(在保险库发布之前是唯一选项) | Vault environment_variable凭据——由Anthropic存储,在出口时替换,在沙箱中永远不可见(shared/managed-agents-tools.md → Vaults)。主机端自定义工具仍然是自托管沙箱的回退方案。 |
此技能中的{lang}/文件比回忆的模式更具权威性。
子命令
如果此提示底部的用户请求是纯子命令字符串(无散文),请搜索此文档中的每个子命令表——包括下面附加部分中的任何表——并直接遵循匹配的操作列。这允许用户通过/claude-api <subcommand>调用特定流程。如果文档中没有表匹配,则将请求视为普通散文。
| 子命令 | 操作 |
|---|---|
migrate | 将现有Claude API代码迁移到较新模型。**立即阅读shared/model-migration.md**并按顺序执行:步骤0(确认范围——在任何编辑前询问哪些文件/目录),步骤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/读取
-
如果检测到多种语言(例如,同时有Python和TypeScript文件):
- 检查用户的当前文件或问题与哪种语言相关
- 如果仍然不明确,则询问:“我检测到Python和TypeScript文件。您使用哪种语言进行Claude API集成?”
-
如果无法推断语言(空项目、无源文件或不支持的语言):
- 使用AskUserQuestion并提供选项:Python、TypeScript、Java、Go、Ruby、cURL/原始HTTP、C#、PHP
- 如果AskUserQuestion不可用,则默认使用Python示例并注明:“显示Python示例。如果您需要其他语言,请告知。”
-
如果检测到不支持的语言(Rust、Swift、C++、Elixir等):
- 建议从
curl/使用cURL/原始HTTP示例,并注明可能存在社区SDK - 提供显示Python或TypeScript示例作为参考实现的选项
- 建议从
-
如果用户需要cURL/原始HTTP示例,则从
curl/读取。
语言特定功能支持
上述每个SDK语言都支持beta版Tool Runner和Managed Agents(beta)——Python(@beta_tool装饰器)、TypeScript(betaZodTool + Zod)、Java(注解类)、Go(toolrunner包中的BetaToolRunner)、Ruby(BaseTool + tool_runner)、C#(BetaToolRunner + 原始JSON模式)、PHP(BetaRunnableTool + toolRunner());代码入口点在下面的工具使用模式快速参考中。cURL是原始HTTP(无SDK功能)并支持Managed Agents。
Managed Agents代码示例:请参见下面
## Managed Agents(Beta)部分的阅读指南。
我应该使用哪个表面?
从简单的开始。 默认使用最能满足你需求的最简单层级。单个API调用和工作流处理大多数用例——只有当任务真正需要开放式的、模型驱动的探索时才使用代理。“最简单”意味着你拥有的代码最少:对于托管式、计划式或内存支持的代理,Managed Agents通常是最简单的选项(无需循环代码、状态文件或调度器),即使它是一个更大的平台。
| 用例 | 层级 | 推荐表面 | 原因 |
|---|---|---|---|
| 分类、摘要、提取、问答 | 单个LLM调用 | Claude API | 一次请求,一次响应 |
| 批处理或嵌入 | 单个LLM调用 | Claude API | 专用端点 |
| 由代码控制逻辑的多步骤管道 | 工作流 | Claude API + 工具使用 | 你编排循环 |
| 使用你自己的工具的自定义代理 | 代理 | Claude API + 工具使用 | 最大灵活性 |
| 由服务器管理的、带有工作区的有状态代理 | 代理 | Managed Agents | Anthropic运行循环并托管工具执行沙箱 |
| 持久化、版本化的代理配置 | 代理 | Managed Agents | 代理是存储的对象;会话固定到一个版本 |
| 带有文件挂载的长时间运行的多轮代理 | 代理 | Managed Agents | 每会话容器、SSE事件流、Skills + MCP |
| 按计划运行的代理(cron、“每晚”) | 代理 | Managed Agents——计划部署 | 部署自主启动会话;无需客户端调度器 |
注意: 当你希望Anthropic运行代理循环并托管工具执行的容器时,Managed Agents是正确的选择——文件操作、bash、代码执行都在每会话工作区中运行。如果你想自己托管计算或运行自己的自定义工具运行时,Claude API + 工具使用是正确的选择——使用tool runner进行代理循环——其每轮钩子仍然提供审批门、日志记录、错误拦截和条件执行(请参阅
shared/tool-use-concepts.md)——或者当你希望完全自己拥有整个循环时使用手动循环。
云提供商访问。 AWS上的Claude Platform由Anthropic运营,具有同日API一致性——客户端设置请参阅
shared/claude-platform-on-aws.md。有关AWS上的Claude Platform、Amazon Bedrock、Google Vertex AI和Microsoft Foundry上各功能的可用性,请参阅shared/platform-availability.md——该表是此技能中的唯一事实来源;不要从任何其他地方推断可用性。
构建代理:四种方法
一旦你确定确实需要代理(开放式的、模型驱动的工具使用),有四种不同的构建方法。两个独立的问题将它们区分开来:谁提供框架(代理循环 + 上下文管理)和谁提供部署(代理运行的基础设施)。Tool Runner和Claude Agent SDK都仅提供框架——你仍然自己托管和部署它们——这就是它们容易被混淆的原因。Managed Agents (CMA) 是唯一同时提供框架和托管部署的选项;手动循环则两者都不提供。
| # | 方法 | 你编写 | 框架和部署 | 可用工具 | 何时使用 |
|---|---|---|---|---|---|
| 1 | Claude API——手动循环 | 你自己编写while stop_reason == "tool_use"循环 | 你构建框架;你托管 | 仅你定义的工具 | 你想拥有整个循环——没有beta依赖,或者Tool Runner的每轮钩子不适合的控制流 |
| 2 | Claude API——Tool Runner(client.beta.messages.tool_runner + @beta_tool / betaZodTool) | 仅工具函数 | SDK提供循环(仅框架);你托管 | 仅你定义的工具 | 自定义工具代理,无需手写循环(大多数情况)。每轮钩子仍然提供审批门、错误拦截、结果修改(例如cache_control)、重试、流式处理和压缩 |
| 3 | Managed Agents(REST,beta) | 代理配置 + 你的工具结果 | Anthropic提供框架并托管每会话沙箱(框架+部署) | Anthropic托管的沙箱(bash、文件、代码执行)+ Skills/MCP + 你的工具 | 你想让Anthropic运行循环并托管每会话工作区;持久化/版本化配置;长时间运行会话 |
| 4 | Claude Agent SDK——单独产品(claude-agent-sdk / @anthropic-ai/claude-agent-sdk) | 提示 + 选项 | SDK提供Claude Code框架 + 内置工具(仅框架);你托管 | 内置读/写/编辑/Bash/Glob/Grep/WebSearch/WebFetch + MCP + 子代理 | 你想要一个在你自己的基础设施上运行的全功能编码/文件系统代理 |
框架/部署拆分是关键思维模型:选项1、2和4都将部署留给你;只有选项3(CMA)增加了托管部署。选项1–3是此技能生成的内容;选项4是一个不同的库,有其自己的文档——请参阅下面的区分说明。
Tool Runner ≠ Claude Agent SDK。 这些听起来相似但属于不同的包:
- Tool Runner是常规Anthropic API SDK(
anthropic/@anthropic-ai/sdk)的一部分,通过client.beta.messages.tool_runner访问。它会自动[由于长度限制被截断]