claude-api

使用 Claude 建構 LLM 驅動的應用程式

本 Skill 能協助您使用 Claude 建構由 LLM 驅動的應用程式。請根據需求選擇合適的串接介面（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（Raw HTTP）（curl、requests、fetch、httpx 等）— 僅在使用者明確要求使用 cURL/REST/原生 HTTP、專案為 Shell/cURL 專案，或是該語言缺乏官方 SDK 時使用。

切勿混合使用兩者 — 不要只因為感覺比較輕量，就在 Python 或 TypeScript 專案中改用 requests/fetch。絕對不要退回使用相容於 OpenAI 介面的轉接層（shims）。

切勿憑空臆測 SDK 的用法。 函式名稱、類別名稱、命名空間、方法簽名（method signatures）與匯入路徑（import paths）必須完全出自明確的說明文件 — 可參考本 Skill 中的 {lang}/ 檔案，或是 shared/live-sources.md 中列出的官方 SDK 儲存庫與文件連結。若您需要的語言綁定（binding）未明確記錄在 Skill 檔案中，撰寫程式碼前請先透過 WebFetch 擷取 shared/live-sources.md 裡的對應 SDK 儲存庫資料。切勿從 cURL 的請求結構或其它語言的 SDK 盲目推斷 Ruby/Java/Go/PHP/C# 的 API。

預設值

除非使用者另有指示，否則：

在 Claude 模型版本的選擇上，請使用 Claude Opus 4.8，其對應的精確模型字串為 claude-opus-4-8。只要任務稍微複雜，請預設啟用適應性思考（adaptive thinking，即 thinking: {type: "adaptive"}）。最後，任何可能包含長輸入、長輸出或高 max_tokens 設定的請求，請預設使用串流（streaming）— 這能避免觸發請求逾時。若您不需要個別處理串流事件，可使用 SDK 的 .get_final_message() / .finalMessage() 輔助函式來取得完整回應。

---

子命令

若本提示詞底部的「使用者請求」僅為單純的子命令字串（無其它內文敘述），請搜尋本文件中的所有子命令表格（包含下方附加章節中的表格），並直接執行對應的「動作（Action）」欄位指示。這能讓使用者透過 /claude-api <subcommand> 觸發特定的工作流程。若文件中無匹配的表格，則將該請求視為一般文字處理。

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/raw 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)	測試版工具呼叫，支援註解類別
Go	是 (beta)	是 (beta)	toolrunner 套件中的 BetaToolRunner
Ruby	是 (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 均提供專屬的語言 README（{lang}/managed-agents/README.md、curl/managed-agents.md）。請閱讀您所使用語言的 README，並搭配跨語言的 shared/managed-agents-*.md 概念文件。Agent 為持久化物件 — 建立一次後即可透過 ID 引用。 請儲存 agents.create 回傳的 Agent ID，並在後續呼叫 sessions.create 時傳入；切勿在請求處理路徑中重複呼叫 agents.create。Anthropic CLI（ant）是透過版本控制的 YAML 檔建立 Agent 與環境的便利工具 — 詳情請參閱 shared/anthropic-cli.md。若您需要的語言綁定未顯示在 README 中，請使用 WebFetch 讀取 shared/live-sources.md 中的對應條目，切勿憑空臆測。C# 透過 client.Beta.Agents 及相關命名空間提供 Managed Agents 的測試版支援。

---

我應該使用哪種介面（Surface）？

從簡單開始。 預設採用能滿足需求的最低層級。單次 API 呼叫與工作流程（workflows）即可涵蓋大多數情境 — 僅在任務確實需要開放式、由模型驅動的自主探索時，才使用 Agent。

使用情境	層級	推薦介面	原因
分類、摘要、擷取、問答	單次 LLM 呼叫	Claude API	一次請求，一次回應
批次處理或向量嵌入（embeddings）	單次 LLM 呼叫	Claude API	專用 API 端點
由程式碼控制邏輯的多步驟管道	工作流程	Claude API + 工具呼叫	由您協調整體迴圈邏輯
自訂 Agent 搭配自有工具	Agent	Claude API + 工具呼叫	提供最高靈活性
伺服器端管理的狀態化 Agent（含工作區）	Agent	Managed Agents	由 Anthropic 運行迴圈並託管工具執行的沙盒環境
持久化、具版本控管的 Agent 設定	Agent	Managed Agents	Agent 為儲存的物件；會話可固定特定版本
支援檔案掛載的長期多輪對話 Agent	Agent	Managed Agents	獨立會話容器、SSE 事件串流、Skills + MCP

注意： 當您希望由 Anthropic 運行 Agent 迴圈並且託管執行工具（檔案操作、bash、程式碼執行等均在個別會話的工作區內運行）的容器時，Managed Agents 是最佳選擇。若您想自行託管運算資源或運行自訂的工具執行環境，則應選擇 Claude API + 工具呼叫 — 可使用 Tool Runner 進行自動迴圈處理，或是採用手動迴圈以實現精細控制（審核關卡、自訂日誌、條件式執行）。

雲端提供商存取。 AWS 上的 Claude 平台由 Anthropic 親自營運，具備同日同步的 API 功能支援 — 包含 Managed Agents 以及本 Skill 中的各項功能均可使用，自託管沙盒除外（詳情請參閱 shared/claude-platform-on-aws.md）。Amazon Bedrock、Google Vertex AI 與 Microsoft Foundry 不支援 Managed Agents 或 Anthropic 伺服器端工具；在這些平台上請使用 Claude API + 工具呼叫。

決策樹

您的應用程式需要什麼？

0. 使用哪家提供商？
   ├── 第一方 API 或 AWS 上的 Claude 平台 → 繼續（支援全套介面）。
   └── Amazon Bedrock、Google Vertex AI 或 Microsoft Foundry → 選擇 Claude API（若需要 Agent 則搭配工具呼叫）；上述平台不支援 Managed Agents。

1. 單次 LLM 呼叫（分類、摘要、擷取、問答）
   └── 選擇 Claude API — 一次請求，一次回應

2. 是否希望由 Anthropic 運行 Agent 迴圈，並託管 Claude 執行工具
   （bash、檔案操作、程式碼）的獨立會話容器？
   └── 是 → 選擇 Managed Agents — 伺服器管理的會話、持久化 Agent 設定、
       SSE 事件串流、Skills + MCP、檔案掛載。
       範例：「每個任務具備獨立工作區的狀態化寫程式 Agent」、
             「向 UI 串流事件的長期研究型 Agent」、
             「跨多個會話使用且具備版本控管的持久化 Agent 設定」

3. 工作流程（多步驟、程式碼協調、搭配自有工具）
   └── 選擇 Claude API + 工具呼叫 — 由您掌控迴圈邏輯

4. 開放式 Agent（模型自主決定執行路徑、搭配自有工具、