使用 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 儲存庫或文件連結。如果您需要的繫結未在技能檔案中明確記錄,請在編寫程式碼之前,從 shared/live-sources.md 使用 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 變化 — 您的訓練先驗知識可能已過時
2025–2026 年間,數個常見的 Claude API 形式已發生變化。如果您從訓練中回憶起某種模式,請在編寫程式碼之前,根據此技能中的 {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 | web_search_20260209、web_fetch_20260209(動態過濾)適用於 Opus 5/4.8/4.7/4.6、Sonnet 5 和 Sonnet 4.6。較舊的模型保留基本變體;在 Vertex AI 上僅提供基本 web_search_20250305(Vertex 上無網路擷取功能)— 請參閱下方伺服器工具的 QR 碼。 |
| PHP 參數名稱 | 網路傳輸線的 snake_case 名稱作為具名引數 (max_tokens) | 頂層的具名引數為 camelCase (maxTokens)。巢狀陣列鍵因功能而異(例如 'taskBudget'、'skillID'、'mcp_server_name')— 請從文件範例中複製確切鍵值;請勿大量轉換。 |
| 托管代理的憑證 | 透過自訂工具將機密保留在主機端(Vault 推出前唯一的選項) | Vault environment_variable 憑證 — 由 Anthropic 儲存,在出口時替換,沙箱中永遠不可見(shared/managed-agents-tools.md → Vaults)。主機端自訂工具仍為自托管沙箱的備用方案。 |
此技能中的 {lang}/ 檔案對於回憶模式具有權威性。
子命令
如果此提示底部的使用者請求是純粹的子命令字串(無敘述句),請搜尋此文件中的所有 子命令 表格 — 包括下方附加章節中的表格 — 並直接遵循相符的動作欄。這讓使用者可以透過 /claude-api <子命令> 來觸發特定流程。如果文件中沒有相符的表格,則將請求視為一般敘述句。
| 子命令 | 動作 |
|---|---|
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 和托管代理 — Python(@beta_tool 裝飾器)、TypeScript(betaZodTool + Zod)、Java(註解類別)、Go(toolrunner 套件中的 BetaToolRunner)、Ruby(BaseTool + tool_runner)、C#(BetaToolRunner + 原始 JSON schema)、PHP(BetaRunnableTool + toolRunner());程式碼入口點位在下方工具使用模式的快速參考中。cURL 是原始 HTTP(無 SDK 功能)並支援托管代理。
托管代理程式碼範例:請參閱下方
## 托管代理章節的閱讀指南。
我應該使用哪種表面?
從簡單開始。 預設使用能滿足您需求的最簡單層級。單一 API 呼叫和工作流程涵蓋大多數使用案例 — 只有當任務真正需要開放式、模型驅動的探索時,才使用代理。「最簡單」意味著您擁有的程式碼最少:對於托管、排程或具有記憶體的代理,托管代理通常是最簡單的選項(無迴圈程式碼、無狀態檔案、無排程器),即使它是一個更大的平台。
| 使用案例 | 層級 | 建議表面 | 原因 |
|---|---|---|---|
| 分類、摘要、提取、問答 | 單一 LLM 呼叫 | Claude API | 一個請求,一個回應 |
| 批次處理或嵌入 | 單一 LLM 呼叫 | Claude API | 專用端點 |
| 以程式碼控制邏輯的多步驟管道 | 工作流程 | Claude API + 工具使用 | 由您編排迴圈 |
| 使用您自己工具的自訂代理 | 代理 | Claude API + 工具使用 | 最大靈活性 |
| 伺服器管理的具狀態代理(含工作區) | 代理 | 托管代理 | Anthropic 執行迴圈並托管工具執行的沙箱 |
| 持久化、版本化的代理配置 | 代理 | 托管代理 | 代理是儲存的物件;工作階段鎖定到某一版本 |
| 長時間運行的多輪代理(含檔案掛載) | 代理 | 托管代理 | 每個工作階段的容器、SSE 事件串流、Skills + MCP |
| 按排程(cron、「每晚」)運行的代理 | 代理 | 托管代理 — 排程部署 | 部署會自主啟動工作階段;無需客戶端排程器 |
注意: 當您希望 Anthropic 執行代理迴圈並托管工具執行的容器時,托管代理是正確的選擇 — 檔案操作、bash、程式碼執行都在每個工作階段的工作區中運行。如果您希望自行托管運算資源或運行自己的自訂工具執行時期,Claude API + 工具使用是正確的選擇 — 使用 Tool Runner 進行代理迴圈 — 其每輪鉤子仍然提供核准閘道、記錄、錯誤攔截和條件執行(請參閱
shared/tool-use-concepts.md)— 或者當您希望完全自行擁有整個迴圈時,使用手動迴圈。
雲端供應商存取。 AWS 上的 Claude 平台由 Anthropic 運營,提供當天的 API 一致性 — 客戶端設定請參閱
shared/claude-platform-on-aws.md。有關 AWS 上的 Claude 平台、Amazon Bedrock、Google Vertex AI 和 Microsoft Foundry 每個功能的可用性,請參閱shared/platform-availability.md— 該表格是此技能中的單一事實來源;請勿從任何其他地方推斷可用性。
建立代理:四種方法
一旦您確定確實需要一個代理(開放式、模型驅動的工具使用),有四種不同的建置方式。兩個獨立問題區分了它們:誰提供框架(代理迴圈 + 上下文管理)以及誰提供部署(代理運行的基礎設施)。Tool Runner 和 Claude Agent SDK 都僅提供框架 — 您仍然自行托管和部署它們 — 這就是為什麼它們容易混淆。托管代理是唯一一個同時提供框架 和 托管部署的選項;手動迴圈則兩者都不提供。
| # | 方法 | 您撰寫的部分 | 框架與部署 | 可用工具 | 使用時機 |
|---|---|---|---|---|---|
| 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 | 托管代理(REST,Beta) | 代理配置 + 您的工具結果 | Anthropic 提供框架並托管每個工作階段的沙箱(框架 + 部署) | Anthropic 托管的沙箱(bash、檔案、程式碼執行)+ Skills/MCP + 您的工具 | 您希望 Anthropic 執行迴圈並托管每個工作階段的工作區;持久化/版本化的配置;長時間運行的會話 |
| 4 | Claude Agent SDK — 獨立產品(claude-agent-sdk / @anthropic-ai/claude-agent-sdk) | 提示 + 選項 | SDK 提供 Claude Code 框架 + 內建工具(僅框架);您托管 | 內建的 Read/Write/Edit/Bash/Glob/Grep/WebSearch/WebFetch + MCP + 子代理 | 您希望在自有基礎設施上執行一個功能齊全的編碼/檔案系統代理 |
框架/部署的區別是關鍵的思維模型:選項 1、2 和 4 都將部署留給您;只有選項 3 增加了托管部署。選項 1–3 是此技能產生的內容;選項 4 是一個不同的函式庫,有其自己的文件 — 請參閱下方的區別說明。
Tool Runner ≠ Claude Agent SDK。 這些名稱聽起來相似,但屬於不同的套件:
- Tool Runner 是一般 Anthropic API SDK(
anthropic/@anthropic-ai/sdk)的一部分,透過client.beta.messages.tool_runner存取。它會自動…