--- title: 遷移至 API 版本 2026-10-21 url: https://platform.claude.com/docs/zh-TW/api/migration-2026-10-21 description: 將 Claude API 整合從 API 版本 2023-06-01 升級至 2026-10-21：需要安裝的 SDK 版本以及需要進行的程式碼變更。 --- 本指南列出從 API 版本 `2023-06-01` 遷移至 `2026-10-21` 所需的程式碼變更。[升級步驟](https://platform.claude.com/docs/zh-TW/api/migration-2026-10-21#migration-checklist)依序說明您需要執行的操作。 ## 升級步驟 如果您使用 SDK，您的請求會使用該 SDK 主要版本發布時的現行 API 版本。下方針對您的語言所列出的版本，是第一個使用 `2026-10-21` 的版本，因此請升級至這些版本。如果您不透過 SDK 呼叫 API，請將 `anthropic-version` 標頭設定為 `2026-10-21`。 將 `anthropic-version` 標頭設定為 `2026-10-21`： ```bash curl https://api.anthropic.com/v1/messages \ -H "x-api-key: $ANTHROPIC_API_KEY" \ -H "anthropic-version: 2026-10-21" \ -H "content-type: application/json" \ -d '{ "model": "claude-opus-5-5", "max_tokens": 1024, "messages": [{"role": "user", "content": "Hello, Claude"}] }' ``` 將 `ant` CLI 升級至 2.0.0 版。Homebrew 指令與發布版本的下載方式維持不變。 Go 要求主要版本為 2 或更高的模組，其路徑必須以該版本結尾，因此 CLI 的模組路徑現在是 `github.com/anthropics/anthropic-cli/v2`。如果您使用 `go install` 安裝，請在路徑中加上 `/v2`： ```bash # 之前 go install 'github.com/anthropics/anthropic-cli/cmd/ant@latest' # 之後 go install 'github.com/anthropics/anthropic-cli/v2/cmd/ant@latest' ``` 舊路徑會繼續安裝最新的 v1 版本，且不會出現任何錯誤或警告。 將 `anthropic` 套件升級至 2.0.0 版。 將 `@anthropic-ai/sdk` 套件升級至 1.0.0 版。 `@anthropic-ai/bedrock-sdk`、`@anthropic-ai/vertex-sdk`、`@anthropic-ai/foundry-sdk`、`@anthropic-ai/aws-sdk` 與 `@anthropic-ai/google-cloud-sdk` 的 v1 需要 `@anthropic-ai/sdk` 的 v1，而它們較早的版本則需要低於 1 的版本。如果您使用其中任何一個，請在同一次升級中將其移至 v1。否則，您的套件管理工具會為它另外安裝一份較舊的 `@anthropic-ai/sdk`。 將 `Anthropic` 套件升級至 13.0.0 版。 升級至 Go SDK 的 2.0.0 版，其模組路徑為 `github.com/anthropics/anthropic-sdk-go/v2`。Go 模組的新主要版本會有新的匯入路徑，因此請將每個 `github.com/anthropics/anthropic-sdk-go` 的匯入，以及其套件（例如 `github.com/anthropics/anthropic-sdk-go/option`）的匯入，改為以 `github.com/anthropics/anthropic-sdk-go/v2` 開頭。接著執行 `go get github.com/anthropics/anthropic-sdk-go/v2`。 將 `com.anthropic:anthropic-java` artifact 升級至 3.0.0 版。 執行 `composer require "anthropic-ai/sdk"` 將套件升級至 1.0.0 版。單獨執行 `composer update` 只會停留在您目前的版本限制範圍內。 將 `anthropic` gem 升級至 2.0.0 版。 在 Amazon Bedrock 上，`2026-10-21` 僅適用於 Claude 4.7 及更新的模型。如果您在 Bedrock 上呼叫較舊的模型（列於 [Amazon Bedrock 上的 Claude（Opus 4.6 及更早版本）](https://platform.claude.com/docs/zh-TW/build-with-claude/claude-on-amazon-bedrock-legacy)），請繼續使用您目前的 SDK 版本；或者，如果您自行設定 API 版本，請繼續傳送您目前傳送的版本。若要將這些呼叫移至 `2026-10-21`，請先將它們切換至 Claude 4.7 或更新的模型。 請將此升級與下一步驟中的修正一併發布。 逐一檢視[重大變更](https://platform.claude.com/docs/zh-TW/api/migration-2026-10-21#breaking-changes)，並針對每一項會影響您的變更更新程式碼。同時也請進行[新版 SDK 或 CLI 所需的程式碼變更](https://platform.claude.com/docs/zh-TW/api/migration-2026-10-21#sdk-changes)。 在發布之前，請針對 `2026-10-21` 測試您的整合。 ## 重大變更 ### Messages API 這些變更適用於對 Messages API（`POST /v1/messages`）的請求、[token 計數](https://platform.claude.com/docs/zh-TW/build-with-claude/token-counting)，以及以 `2026-10-21` 建立的 [Message Batch](https://platform.claude.com/docs/zh-TW/build-with-claude/batch-processing) 中的每個請求。 #### assistant 訊息中的 document 區塊會傳回錯誤 如果您直接在 `assistant` 訊息中傳送 `document` 區塊，則會受到影響。 在 `2026-10-21` 中，直接在 `assistant` 訊息中放置 `document` 區塊的請求會傳回 400 錯誤。請改為在 `user` 訊息中傳送文件。巢狀於其他區塊中的文件（例如 Claude 傳回的網頁擷取工具結果）仍會被接受。 #### user 訊息中的引用會傳回錯誤 如果您在 `user` 訊息的 `text` 區塊上傳送 `citations`（包括在 `search_result` 區塊內），則會受到影響。 在 `2026-10-21` 中，在 `user` 訊息中傳送帶有非空 `citations` 陣列之 `text` 區塊的請求會傳回 400 錯誤。請從這些區塊中移除 `citations`。`assistant` 訊息中 `text` 區塊上的引用（例如您回傳的 Claude 先前回覆）仍會被接受，文件與搜尋結果上的 `"citations": {"enabled": true}` 設定也同樣會被接受。 #### 取樣參數已移除 如果您在 Messages 請求或 Message Batch 請求中傳送 `temperature`、`top_p` 或 `top_k`，則會受到影響。 在 `2026-10-21` 中，傳送 `temperature`、`top_p` 或 `top_k` 的請求會傳回 400 錯誤，即使參數值為預設值也是如此。 請從您的請求中移除這三個參數。 自最新的主要版本起，SDK 與 CLI 已不再提供這三個參數。 沒有這些參數時，請求會以其預設值進行取樣，包括 `temperature` 為 1.0，與省略這些參數的 `2023-06-01` 請求相同。已經只接受預設值的模型（例如 Claude 4.7 及更新的模型）會與先前一樣進行取樣。在接受其他值的模型上（例如 Claude Sonnet 4.6），原本為了獲得更一致的輸出而調低 `temperature` 的請求將失去該效果，且沒有其他設定可以取代它。如果某個請求依賴非預設值，請停止傳送該參數，或讓該請求繼續使用 `2023-06-01`。 ### Admin API 與 Claude Enterprise Analytics API 如果您的程式碼讀取下表中的 Admin API 或 Claude Enterprise Analytics API 回應欄位，則會受到影響。 在 `2026-10-21` 中，Admin API 與 [Claude Enterprise Analytics API](https://platform.claude.com/docs/zh-TW/manage-claude/analytics-api) 的回應不再包含已重新命名欄位的舊名稱。請改用新名稱。 Admin API： | 端點 | 舊名稱 | 新名稱 | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------- | -------------------------------------------------------------------------------------------------------------------------------- | | [RBAC 群組](https://platform.claude.com/docs/zh-TW/api/beta/organization/rbac_groups/list)：建立、列出、擷取與更新 | `roles` | `role_ids` | | [RBAC 群組成員](https://platform.claude.com/docs/zh-TW/api/beta/organization/rbac_groups/members/list)：列出與新增，以及[移除成員](https://platform.claude.com/docs/zh-TW/api/beta/organization/rbac_groups/members/remove)的回應 | `group_id` | `rbac_group_id` | | [RBAC 角色](https://platform.claude.com/docs/zh-TW/api/beta/organization/rbac_roles/list)：列出與擷取 | `name` | `display_name` | | [組織](https://platform.claude.com/docs/zh-TW/api/organization/rate_limits/list)與[工作區](https://platform.claude.com/docs/zh-TW/api/organization/workspaces/rate_limits/list)速率限制：列出，以及設定工作區速率限制的回應 | `group_type` | `group.type` | | [API 金鑰](https://platform.claude.com/docs/zh-TW/api/organization/api_keys/list)：列出、擷取與更新 | `workspace_id` | `scope`（值不同；請參閱 [API 金鑰上的 `workspace_id`](https://platform.claude.com/docs/zh-TW/api/migration-2026-10-21#api-key-workspace-id)） | Claude Enterprise Analytics API： | 端點 | 舊名稱 | 新名稱 | | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- | --------------------- | | 每位使用者的[用量](https://platform.claude.com/docs/zh-TW/api/beta/organization/analytics/user_usage_report/list)與[費用](https://platform.claude.com/docs/zh-TW/api/beta/organization/analytics/user_cost_report/list)報告 | `actor.email` | `actor.email_address` | | [活動摘要](https://platform.claude.com/docs/zh-TW/api/beta/organization/analytics/summaries/list) | `summaries` | `data` | 速率限制列出端點上的 `group_type` 查詢參數，以及 API 金鑰列出端點上的 `workspace_id` 篩選條件維持不變。 #### API 金鑰上的 `workspace_id` 如果您的程式碼讀取 API 金鑰上的 `workspace_id`，則會受到影響。 在 `2023-06-01` 中，API 金鑰的 `workspace_id` 是該金鑰所綁定之工作區的 ID；對於綁定至 Default Workspace 的金鑰，以及未綁定至單一工作區的金鑰（全工作區金鑰），其值為 `null`。 在 `2026-10-21` 中，`workspace_id` 已移除。請改為讀取 `scope`：對於綁定至某個工作區（包括 Default Workspace）的金鑰，`scope.workspace_id` 是該工作區的實際 ID；而全工作區金鑰的 `scope` 為 `{"type": "organization"}`，且沒有 `workspace_id`。 如果您的程式碼將 `null` 的 `workspace_id` 視為 Default Workspace，請改為將 `scope.workspace_id` 與您的 Default Workspace ID 進行比較。若要找出該 ID，請以 `include_default=true` 呼叫 [List Workspaces](https://platform.claude.com/docs/zh-TW/api/organization/workspaces/list)，並取得名稱為 `"Default"` 的工作區。 ## SDK 與 CLI 變更 較早的 SDK 與 CLI 版本會在每個請求中傳送 `anthropic-version: 2023-06-01`。[切換至 2026-10-21](https://platform.claude.com/docs/zh-TW/api/migration-2026-10-21#upgrade) 中所列的版本則會傳送 `2026-10-21`。[重大變更](https://platform.claude.com/docs/zh-TW/api/migration-2026-10-21#breaking-changes)中的變更同樣適用於這些版本：已移除的參數與舊欄位名稱也已從 SDK 的型別以及 CLI 的旗標與輸出中移除。 ### Amazon Bedrock 與 Google Cloud 上的 API 版本 SDK 中用於 Google Cloud's Agent Platform 的用戶端會在請求主體中指定版本，而非在標頭中。它會傳送 `anthropic_version: 2026-10-21`（較早的版本傳送的是 `vertex-2023-10-16`），且不傳送 `anthropic-version` 標頭。 Amazon Bedrock 用戶端也是如此。它會傳送 `anthropic_version: 2026-10-21`（較早的版本傳送的是 `bedrock-2023-05-31`），且不傳送 `anthropic-version` 標頭。早於 Claude Opus 4.7 的模型目前尚不支援 Bedrock 上的 API 版本 `2026-10-21`，指定該版本的請求可能會收到 400 錯誤。如果您使用其中任何一個模型，請暫時繼續使用較早的 SDK 版本，或者升級後自行傳送 `bedrock-2023-05-31`。 這適用於 `AnthropicVertex`、`AsyncAnthropicVertex`、`AnthropicBedrock` 與 `AsyncAnthropicBedrock`。 若要傳送 `bedrock-2023-05-31`，請在每個請求中傳入 `extra_body={"anthropic_version": "bedrock-2023-05-31"}`。 這適用於 `AnthropicVertex` 與 `AnthropicBedrock`。如果您在用戶端或請求上設定 `anthropic-version` 標頭，其值會放入主體中。 若要傳送 `bedrock-2023-05-31`，請在用戶端或請求上將 `anthropic-version` 標頭設定為 `"bedrock-2023-05-31"`。 這適用於 `AnthropicVertexClient` 與 `AnthropicBedrockClient`。如果您透過 `ClientOptions.ExtraHeaders` 設定 `anthropic-version` 標頭，其值會放入主體中。 若要傳送 `bedrock-2023-05-31`，請在用戶端上呼叫 `WithOptions`，並在 `ClientOptions.ExtraHeaders` 中將 `anthropic-version` 設定為 `bedrock-2023-05-31`。 這適用於 `vertex` 與 `bedrock` 套件。如果您使用 `option.WithHeader` 設定 `anthropic-version` 標頭，其值會放入主體中。`vertex.DefaultVersion` 與 `bedrock.DefaultVersion` 已移除。 若要傳送 `bedrock-2023-05-31`，請將 `option.WithHeader("anthropic-version", "bedrock-2023-05-31")` 傳入用戶端或請求。 這適用於 `VertexBackend` 與 `BedrockBackend`。如果您在用戶端或請求上設定 `anthropic-version` 標頭，其值會放入主體中。 若要傳送 `bedrock-2023-05-31`，請在用戶端或請求上將 `anthropic-version` 標頭設定為 `bedrock-2023-05-31`。 這適用於 `Anthropic\Vertex\Client` 與 `Anthropic\Bedrock\Client`。 若要傳送 `bedrock-2023-05-31`，請在 `requestOptions` 中傳入 `'extraBodyParams' => ['anthropic_version' => 'bedrock-2023-05-31']`。 這適用於 `Anthropic::VertexClient` 與 `Anthropic::BedrockClient`。如果您透過 `extra_headers` 設定 `anthropic-version` 標頭，其值會放入主體中。`Anthropic::VertexClient::DEFAULT_VERSION` 與 `Anthropic::BedrockClient::DEFAULT_VERSION` 已移除。 若要傳送 `bedrock-2023-05-31`，請在 `request_options` 中傳入 `extra_headers: {"anthropic-version" => "bedrock-2023-05-31"}`。 ### `MessageParam` 是每個角色各有一個型別的 union 在較早的版本中，`MessageParam` 是適用於所有角色的單一型別。現在每個角色都有自己的型別：`UserMessageParam`、`AssistantMessageParam` 與 `SystemMessageParam`。`BetaMessageParam` 也以相同方式拆分為 `BetaUserMessageParam`、`BetaAssistantMessageParam` 與 `BetaSystemMessageParam`。SDK 傳送的請求具有與先前相同的欄位與值。 以 dict 字面值撰寫的訊息（例如 `{"role": "user", "content": "Hello"}`）不需要任何變更。 在 v1 中，`anthropic.types.MessageParam` 是單一的 `TypedDict`。在 v2 中，它是這三個型別的 union，而 `anthropic.types.beta.BetaMessageParam` 則是其三個型別的 union。這兩個名稱在型別註記中仍可使用，例如 `list[MessageParam]`。 現在呼叫這兩個名稱中的任何一個都會引發 `TypeError`，且型別檢查工具會標記它。請將訊息寫成 dict： ```python # 之前 message = MessageParam(role="user", content="Hello") # 之後 message: MessageParam = {"role": "user", "content": "Hello"} ``` 繼承這兩個名稱中的任何一個也會引發 `TypeError`。請改為繼承該角色的型別，例如 `UserMessageParam`。 其餘的變更僅影響型別檢查。`role` 為可容納多個角色之變數的 dict 不會符合 union 中的任何型別，因此請一次針對一個角色建立 dict： ```python # 之前 def to_message(role: Literal["user", "assistant"], text: str) -> MessageParam: return {"role": role, "content": text} # 之後 def to_message(role: Literal["user", "assistant"], text: str) -> MessageParam: if role == "user": return {"role": "user", "content": text} return {"role": "assistant", "content": text} ``` 另有兩項僅適用於 `BetaMessageParam`： * `clear_at` 與 `output_config` 是 `BetaSystemMessageParam` 的鍵，因此 user 或 assistant 訊息不能擁有它們。 * `content` 在 `BetaSystemMessageParam` 中是選用的，因此 pyright 會回報 `message["content"]`。請使用 `message.get("content")` 讀取，或先檢查 `message["role"]` 不是 `"system"`。 `MessageParam` 原本是單一介面。現在它是 `UserMessageParam | AssistantMessageParam | SystemMessageParam`，而 `BetaMessageParam` 則是其三個型別的相同 union。只有型別有所變更。指定了角色的訊息字面值（例如 `{ role: "user", content: "Hello, Claude" }`）的型別檢查結果與先前相同，因此大多數程式碼不需要變更。 system 型別與其他兩者不同。它的 `content` 是字串或文字區塊，在 `beta` 中還包括 `tool_addition` 與 `tool_removal` 區塊，因此在其中放置圖片區塊將無法再通過編譯。在 `beta` 中，只有它擁有 `clear_at` 與 `output_config`，且其 `content` 是選用的。 處理任何角色訊息的程式碼，必須在取代或新增內容區塊之前，以及在讀取 `clear_at` 或 `output_config` 之前，先檢查 `role`： ```typescript // 之前 const copy: Anthropic.MessageParam = { ...message, content: blocks }; // 之後 const copy: Anthropic.MessageParam = message.role === "system" ? message : { ...message, content: blocks }; ``` `BetaMessageParam` 的 `content` 可能為 `undefined`： ```typescript // 之前 const types = typeof message.content === "string" ? [] : message.content.map((block) => block.type); // 之後 const types = Array.isArray(message.content) ? message.content.map((block) => block.type) : []; ``` 型別 `BetaMessageParam["content"]` 也包含 `undefined`。對於 user 或 assistant 訊息的內容，請使用 `BetaMessageContentParam`。 介面無法擴充 union，類別也無法實作 union。請改用型別別名，或指定單一角色的型別。 ```typescript // 之前 interface StoredMessage extends Anthropic.MessageParam { id: string; } // 之後 type StoredMessage = Anthropic.MessageParam & { id: string }; ``` 在 v12 中，`MessageParam` 與 `BetaMessageParam` 是由您設定其 `Role` 與 `Content` 的類別。在 v13 中，兩者各自是其角色之三個類別的 union，而 `Anthropic.Models.Messages` 與 `Anthropic.Models.Beta.Messages` 中的 `Role` 列舉已移除。 建立訊息時，請指定該角色的類別並刪除 `Role`。每個類別都會隱含轉換為 union： ```csharp // 之前 Messages = [new() { Role = Role.User, Content = "Hello, Claude" }], // 之後 Messages = [new UserMessageParam { Content = "Hello, Claude" }], ``` `new UserMessageParam("Hello, Claude")` 也可以使用。 容納 `Content` 的類別也有所變更： * `MessageParamContent` 現在是 `MessageContentParam`，而 `BetaMessageParamContent` 現在是 `BetaMessageContentParam`。 * system 訊息有自己的內容類別。`SystemMessageParamContent` 容納字串或 `TextBlockParam` 清單，而 `BetaSystemMessageParamContent` 容納字串或 `SystemMessageContentBlock` 清單。`List` 或 `List` 不再能轉換為它。 * `ClearAt` 與 `OutputConfig` 僅存在於 `BetaSystemMessageParam` 上。 讀取訊息時，union 仍具有 `Role` 與 `Content`，但您無法設定它們，因此 `with` 運算式需作用於該角色的類別上。`Role` 現在容納 `MessageParamRole` 或 `BetaMessageParamRole`。`BetaMessageParam.Content` 可能為 `null`，因為 `Content` 在 `BetaSystemMessageParam` 上是選用的。 ```csharp // 之前 if (message.Role.Value() == Role.Assistant) { } // 之後 if (message.Role.Value() == MessageParamRole.Assistant) { } ``` `TryPickUser`、`TryPickAssistant`、`TryPickSystem`、`Switch` 與 `Match` 會提供該角色的類別。 在 v1 中，`MessageParam` 是具有 `Role` 與 `Content` 欄位的單一 struct。在 v2 中，它是一個 union：`OfUser` 容納 `*UserMessageParam`，`OfAssistant` 容納 `*AssistantMessageParam`，`OfSystem` 容納 `*SystemMessageParam`。`BetaMessageParam` 也以相同方式變更。除了 beta system 訊息中鍵的順序之外，SDK 傳送的 JSON 與先前相同。 `NewUserMessage`、`NewAssistantMessage`、`NewBetaUserMessage`，以及 `Message` 與 `BetaMessage` 的 `ToParam` 方法的運作方式與先前相同，因此使用它們建立訊息的程式碼不需要變更。 struct 字面值需指定其角色的型別。請省略 `Role`，因為每個型別都會自行序列化其角色： ```go // 之前 anthropic.MessageParam{ Role: anthropic.MessageParamRoleAssistant, Content: blocks, } // 之後 anthropic.MessageParam{OfAssistant: &anthropic.AssistantMessageParam{ Content: blocks, }} ``` 讀取訊息的程式碼需檢查哪個欄位已設定： ```go // 之前 if message.Role == anthropic.MessageParamRoleUser { blocks = message.Content } // 之後 if message.OfUser != nil { blocks = message.OfUser.Content } ``` * `MessageParamRole` 與 `BetaMessageParamRole` 型別及其常數已移除。`message.GetRole()` 會傳回指向角色 `string` 的指標，若未設定任何欄位則傳回 `nil`。 * `ClearAt` 與 `OutputConfig` 已從 `BetaMessageParam` 移至 `BetaSystemMessageParam`。`BetaMessageParamClearAt` 型別及其常數的名稱現在以 `BetaSystemMessageParamClearAt` 開頭。 * `SystemMessageParam.Content` 是 `[]TextBlockParam`。`BetaSystemMessageParam.Content` 是 `[]BetaSystemMessageParamContentUnion`，可容納 `text`、`tool_addition` 與 `tool_removal` 區塊。`NewBetaSystemMessage` 接受該型別的區塊，因此 `anthropic.NewBetaTextBlock("Be brief.")` 會變成 `anthropic.BetaSystemMessageParamContentUnion{OfText: &anthropic.BetaTextBlockParam{Text: "Be brief."}}`。 * `MessageParam` 的副本與原始值指向同一則訊息。設定 `duplicate.OfUser.Content` 會同時變更兩者，而在 v1 中設定 `duplicate.Content` 只會變更副本。 * 對於 `user` 或 `assistant` 以外的角色，`mcp.ToMessage` 會傳回 `*mcp.UnsupportedValueError`。v1 會將任何角色複製到訊息中。 在 v2 中，`MessageParam` 是具有 `role` 與 `content` 的單一類別。在 v3 中，它是三個類別的 union，而 `MessageParam.Content` 現在是頂層的 `MessageContentParam`。`BetaMessageParam` 也以相同方式變更，其類別名稱相同但加上 `Beta` 前綴。SDK 傳送的 JSON 相同，只是 beta system 訊息現在會將 `role` 放在 `content` 之前。 使用 `String` 的 `addUserMessage`、`addAssistantMessage` 與 `addSystemMessage`，使用 `Message` 或 `MessageParam` 的 `addMessage`，以及 `Message.toParam()` 都沒有變更。 `MessageParam.builder()` 與 `toBuilder()` 已移除。請呼叫該角色的工廠方法，即 `ofUser`、`ofAssistant` 或 `ofSystem`： ```java // 修改前 MessageParam message = MessageParam.builder() .role(MessageParam.Role.USER) .content("Hello, Claude") .build(); // 修改後 MessageParam message = MessageParam.ofUser("Hello, Claude"); ``` 在 `MessageCreateParams`、`StructuredMessageCreateParams`、`MessageCountTokensParams` 與 `BatchCreateParams.Request.Params` 的 builder 上，接受內容區塊清單的方法有了新名稱： | v2 | v2 beta | v3 | | ---------------------------------- | --------------------------------------------- | ----------------------------------------- | | `addUserMessageOfBlockParams` | `addUserMessageOfBetaContentBlockParams` | `addUserMessageOfContentBlockParams` | | `addAssistantMessageOfBlockParams` | `addAssistantMessageOfBetaContentBlockParams` | `addAssistantMessageOfContentBlockParams` | | `addSystemMessageOfBlockParams` | `addSystemMessageOfBetaContentBlockParams` | `addSystemMessageOfBlocks` | 在內容類別上，`ofBlockParams`、`blockParams()`、`isBlockParams()`、`asBlockParams()` 以及 visitor 的 `visitBlockParams` 中的 `BlockParams`（在 beta 中為 `BetaContentBlockParams`）變為 `ContentBlockParams`。 system 訊息有自己的內容類別 `SystemMessageParam.Content`，`addSystemMessage` 現在接受此類別。其區塊是 `TextBlockParam`，而非 `ContentBlockParam`。在 beta 中，它們是 `BetaSystemMessageParam.Content.SystemMessageContentBlock`，具有 `ofText`、`ofToolAddition` 與 `ofToolRemoval`。 ```java // 之前 builder.addSystemMessageOfBlockParams(List.of(ContentBlockParam.ofText(textBlock))); // 之後 builder.addSystemMessageOfBlocks(List.of(textBlock)); ``` 讀取訊息時，`role()` 沒有變更。`content()` 會傳回 `MessageContentParam`，在 beta 中則傳回 `Optional`，因為 system 訊息可能沒有內容。`_role()`、`_content()` 與 `_additionalProperties()` 現在位於該角色的類別上，可由 `asUser()`、`asAssistant()` 或 `asSystem()` 傳回。 這些類別位於 `Anthropic\Messages`，beta 類別則位於 `Anthropic\Beta\Messages`。您以陣列撰寫的訊息沒有變更，且仍需要其 `'role'`。 `MessageParam::with()` 與 `BetaMessageParam::with()` 仍然保留，並會傳回與 `role` 對應的類別。使用具名引數的呼叫不需要變更。`role` 現在是第一個參數，因此在位置引數呼叫中，請對調 `content` 與 `role`，或在該角色的類別上呼叫 `with()`（該方法不接受 `role`）。對於舊順序的引數，PHP 會擲出 `UnhandledMatchError`（PHPStan 不會對此發出警告），或者在 `content` 是清單或 `role` 是列舉成員時擲出 `TypeError`。 ```php // 修改前 MessageParam::with('Hello, Claude', 'user'); // 修改後 UserMessageParam::with('Hello, Claude'); ``` 不再有任何物件是 `MessageParam`：`instanceof MessageParam` 為 false，且在參數或傳回型別指定它的地方，PHP 會擲出 `TypeError`。請改為指定這三個類別： ```php // 之前 function send(MessageParam $message): void {} // 之後 function send(UserMessageParam|AssistantMessageParam|SystemMessageParam $message): void {} ``` * `MessageParam::fromArray()` 與 `(new MessageParam)->withContent()` 會擲出「Call to undefined method」。請在該角色的類別上呼叫它們，該類別會自行設定 `role`。 * `withRole()` 現在只接受字串：對於 `Role` 成員，PHP 會擲出 `TypeError`。若要為訊息指定其他角色，請建立該角色的類別。 * `clearAt` 與 `outputConfig` 僅存在於 `BetaSystemMessageParam` 上，且 `BetaMessageParam::with()` 會針對其他兩個角色捨棄它們。`BetaMessageParam\ClearAt` 列舉現在是 `BetaSystemMessageParam\ClearAt`。 * `MessageParam\Content` 現在是 `MessageContentParam`，而 `BetaMessageParam\Content` 現在是 `BetaMessageContentParam`。它們的 PHPStan 型別也採用新名稱：`ContentShape` 現在是 `MessageContentParamShape`。 * `'role'` 為 `Role` 成員的陣列仍可運作，但 PHPStan 現在會回報它。請改寫為字串。 您以 hash 撰寫的訊息沒有變更。 在 v2 中，`Anthropic::MessageParam` 是 `Anthropic::UserMessageParam`、`Anthropic::AssistantMessageParam` 與 `Anthropic::SystemMessageParam` 的 union。同樣地，`Anthropic::Beta::BetaMessageParam` 是其三個類別的 union。 `Anthropic::MessageParam.new(role: :user, content: "Hello, Claude")` 仍可運作，並會傳回該角色類別的實例。您也可以自行建立該類別，不需 `role:`，寫法為 `Anthropic::UserMessageParam.new(content: "Hello, Claude")`。對於建立或檢查這些實例的程式碼，有四項變更： * `MessageParam.new` 只接受關鍵字引數，因此請以 `MessageParam.new(**hash)` 傳入 hash。當缺少 `role:` 或其值不是三個角色之一時，它會引發 `ArgumentError`。 * `message.is_a?(Anthropic::MessageParam)` 為 `false`。`when Anthropic::MessageParam` 分支與 `messages.grep(Anthropic::MessageParam)` 仍會符合。 * 以 `.new` 建立的實例，其 `to_h` 中沒有 `:role`，且 `message[:role]` 為 `nil`。`message.role` 仍會傳回角色。 * 只有 `BetaSystemMessageParam` 具有 `clear_at` 與 `output_config`。在 user 或 assistant 訊息上，它們原本傳回 `nil`，現在則會引發 `NoMethodError`。 ```ruby # 之前 typed = messages.select { _1.is_a?(Anthropic::MessageParam) } roles = typed.map { _1[:role] } # 之後 typed = messages.grep(Anthropic::MessageParam) roles = typed.map(&:role) ``` `Role` 列舉模組保留不變。以下常數已移動。以 `Beta` 開頭的名稱位於 `Anthropic::Beta` 之下，其他則位於 `Anthropic` 之下： | 已移除 | 改用 | | --------------------------- | --------------------------------------------------------------------------- | | `MessageParam::Content` | `MessageContentParam`，或針對 system 訊息使用 `SystemMessageParam::Content` | | `BetaMessageParam::Content` | `BetaMessageContentParam`，或針對 system 訊息使用 `BetaSystemMessageParam::Content` | | `BetaMessageParam::ClearAt` | `BetaSystemMessageParam::ClearAt` | 如果您使用 Sorbet 進行型別檢查，`MessageParam::OrHash` 已移除，且作為型別的 `Anthropic::MessageParam` 不再接受實例。請使用 `Anthropic::MessageParam::Variants` 表示這三個類別，每個類別都有自己的 `OrHash`。在 RBS 中，型別為 `Anthropic::MessageParam` 的值沒有 `role` 或 `content`。請使用 `Anthropic::Models::message_param` 別名，它原本是訊息的 hash 形式，現在則是這三個類別的 union。beta 的名稱為 `BetaMessageParam::Variants` 與 `Anthropic::Models::Beta::beta_message_param`。 ### 單一值列舉現在是常數 這會影響 C#、Go、Java、PHP 和 Ruby SDK，以及一個 CLI 旗標。在較早的版本中，只能容納一個值的必要欄位擁有自己的列舉型別，且該列舉只有一個成員。這些欄位現在是常數，而這些列舉型別已被移除。SDK 傳送和讀取的 JSON 保持不變。 `--type` 在 `ant beta:sessions:resources add` 上是選用的。`file` 是 `--type` 在該處唯一可接受的值，因此 v2 會替您傳送它。仍然傳遞 `--type file` 的命令可以繼續運作，因此無需做任何變更。 在 v12 中，這類 `required` 屬性擁有只有單一成員的列舉，例如 `BetaManagedAgentsTextBlockType.Text`。它們幾乎都是 `Anthropic.Models.Beta` 下某個類別的 `Type` 屬性：`Agents`、`DeploymentRuns`、`Deployments`、`Dreams`、`Environments`、`MemoryStores`、`Sessions`、`UserProfiles` 和 `Vaults`。在 v13 中，這些屬性是由建構函式填入的 `JsonElement`，就像 `TextBlockParam.Type` 原本的做法一樣。 選用屬性（例如 `BetaManagedAgentsGlobToolConfigParams.Type`）會保留其列舉。其中兩個列舉有了新名稱： | v12 | v13 | | ------------------------------------------- | ----------------------------------------- | | `BetaManagedAgentsBashToolConfigParamsType` | `Anthropic.Models.Beta.Agents.Type` | | `BetaPackagesType` | `Anthropic.Models.Beta.Environments.Type` | 建立物件時，請刪除該屬性： ```csharp // 之前 new BetaManagedAgentsTextBlock { Type = BetaManagedAgentsTextBlockType.Text, Text = "Hello Claude!", }; // 之後 new BetaManagedAgentsTextBlock { Text = "Hello Claude!" }; ``` 只剩下一個必要屬性的類別也會新增一個接受該屬性的建構函式，因此 `new BetaManagedAgentsTextBlock("Hello Claude!")` 也可以運作。沒有剩下任何必要屬性的類別則以 `new BetaManagedAgentsAlwaysAllowPolicy()` 建立。 讀取時，請與字串比較： ```csharp // 之前 if (message.Type.Value() == BetaManagedAgentsAgentMessageEventType.AgentMessage) { } // 之後 if (message.Type.GetString() == "agent.message") { } ``` 若要區分聯集的各個變體，請繼續使用其 `TryPick*`、`Switch` 和 `Match` 方法，這些方法沒有變更。 這類列舉型別及其常數的一個範例是 `BetaManagedAgentsTextBlockType` 和 `BetaManagedAgentsTextBlockTypeText`。它們幾乎都是 `client.Beta` 下某個結構的 `Type` 欄位：Agents、Deployments、Deployment Runs、Dreams、Environments、Memory Stores、Sessions、User Profiles 和 Vaults。在 v2 中，這些欄位使用 `shared/constant` 套件中的型別，就像 `TextBlockParam.Type` 原本的做法一樣。選用欄位（例如 `BetaManagedAgentsBashToolConfigParams.Type`）會保留其列舉。 在請求中，請刪除該欄位。當您省略它時，它會序列化為其唯一的值： ```go // 之前 anthropic.BetaManagedAgentsTextBlockParam{ Type: anthropic.BetaManagedAgentsTextBlockTypeText, Text: "Hello Claude!", } // 之後 anthropic.BetaManagedAgentsTextBlockParam{ Text: "Hello Claude!", } ``` 唯一欄位是該 `Type` 的結構現在有一個建構函式，例如 `NewBetaManagedAgentsAlwaysAllowPolicyParam()`。作為聯集成員時，指向空結構的指標也可以運作：`OfAlwaysAllow: &anthropic.BetaManagedAgentsAlwaysAllowPolicyParam{}`。 在回應中，請與字串比較： ```go // 之前 switch event.Type { case string(anthropic.BetaManagedAgentsAgentMessageEventTypeAgentMessage): } // 之後 switch event.Type { case "agent.message": } ``` 您以已移除型別之一宣告的變數、欄位或參數，請改用該欄位的新型別，例如 `constant.AgentMessage`。`constant.ValueOf[constant.AgentMessage]()` 會傳回其值。 聯集建構函式會隨欄位一起變更。以下五個失去了其 `type_` 引數： * `BetaManagedAgentsEventParamsOfUserToolConfirmation` * `BetaManagedAgentsEventParamsOfUserDefineOutcome` * `BetaManagedAgentsDeploymentInitialEventParamsOfUserDefineOutcome` * `BetaManagedAgentsMultiagentRosterEntryParamsOfBetaManagedAgentsAgents` * `BetaManagedAgentsMultiagentRosterEntryParamsOfBetaManagedAgentsAdvisors` 以下四個沒有其他引數，因此已被移除。請將聯集的欄位設為指向空結構的指標，例如 `BetaManagedAgentsEventParamsUnion{OfUserInterrupt: &anthropic.BetaManagedAgentsUserInterruptEventParams{}}`： * `BetaManagedAgentsEventParamsOfUserInterrupt` * `BetaManagedAgentsMultiagentRosterEntryParamsOfBetaManagedAgentsMultiagentSelfs` * `BetaManagedAgentsCredentialNetworkingParamsOfUnrestricted` * `BetaOutputBehaviorParamOfCreateNew` 這類列舉的一個範例是巢狀類別 `BetaManagedAgentsTextBlock.Type`，其唯一成員為 `TEXT`。它們幾乎都是 `com.anthropic.models.beta` 下某個類別的 `type`：`agents`、`deploymentruns`、`deployments`、`dreams`、`environments`、`memorystores`、`sessions`、`userprofiles` 和 `vaults`。在 v3 中，這些欄位是由 builder 填入的 `JsonValue`，就像 `TextBlockParam` 的欄位原本的做法一樣。選用欄位（例如 `BetaManagedAgentsBashToolConfigParams` 的 `type`）會保留其列舉。 建立物件時，請刪除該呼叫： ```java // 之前 BetaManagedAgentsTextBlock block = BetaManagedAgentsTextBlock.builder() .type(BetaManagedAgentsTextBlock.Type.TEXT) .text("Hello Claude!") .build(); // 之後 BetaManagedAgentsTextBlock block = BetaManagedAgentsTextBlock.builder() .text("Hello Claude!") .build(); ``` 只剩下一個必要欄位的類別也會新增一個接受該欄位的工廠方法，因此 `BetaManagedAgentsTextBlock.of("Hello Claude!")` 也可以運作。沒有剩下任何必要欄位的類別會失去 `of(type)`，其聯集也會失去接受該列舉的多載，例如 `ofAlwaysAllow(type)`。請以 `BetaManagedAgentsAlwaysAllowPolicy.builder().build()` 建立它。 讀取時，`type()` 已被移除，而 `_type()` 會傳回 `com.anthropic.core.JsonValue`： ```java // 之前 if (message.type().equals(BetaManagedAgentsAgentMessageEvent.Type.AGENT_MESSAGE)) {} // 之後 if (message._type().equals(JsonValue.from("agent.message"))) {} ``` 若要區分聯集的各個變體，請繼續使用其 `is*()` 和 `as*()` 方法及其 visitor，這些都沒有變更。 這類列舉 case 的一個範例是 `Anthropic\Beta\Sessions\Events\ManagedAgentsTextBlock\Type::TEXT`。它們幾乎都是 `Anthropic\Beta` 下某個 Managed Agents 類別的 `type`。這些屬性現在是以該唯一值作為預設值的字串，就像 `Anthropic\Messages\TextBlockParam` 的 `type` 原本的做法一樣。選用屬性（例如 `Anthropic\Beta\Environments\BetaPackages` 的 `type`）會保留其列舉。 `with()` 不再接受 `type`。請將其移除：對於殘留的 `type:`，PHP 會擲出「Unknown named parameter」，而在位置呼叫中，其後的引數會往前移一位。 ```php // 修改前 ManagedAgentsTextBlock::with(text: 'Hello Claude!', type: Type::TEXT); // 修改後 ManagedAgentsTextBlock::with(text: 'Hello Claude!'); ``` 在您與列舉 case 比較的地方，請改為與字串比較： ```php // 之前 $event->type === Type::AGENT_MESSAGE->value; // 之後 $event->type === 'agent.message'; ``` * `withType()` 以及 `$client->beta->sessions->resources->add()` 的 `type` 引數現在只接受字串。在 `add()` 中，它預設為 `'file'`，因此您可以省略它。 * 您以陣列撰寫的請求沒有變更，仍然需要其 `'type'`。 這類列舉常數的一個範例是 `Anthropic::Beta::Sessions::BetaManagedAgentsTextBlock::Type::TEXT`。它們幾乎都是 `Anthropic::Beta` 下某個 Managed Agents 類別的 `type`。在 v2 中，這些欄位被宣告為常數，就像 `Anthropic::TextBlockParam` 的 `type` 原本的做法一樣。選用欄位（例如 `Anthropic::Beta::BetaManagedAgentsGlobToolConfigParams` 的 `type`）會保留其列舉。 請將已移除的常數替換為其 symbol： ```ruby # 之前 event.type == Anthropic::Beta::Sessions::BetaManagedAgentsAgentMessageEvent::Type::AGENT_MESSAGE # 之後 event.type == :"agent.message" ``` 您以 hash 撰寫的請求沒有變更，仍然需要其 `type`： ```ruby client.beta.sessions.events.send_( session.id, events: [{type: "user.message", content: [{type: "text", text: "Hello Claude!"}]}] ) ``` 建立模型實例時，`type:` 現在有預設值，因此您可以省略它：`Anthropic::Beta::Sessions::BetaManagedAgentsTextBlock.new(text: "Hello Claude!")`。`client.beta.sessions.resources.add` 的 `type:` 關鍵字也是如此。 如果您使用 Sorbet 進行型別檢查，這些模組的 `Type::OrSymbol` 和 `Type::TaggedSymbol` 別名也隨之移除，而這些欄位是 `Symbol`。`OrSymbol` 也允許 `String`，因此 `.new(type: "text")` 不再通過型別檢查。請移除該關鍵字或傳遞 `:text`。在 RBS 中，每個類別的 `type_` 別名已被移除，而該欄位是字面值，例如 `:text`。 ### 已從 tool runner 中移除用戶端壓縮 這會影響 TypeScript 和 Ruby SDK。tool runner 中的「client-side compaction」（用戶端壓縮）已被移除，改用伺服器端壓縮，後者會在 API 內部摘要對話，而不是由用戶端發出額外的請求。 `compactionControl` 選項和 `@anthropic-ai/sdk/lib/tools/CompactionControl` 模組已被移除。該選項在 v0.129.0 中已停止運作，當時傳遞它會擲出 `AnthropicError`。它不在 params 型別中，因此 TypeScript 會將其回報為未知屬性。 若要在達到 token 閾值時繼續自動壓縮： ```typescript // 之前 const runner = client.beta.messages.toolRunner({ // ... compactionControl: { enabled: true, contextTokenThreshold: 100_000 } }); // 之後 const runner = client.beta.messages.toolRunner({ // ... betas: ["compact-2026-01-12"], context_management: { edits: [{ type: "compact_20260112", trigger: { type: "input_tokens", value: 100_000 } }] } }); ``` 若要自行決定何時壓縮對話，請呼叫 [`runner.compactBeforeNextTurn()`](https://github.com/anthropics/anthropic-sdk-typescript/blob/main/helpers.md#compaction)。 `compaction_control:` 選項已被移除。它在 v1.74.0 中已停止運作，當時傳遞它會引發 `ArgumentError`。 若要在達到 token 閾值時繼續自動壓縮： ```ruby # 之前 runner = client.beta.messages.tool_runner( # ... compaction_control: {enabled: true, context_token_threshold: 100_000} ) # 之後 runner = client.beta.messages.tool_runner( # ... betas: ["compact-2026-01-12"], context_management: { edits: [{type: :compact_20260112, trigger: {type: :input_tokens, value: 100_000}}] } ) ``` 若要自行決定何時壓縮對話，請在 runner 上呼叫 [`#compact_before_next_turn`](https://github.com/anthropics/anthropic-sdk-ruby/blob/main/helpers.md#compact_before_next_turn---compact-the-conversation)。 觸發閾值必須至少為 50,000 個 token。如需其他選項（`pause_after_compaction`、自訂 `instructions`），請參閱[壓縮](https://platform.claude.com/docs/zh-TW/build-with-claude/compaction-threshold)。 ### Text Completions 已被移除 舊版 Text Completions API 已從 TypeScript、Go、Java 和 Ruby SDK 以及 CLI 中移除。較新的模型和功能不支援它。請改用 [Messages API](https://platform.claude.com/docs/zh-TW/api/messages)。 `ant completions create` 命令已被移除。 ```bash # 之前 ant completions create \ --model "$MODEL" \ --max-tokens-to-sample 1024 \ --prompt $'\n\nHuman: Hello, Claude\n\nAssistant:' # 之後 ant messages create \ --model "$MODEL" \ --max-tokens 1024 \ --message '{role: user, content: "Hello, Claude"}' ``` 回覆文字從 `completion` 欄位移至 `content.0.text`，因此原本傳遞 `--transform completion` 的指令碼請改為傳遞 `--transform content.0.text`。 `ant messages create` 也接受 `--stream`，但其事件的結構不同：文字會出現在 `content_block_delta` 事件的 `delta.text` 中，因此 `--transform content.0.text` 不適用於串流。 `client.completions` 已被移除，連同 `Completions` 資源類別以及 `Completion`、`CompletionCreateParams`、`CompletionCreateParamsNonStreaming` 和 `CompletionCreateParamsStreaming` 型別。`AnthropicBedrock` 也不再有 `completions` 屬性。僅供 Text Completions 提示使用的 `HUMAN_PROMPT` 和 `AI_PROMPT` 常數也已被移除，無論是作為匯出項目還是作為用戶端的靜態屬性。 ```typescript // 之前 const completion = await client.completions.create({ model, max_tokens_to_sample: 1024, prompt: "\n\nHuman: Hello, Claude\n\nAssistant:" }); console.log(completion.completion); // 之後 const message = await client.messages.create({ model, max_tokens: 1024, messages: [{ role: "user", content: "Hello, Claude" }] }); console.log(message.content); ``` `client.completions.create({ ..., stream: true })` 變為 `client.messages.create({ ..., stream: true })` 或 `client.messages.stream({ ... })`。 `client.Completions` 已被移除，連同 `CompletionService`、`NewCompletionService`、`CompletionNewParams` 和 `Completion`。`aws.Client` 也不再有 `Completions` 欄位。`bedrock.DefaultEndpoints` 不再列出 `/v1/complete`。 ```go // 修改前 completion, err := client.Completions.New(ctx, anthropic.CompletionNewParams{ Model: model, MaxTokensToSample: 1024, Prompt: "\n\nHuman: Hello, Claude\n\nAssistant:", }) fmt.Println(completion.Completion) // 修改後 message, err := client.Messages.New(ctx, anthropic.MessageNewParams{ Model: model, MaxTokens: 1024, Messages: []anthropic.MessageParam{ anthropic.NewUserMessage(anthropic.NewTextBlock("Hello, Claude")), }, }) fmt.Println(message.Content[0].Text) ``` `client.Completions.NewStreaming` 變為 `client.Messages.NewStreaming`。 `client.completions()` 已從 `AnthropicClient` 和 `AnthropicClientAsync` 中移除，連同 `CompletionService`、`CompletionServiceAsync` 以及 `com.anthropic.models.completions` 套件（`CompletionCreateParams` 和 `Completion`）。 ```java // 之前 CompletionCreateParams params = CompletionCreateParams.builder() .model(model) .maxTokensToSample(1024) .prompt("\n\nHuman: Hello, Claude\n\nAssistant:") .build(); System.out.println(client.completions().create(params).completion()); // 之後 MessageCreateParams params = MessageCreateParams.builder() .model(model) .maxTokens(1024) .addUserMessage("Hello, Claude") .build(); client.messages().create(params).content().stream() .flatMap(contentBlock -> contentBlock.text().stream()) .forEach(textBlock -> System.out.println(textBlock.text())); ``` `client.completions().createStreaming` 變為 `client.messages().createStreaming`。 `client.completions` 已被移除，連同 `Anthropic::Resources::Completions`、`Anthropic::CompletionCreateParams` 和 `Anthropic::Completion`。`Anthropic::BedrockClient` 也不再有 `completions` reader。在 `Anthropic::BedrockMantleClient` 和 `Anthropic::GoogleCloudClient` 上，原本 `completions` 會引發 `NotImplementedError`，現在該方法已不存在。 ```ruby # 之前 completion = client.completions.create( model: model, max_tokens_to_sample: 1024, prompt: "\n\nHuman: Hello, Claude\n\nAssistant:" ) puts(completion.completion) # 之後 message = client.messages.create( model: model, max_tokens: 1024, messages: [{role: "user", content: "Hello, Claude"}] ) puts(message.content) ``` `client.completions.create_streaming` 變為 `client.messages.stream`。 ### 已從非 beta 的 Models 方法中移除 `betas` 非 beta 的 Models 方法不再接受 `betas` (csharp, go: `Betas`; java: `.addBeta()`)，而 `ant models` 命令也不再接受 `--beta`。若要傳送 beta 標頭，請在 `client.beta.models` (csharp, go: `client.Beta.Models`; java: `client.beta().models()`; php: `$client->beta->models`) 上呼叫相同的方法，或在 CLI 中使用 `ant beta:models`。在 SDK 中，這些方法會傳回 `BetaModelInfo` (ruby: `Anthropic::Beta::BetaModelInfo`)，而非 beta 的方法則傳回 `ModelInfo` (ruby: `Anthropic::ModelInfo`)。 ```bash # 之前 ant models list --beta "$BETA" # 之後 ant beta:models list --beta "$BETA" ``` `client.models.retrieve()` 和 `client.models.list()` 不再接受 `betas`（傳遞它會導致 `TypeError`，且型別檢查器會標記它），而 `anthropic.types.ModelListParams` 也不再有 `betas` 鍵。 ```python # 之前 page = client.models.list(betas=[beta]) # 之後 page = client.beta.models.list(betas=[beta]) ``` `Anthropic.ModelRetrieveParams` 和 `Anthropic.ModelListParams` 不再有 `betas` 屬性。 ```typescript // 之前 const page = await client.models.list({ betas: [beta] }); // 之後 const page = await client.beta.models.list({ betas: [beta] }); ``` `Anthropic.Models.Models` 中的 `ModelRetrieveParams` 和 `ModelListParams` 不再有 `Betas` 屬性。`client.Beta.Models` 上的方法接受 `Anthropic.Models.Beta.Models` 中同名的類別。 ```csharp // 之前 using Anthropic.Models.Models; var page = await client.Models.List(new ModelListParams { Betas = [beta] }); // 之後 using Anthropic.Models.Beta.Models; var page = await client.Beta.Models.List(new ModelListParams { Betas = [beta] }); ``` `ModelGetParams` 和 `ModelListParams` 不再有 `Betas` 欄位。 ```go // 之前 page, err := client.Models.List(ctx, anthropic.ModelListParams{ Betas: []anthropic.AnthropicBeta{beta}, }) // 之後 page, err := client.Beta.Models.List(ctx, anthropic.BetaModelListParams{ Betas: []anthropic.AnthropicBeta{beta}, }) ``` `com.anthropic.models.models` 中的 `ModelRetrieveParams` 和 `ModelListParams` 不再有 `betas()`，其 builder 也不再有 `betas` 和 `addBeta`。`client.beta().models()` 上的方法接受 `com.anthropic.models.beta.models` 中同名的類別。 ```java // 之前 import com.anthropic.models.models.ModelListPage; import com.anthropic.models.models.ModelListParams; ModelListPage page = client.models().list(ModelListParams.builder().addBeta(beta).build()); // 之後 import com.anthropic.models.beta.models.ModelListPage; import com.anthropic.models.beta.models.ModelListParams; ModelListPage page = client.beta().models().list(ModelListParams.builder().addBeta(beta).build()); ``` `$client->models->retrieve()` 和 `$client->models->list()` 不再接受 `betas`（傳遞它會擲出 `Error: Unknown named parameter $betas`），而 `Anthropic\Models\ModelRetrieveParams` 和 `Anthropic\Models\ModelListParams` 也不再有 `betas` 屬性。 ```php // 修改前 $page = $client->models->list(betas: [$beta]); // 修改後 $page = $client->beta->models->list(betas: [$beta]); ``` 如果您以位置傳遞引數，在這兩個方法中，`workspaceID` 和 `requestOptions` 都會各往前移一位。 `client.models.retrieve` 和 `client.models.list` 不再接受 `betas:`，而 `Anthropic::ModelRetrieveParams` 和 `Anthropic::ModelListParams` 也不再有 `betas` 欄位。 ```ruby # 之前 page = client.models.list(betas: [beta]) # 之後 page = client.beta.models.list(betas: [beta]) ``` 將 `betas:` 傳遞給 `client.models` 不會引發錯誤，但它不再設定 `anthropic-beta` 標頭。 ### API 金鑰以 `Authorization: Bearer` 傳送 SDK 和 CLI 會以 `Authorization: Bearer ` 傳送您的 API 金鑰，而不是放在 `X-Api-Key` 標頭中，因此請將任何讀取或設定 `X-Api-Key` 的代理或閘道改為使用 `Authorization`，或[自行在 `X-Api-Key` 中傳送金鑰](https://platform.claude.com/docs/zh-TW/api/migration-2026-10-21#sdk-proxy-x-api-key)。Claude API 接受放在任一標頭中的金鑰，因此直接與 API 通訊的程式無需變更。 ```text wrap # Before X-Api-Key: # After Authorization: Bearer ``` 這適用於 `ANTHROPIC_API_KEY` 中的金鑰，以及透過管道傳給 `--api-key-stdin` 的金鑰。 使用 `--debug` 時，請求日誌現在會在原本顯示 `X-Api-Key: ` 的地方顯示 `Authorization: Bearer `。 `Authorization` 是 `auth_token` 原本就使用的標頭。 這適用於 `Anthropic` 和 `AsyncAnthropic` 的 `api_key` 引數和 `ANTHROPIC_API_KEY` 環境變數，以及 `AnthropicAWS` 的 `api_key` 和 `ANTHROPIC_AWS_API_KEY`。`AnthropicFoundry` 仍以 `x-api-key` 傳送其金鑰，而 `AnthropicBedrockMantle` 原本就傳送 bearer token。 `Authorization` 是 `authToken` 選項原本就使用的標頭。 這適用於 `apiKey` 選項、`ANTHROPIC_API_KEY` 環境變數，以及 `@anthropic-ai/aws-sdk` 中的 `apiKey` 和 `ANTHROPIC_AWS_API_KEY`。`@anthropic-ai/foundry-sdk` 中的 `apiKey` 仍以 `X-Api-Key` 送出，而 `@anthropic-ai/bedrock-sdk` 中的 `apiKey` 原本就是 bearer token。 從 `x-api-key` 請求標頭讀取金鑰的中介軟體或自訂 `fetch` 需要改為讀取 `authorization`，其中金鑰位於 `Bearer `之後。 `Authorization` 是 `AuthToken` 原本就使用的標頭。 這適用於 `AnthropicClient` 和 `ClientOptions` 上的 `ApiKey`，以及 `ANTHROPIC_API_KEY` 環境變數。在依賴 v13 的 `Anthropic.Aws` 版本中，它也適用於 `AwsClientOptions` 中的 `ApiKey` 以及 `ANTHROPIC_AWS_API_KEY`。`AnthropicFoundryApiKeyCredentials` 仍以 `x-api-key` 傳送其金鑰，而 `MantleAwsClientOptions` 中的 `ApiKey` 原本就是 bearer token。 這適用於 `option.WithAPIKey`、`ANTHROPIC_API_KEY` 環境變數，以及 `aws.ClientConfig` 中的 `APIKey`（或 `ANTHROPIC_AWS_API_KEY`）。`foundry.ClientConfig` 中的 `APIKey`（或 `ANTHROPIC_FOUNDRY_API_KEY`）仍以 `X-Api-Key` 送出，而 `bedrock.MantleClientConfig` 中的 `APIKey` 原本就是 bearer token。 `Authorization` 是 `authToken` 原本就使用的標頭。 這適用於 `AnthropicOkHttpClient`、`AnthropicOkHttpClientAsync` 和 `AnthropicBackend` builder 上的 `apiKey`、`ANTHROPIC_API_KEY` 環境變數，以及 `anthropic.apiKey` 系統屬性。`FoundryBackend` builder 上的 `apiKey` 仍以 `x-api-key` 送出。`AwsBackend`、`BedrockBackend` 和 `BedrockMantleBackend` builder 上的 `apiKey` 原本就是 bearer token。 攔截器現在會在 `Authorization` 而非 `X-Api-Key` 中看到金鑰。 `Authorization` 是 `authToken` 原本就使用的標頭。 這適用於 `Anthropic\Client` 的 `apiKey` 引數和 `ANTHROPIC_API_KEY` 環境變數，以及 `Anthropic\Aws\Client` 的 `apiKey` 和 `ANTHROPIC_AWS_API_KEY`。`Anthropic\Foundry\Client` 仍以 `x-api-key` 傳送其金鑰，而 `Anthropic\Bedrock\MantleClient` 原本就傳送 bearer token。 `Authorization` 是 `auth_token:` 原本就使用的標頭。 這適用於 `Anthropic::Client` 的 `api_key:` 引數和 `ANTHROPIC_API_KEY` 環境變數，以及 `Anthropic::AWSClient` 的 `api_key:` 和 `ANTHROPIC_AWS_API_KEY`。`Anthropic::BedrockMantleClient` 原本就傳送 bearer token。 SDK 在跟隨重新導向至另一個來源時會捨棄 `Authorization`，這包括在同一主機上從 `http` 重新導向至 `https`。現在金鑰在這種情況下也會被捨棄。 #### 如果代理或閘道讀取 `X-Api-Key` 如果 `--base-url` 或 `ANTHROPIC_BASE_URL` 將 `ant` 指向讀取 `X-Api-Key` 的代理或閘道，請將其改為從 `Authorization` 讀取金鑰。`ant` 沒有可用來新增自訂標頭的旗標或環境變數，因此它無法傳送 `X-Api-Key`。 請在 HTTP 用戶端上使用 `auth` 函式將金鑰移回。它會在用戶端傳送的每個請求上執行，包括重試： ```python import httpx2 from anthropic import Anthropic, DefaultHttpxClient def send_x_api_key(request: httpx2.Request) -> httpx2.Request: if request.headers.get("Authorization") == f"Bearer {api_key}": del request.headers["Authorization"] request.headers["X-Api-Key"] = api_key return request client = Anthropic(api_key=api_key, http_client=DefaultHttpxClient(auth=send_x_api_key)) ``` `AsyncAnthropic` 接受相同的函式，寫法為 `http_client=DefaultAsyncHttpxClient(auth=send_x_api_key)`。 請自行設定標頭。`Authorization: null` 也會阻止金鑰從該處送出： ```typescript const client = new Anthropic({ apiKey, defaultHeaders: { "X-Api-Key": apiKey, Authorization: null } }); ``` 如果代理會加入憑證而您的用戶端沒有憑證，v0 允許您在 `defaultHeaders` 中以 `"X-Api-Key": null` 或 `Authorization: null` 表示這一點。v1 只接受 `Authorization: null`。 environment work poller 和 worker 會被賦予自己的金鑰，因此它們會在自己的請求中省略 `X-Api-Key` 和 `Authorization` 預設標頭。 請使用 `ExtraHeaders` 自行設定標頭。將 `ApiKey` 和 `AuthToken` 設為 `null` 也會阻止在 `ANTHROPIC_API_KEY` 或 `ANTHROPIC_AUTH_TOKEN` 中找到的憑證被送出： ```csharp AnthropicClient client = new( new ClientOptions { ApiKey = null, AuthToken = null, ExtraHeaders = new Dictionary { ["X-Api-Key"] = apiKey }, } ); ``` 請自行設定標頭。`option.WithHeaderDel` 也會阻止在 `ANTHROPIC_API_KEY` 中找到的金鑰被送出： ```go client := anthropic.NewClient( option.WithHeader("X-Api-Key", apiKey), option.WithHeaderDel("Authorization"), ) ``` `environments.WorkPoller` 和 `environments.EnvironmentWorker` 會被賦予自己的金鑰，因此它們會在自己的請求中省略手動設定的 `X-Api-Key`。 請自行設定標頭，而不是呼叫 `apiKey`： ```java AnthropicClient client = AnthropicOkHttpClient.builder() .putHeader("X-Api-Key", apiKey) .build(); ``` 請使用中介軟體將金鑰移回： ```php use Anthropic\Client; use Psr\Http\Message\RequestInterface; use Psr\Http\Message\ResponseInterface; $sendXApiKey = fn (RequestInterface $request, callable $next): ResponseInterface => $next( $request->withoutHeader('Authorization')->withHeader('X-Api-Key', $apiKey) ); $client = new Client(apiKey: $apiKey, requestOptions: ['middleware' => [$sendXApiKey]]); ``` 請勿為此使用用戶端的 `extraHeaders`。擁有自己 `extraHeaders` 的請求會取代用戶端的設定，而 `$client->beta` 下每個需要 beta 標頭的端點都有自己的 `extraHeaders`。 請使用中介軟體將金鑰移回： ```ruby send_x_api_key = lambda do |req, nxt| next nxt.call(req) unless req.headers["authorization"] == "Bearer #{api_key}" nxt.call(req.with(headers: {**req.headers.except("authorization"), "x-api-key" => api_key})) end client = Anthropic::Client.new(api_key: api_key, middleware: send_x_api_key) ``` 第一行會在請求未攜帶金鑰時不做處理，例如被重新導向至另一個來源的請求。 `Anthropic::AWSClient` 不接受 `middleware:` 引數。請改為在每個請求中傳遞中介軟體，寫法為 `request_options: {middleware: send_x_api_key}`。 #### 如果您曾在請求上設定或移除 `X-Api-Key` 這會影響 Python、TypeScript、Go、PHP 和 Ruby SDK。 如果您曾移除 `X-Api-Key` 以讓請求只傳送 auth token，請刪除該程式碼而不是修改它，因為移除 `Authorization` 會移除該 token。[一個用戶端只持有一個憑證](https://platform.claude.com/docs/zh-TW/api/migration-2026-10-21#sdk-one-credential)，因此請確保該憑證是 token：如果程式碼中未傳入任何憑證，且同時設定了 `ANTHROPIC_API_KEY` 和 `ANTHROPIC_AUTH_TOKEN`，用戶端會使用金鑰。 傳遞 `extra_headers={"X-Api-Key": omit}` 以讓請求不帶金鑰的程式碼不再有此效果。請改為傳遞 `extra_headers={"Authorization": omit}`。 `extra_headers={"X-Api-Key": other_key}` 不再取代用戶端的金鑰：兩個金鑰都會被送出。若要在單一請求中傳送另一個金鑰，請傳遞 `extra_headers={"Authorization": f"Bearer {other_key}"}`。 請求選項中的 `headers: { "X-Api-Key": otherKey }` 不再取代用戶端的金鑰：兩個金鑰都會被送出。若要在單一請求中傳送另一個金鑰，請傳遞 ``headers: { Authorization: `Bearer $\{otherKey}` }``。 `option.WithHeaderDel("X-Api-Key")` 不再讓請求不帶金鑰。請改為刪除 `Authorization`： ```go // 修改前 client.Messages.New(ctx, params, option.WithHeaderDel("X-Api-Key")) // 修改後 client.Messages.New(ctx, params, option.WithHeaderDel("Authorization")) ``` `option.WithHeader("X-Api-Key", otherKey)` 不再取代用戶端的金鑰：兩個金鑰都會被送出。若要在單一請求中傳送另一個金鑰，請傳遞 `option.WithAPIKey(otherKey)`。 `'extraHeaders' => ['X-Api-Key' => null]` 不再讓請求不帶金鑰。若要傳送不含憑證的請求，請改為將 `Authorization` 設為 `null`，或者如果您是對整個用戶端這樣做，請在中介軟體中將其移除。 `'extraHeaders' => ['X-Api-Key' => $otherKey]` 不再取代用戶端的金鑰：兩個金鑰都會被送出。若要在單一請求中傳送另一個金鑰，請將 `Authorization` 設為 `"Bearer {$otherKey}"`。 `extra_headers: {"x-api-key" => nil}` 不再讓請求不帶金鑰。請改為將 `"authorization"` 設為 `nil`。若要在單一請求中傳送另一個金鑰，請將 `"authorization"` 設為 `"Bearer #{other_key}"`，而不是設定 `"x-api-key"`。 ### 用戶端只持有一個憑證 API 金鑰與驗證權杖現在共用同一個標頭，因此 SDK 用戶端只持有一個憑證。若未在程式碼中傳入任何憑證，則會依照[憑證優先順序](https://platform.claude.com/docs/zh-TW/manage-claude/wif-reference#credential-precedence)的順序處理。 在 v1 中，當用戶端同時擁有 API 金鑰與驗證權杖時，會將兩者都送出，各自放在自己的標頭中。憑證為 `api_key`、`auth_token`、`credentials`、`config` 或 `profile` 其中之一。 * **最多只傳入一個。** 在建構函式中，或在單次 `copy()` 或 `with_options()` 呼叫中傳入兩個以上，會引發 `ValueError`。`None` 不計入。v1 引發的是 `TypeError`，且僅在 `credentials`、`config` 與 `profile` 中傳入兩個時才會引發。 * **您傳入的那一個就是唯一的憑證。** 與 v1 相同，用戶端不會在環境或磁碟上尋找其他憑證。 * **未傳入任何憑證時，只會使用下列項目中第一個已設定的項目：** `ANTHROPIC_API_KEY`、`ANTHROPIC_AUTH_TOKEN`、`ANTHROPIC_PROFILE` 所指定的設定檔、workload identity federation（工作負載身分聯合）變數、磁碟上的作用中設定檔（即 `active_config` 檔案所指定的設定檔，否則為 `default`）。當前兩者都已設定時，用戶端會記錄一次警告。在 v1 中，當設定了 `ANTHROPIC_CONFIG_DIR` 或存在 `active_config` 檔案時，作用中設定檔的優先順序高於聯合變數；若要繼續使用它，請設定 `ANTHROPIC_PROFILE`。 * **`copy()` 與 `with_options()` 會取代。** 您傳入的憑證會取代用戶端自身的憑證，無論兩者各是哪一種。來自舊憑證之 config 或設定檔的基礎 URL 與標頭會隨之移除，並改用新憑證的設定。您自行傳入的基礎 URL 則會保留。 ```python client = Anthropic(api_key=key, auth_token=token) # 之前：會傳送 `X-Api-Key: ` 與 `Authorization: Bearer ` # 之後：引發 `ValueError` ``` 平台用戶端保有各自的規則。`AnthropicAWS` 可同時接受 `auth_token` 與 `api_key` 而不會出錯，並會送出金鑰。 [`_client.py`](https://github.com/anthropics/anthropic-sdk-python/blob/main/src/anthropic/_client.py) 中 `Anthropic.__init__` 與 `Anthropic.copy` 的 docstring 提供了詳細資訊。 如果您依賴同時送出兩者，例如將權杖用於閘道、將金鑰用於閘道後方的 API，請將權杖作為 `auth_token` 傳入，並在 `default_headers` 中設定 `X-Api-Key`。請讓閘道在轉送請求之前移除其 `Authorization` 標頭。Claude API 預期每個請求只有一個憑證。 在 v0 中，同時擁有 API 金鑰與驗證權杖的用戶端會將兩者都送出，各自放在自己的標頭中。憑證為 `apiKey`、`authToken`、`credentials`、`config` 或 `profile` 其中之一。 * **最多只傳入一個。** 在 `new Anthropic()` 中，或在單次 `withOptions()` 呼叫中傳入兩個以上，會擲出 `TypeError`。`null` 與 `undefined` 不計入。 * **您傳入的那一個就是唯一的憑證。** 用戶端不會在環境或磁碟上尋找其他憑證。 * **未傳入任何憑證時，會使用下列項目中的第一個：** `ANTHROPIC_API_KEY`、`ANTHROPIC_AUTH_TOKEN`、`ANTHROPIC_PROFILE` 所指定的設定檔、workload identity federation 變數、磁碟上的作用中設定檔（即 `active_config` 檔案所指定的設定檔，否則為 `default`）。當前兩者都已設定時，用戶端會記錄一次警告。在 v0 中，作用中設定檔排在聯合變數之前。在 v0 中，指定了不存在之設定檔的 `ANTHROPIC_PROFILE` 會被略過，現在則會在第一個請求時擲出 `AnthropicError`。不帶引數的 `loadConfig()` 遵循相同的順序，並擲出相同的錯誤。 * **`withOptions` 會取代。** 您傳入的憑證會取代所複製之用戶端的憑證，因此 `client.withOptions({ authToken })` 不再需要在旁邊加上 `apiKey: null`。 * **平台用戶端只接受其平台的憑證。** AWS、Bedrock 與 Foundry 用戶端以及 `AnthropicVertex`，對於它們不用來驗證的憑證選項會擲出 `AnthropicError`，與 `AnthropicGoogleCloud` 原本的行為相同。在 AWS 與 Bedrock 用戶端上，`apiKey: null` 現在會清除金鑰，因此用戶端會以 AWS 憑證簽署。`AnthropicBedrock` 將其金鑰保存在 `client.apiKey` 中，而 v0 則保存在 `client.authToken` 中。 ```typescript // 之前：會傳送 API 金鑰並忽略 `credentials` const client = new Anthropic({ apiKey, credentials }); // 之後：上一行會擲出 TypeError const client = new Anthropic({ credentials }); ``` [`ClientOptions`](https://github.com/anthropics/anthropic-sdk-typescript/blob/main/src/client.ts) 上的文件註解說明了每個選項的行為，而上述各平台用戶端建構函式上的文件註解則列出了它所拒絕的選項。 如果您依賴同時送出兩者，例如將權杖用於閘道、將金鑰用於閘道後方的 API，請在 `defaultHeaders` 中設定 `X-Api-Key` 並保留 `authToken`。請讓閘道在轉送請求之前移除其 `Authorization` 標頭。Claude API 預期每個請求只有一個憑證。 在 v12 中，同時擁有 API 金鑰與驗證權杖的用戶端會將兩者都送出，各自放在自己的標頭中。憑證為 `ApiKey`、`AuthToken` 或 `ClientOptions.Credentials` 其中之一。 * **傳入兩個會產生錯誤。** 設定第二個會擲出 `ArgumentException`。`null` 不計入，因此若要在您自行建立的 `ClientOptions` 中替換憑證，請先將舊的設為 `null`。 * **傳入一個時會使用它並忽略環境。** 不會讀取任何憑證環境變數或磁碟上的設定檔。同樣地，當設定了 `ANTHROPIC_API_KEY` 或 `ANTHROPIC_AUTH_TOKEN` 時，`AnthropicCredentials.Resolve(profile: "name")` 現在會傳回該設定檔的憑證。 * **未傳入任何憑證時，會使用環境中第一個符合的項目：** `ANTHROPIC_API_KEY`、`ANTHROPIC_AUTH_TOKEN`、`ANTHROPIC_PROFILE`、workload identity federation 變數，然後是磁碟上的作用中設定檔。空的 `ANTHROPIC_API_KEY` 或 `ANTHROPIC_AUTH_TOKEN` 視為未設定。當前兩者都已設定時，會向 stderr 輸出一次警告。用戶端會在首次使用時才進行查找，因此不存在的 `ANTHROPIC_PROFILE` 現在會在第一個請求時擲出錯誤，而非在建構函式中。 * **`WithOptions` 會取代。** 您在修飾函式中傳入的憑證會取代用戶端的憑證，無論原本是哪一種，因此 `AuthToken = token` 不再需要在旁邊加上 `ApiKey = null`。未傳入任何憑證時，副本會保留用戶端的憑證、`BaseUrl` 與 `ExtraHeaders`，即使修飾函式傳回新的 `ClientOptions` 也是如此。 ```csharp // 之前：兩者都會送出，各自放在獨立的標頭中 AnthropicClient client = new() { ApiKey = apiKey, AuthToken = token }; // 之後：上一行會擲回 ArgumentException AnthropicClient client = new() { AuthToken = token }; ``` [`ClientOptions`](https://github.com/anthropics/anthropic-sdk-csharp/blob/main/src/Anthropic/Core/ClientOptions.cs) 上這三個屬性的 XML 文件提供了詳細資訊。 雲端平台用戶端會保留建立時所使用的憑證。Bedrock、Bedrock Mantle、Foundry、Google Cloud 與 AWS 用戶端以及 `AnthropicVertexClient` 會在您建立它們時決定驗證方式，且其中大多數會使用 `Authorization` 標頭進行驗證。這些套件中相依於 v13 的版本會忽略您透過 `WithOptions` 設定的 `ApiKey` 或 `AuthToken`。若要在 `AnthropicAwsClient` 中使用另一個金鑰，請在 `AwsClientOptions` 中設定 `ApiKey` 並建立新的用戶端。 如果您依賴同時送出兩者，例如將權杖用於閘道、將金鑰用於閘道後方的 API，請使用 `ExtraHeaders` 設定 `X-Api-Key` 並保留 `AuthToken`。請讓閘道在轉送請求之前移除其 `Authorization` 標頭。Claude API 預期每個請求只有一個憑證。 在 v1 中，同時擁有 API 金鑰與驗證權杖的用戶端會將兩者都送出，各自放在自己的標頭中。憑證來自 `option.WithAPIKey`、`option.WithAuthToken`、`option.WithConfig`、`option.WithProfile` 或 `option.WithFederationTokenProvider`。 * **將其中兩個傳給 `anthropic.NewClient` 會產生錯誤。** `NewClient` 不會傳回錯誤，因此用戶端發出的每個請求都會因此錯誤而失敗。`NewClient` 已經套用了 `anthropic.DefaultClientOptions()`，因此請勿再另外傳入其結果：否則它在環境中找到的憑證會被視為您傳入的憑證。 * **其中一個會被原樣使用。** 不會從環境或磁碟上的設定檔讀取任何憑證。在 v1 中，`ANTHROPIC_API_KEY` 與 `ANTHROPIC_AUTH_TOKEN` 的優先順序高於後三者。 * **若一個都沒有，則會使用下列項目中第一個已設定的項目，** 順序與 v1 相同：`ANTHROPIC_API_KEY`、`ANTHROPIC_AUTH_TOKEN`、`ANTHROPIC_PROFILE`、workload identity federation 變數、磁碟上的作用中設定檔。當前兩者都已設定時，SDK 會記錄一次警告。 * **在請求上傳入其中一個，會在該請求中取代用戶端的憑證，** 因此 `option.WithAuthToken` 不再需要在旁邊加上 `option.WithHeaderDel("X-Api-Key")`。 ```go // 之前：會送出 API 金鑰並記錄一則警告 client := anthropic.NewClient( option.WithAPIKey(apiKey), option.WithProfile("work"), ) // 之後：上述用戶端的每個請求都會失敗，因此請傳入您要使用的那一個 client := anthropic.NewClient(option.WithAPIKey(apiKey)) ``` v1 所記錄的警告已移除，因此原本用來抑制該警告的 `option.WithConfigQuiet`，現在的行為與 `option.WithConfig` 相同，並已被棄用。 [`client.go`](https://github.com/anthropics/anthropic-sdk-go/blob/main/client.go) 中 `anthropic.NewClient` 與 `anthropic.DefaultClientOptions` 的文件註解提供了詳細資訊。 如果您依賴同時送出兩者，例如將權杖用於閘道、將金鑰用於閘道後方的 API，請使用 `option.WithHeader` 設定 `X-Api-Key` 並保留 `option.WithAuthToken`。請讓閘道在轉送請求之前移除其 `Authorization` 標頭。Claude API 預期每個請求只有一個憑證。 `ANTHROPIC_CUSTOM_HEADERS` 與 `ANTHROPIC_WEBHOOK_SIGNING_KEY` 現在會套用到 `anthropic.NewClient` 所建立的每個用戶端。在 v1 中，只有在環境與磁碟上的設定檔都沒有憑證時才會讀取它們。 在 v2 中，同時擁有 API 金鑰與驗證權杖的用戶端會將兩者都送出，各自放在自己的標頭中。憑證為 `AnthropicOkHttpClient`、`AnthropicOkHttpClientAsync` 與 `AnthropicBackend` 建構器上的 `apiKey`、`authToken` 或 `configurationProvider` 其中之一。 * **最多只設定一個。** 若在同一個建構器上設定兩個，`build()` 會擲出一個指出它們名稱的 `IllegalStateException`。`null` 或空的 `Optional` 不計入。 * **您設定的那一個就是唯一的憑證。** 無論在之前或之後呼叫，`fromEnv()` 都不會從環境或磁碟上的設定檔取得憑證。在 v2 中，`fromEnv()` 找到的金鑰或權杖可能會一併送出，或取而代之。 * **未設定任何憑證時，`fromEnv()` 會使用它找到的下列項目中的第一個：** `ANTHROPIC_API_KEY`、`ANTHROPIC_AUTH_TOKEN`、`ANTHROPIC_PROFILE`、workload identity federation 變數、磁碟上的作用中設定檔。當前兩者都已設定時，會向 `System.err` 輸出一次警告。`anthropic.apiKey` 與 `anthropic.authToken` 系統屬性視同環境。空的金鑰或權杖，無論是在變數或系統屬性中，都視為未設定。在 v2 中，`fromEnv()` 會將空值當作金鑰或權杖使用。 ```java // 之前：兩者都會被送出。在 v3 中，build() 會擲出 IllegalStateException AnthropicClient client = AnthropicOkHttpClient.builder() .apiKey(apiKey) .authToken(authToken) .build(); // 之後 AnthropicClient client = AnthropicOkHttpClient.builder() .apiKey(apiKey) .build(); ``` 這些建構器上 `fromEnv()` 的文件提供了詳細資訊。 如果您依賴同時送出兩者，例如將權杖用於閘道、將金鑰用於閘道後方的 API，請自行設定這兩個標頭： ```java AnthropicClient client = AnthropicOkHttpClient.builder() .putHeader("Authorization", "Bearer " + gatewayToken) .putHeader("X-Api-Key", apiKey) .build(); ``` 請讓閘道在轉送請求之前移除其 `Authorization` 標頭。Claude API 預期每個請求只有一個憑證。 較早的版本在用戶端同時擁有 API 金鑰與驗證權杖時，會將兩者都送出，各自放在自己的標頭中。`Anthropic\Client` 只接受一個憑證，來自 `apiKey`、`authToken` 或 `credentials`： * 傳入其中一個以上會擲出 `\InvalidArgumentException`。只有 `null` 視為未傳入。空字串視為已傳入，因此 `new Client(apiKey: '')` 不會送出任何憑證。 * 傳入一個時會使用它，且不會從環境或磁碟上的設定檔讀取任何憑證。在設定了 `ANTHROPIC_API_KEY` 的情況下，`new Client(authToken: $token)` 會送出權杖。較早的版本會連同環境中的金鑰一起送出。 * 未傳入任何憑證時，會使用下列項目中第一個已設定的項目：`ANTHROPIC_API_KEY`、`ANTHROPIC_AUTH_TOKEN`、`ANTHROPIC_PROFILE` 所指定的設定檔、workload identity federation 變數、磁碟上的作用中設定檔（即 `active_config` 檔案所指定的設定檔，否則為 `default`）。較早的版本會在聯合變數之前使用作用中設定檔，且在沒有 `active_config` 檔案時不使用任何設定檔。它們也會略過指定了不存在或無效設定檔的 `ANTHROPIC_PROFILE`。對於這種情況，`new Client()` 現在會擲出 `Anthropic\Core\Exceptions\AnthropicException`。當 `ANTHROPIC_API_KEY` 與 `ANTHROPIC_AUTH_TOKEN` 都已設定時，用戶端會送出金鑰，且其 `authToken` 屬性為空。以此方式建立的第一個用戶端也會透過 `error_log()` 寫入一則警告，每個程序一次，在網頁伺服器上即代表每個請求一次：`Anthropic: ANTHROPIC_API_KEY and ANTHROPIC_AUTH_TOKEN are both set. Using ANTHROPIC_API_KEY.` 若要停止此警告，請取消設定您未使用的變數。 ```php // 之前：將金鑰以 X-Api-Key 傳送，並將權杖以 Authorization 傳送。 // 之後：擲出 "Pass at most one of `apiKey`, `authToken`, or `credentials`. Received `apiKey`, `authToken`." $client = new Client(apiKey: $key, authToken: $token); ``` 如果您依賴同時送出兩者，例如將權杖用於閘道、將金鑰用於閘道後方的 API，請將權杖作為 `authToken` 傳入，並在類似[如果代理或閘道讀取 `X-Api-Key`](https://platform.claude.com/docs/zh-TW/api/migration-2026-10-21#sdk-proxy-x-api-key) 中所示的中介軟體中加入 `X-Api-Key`，但不要呼叫 `withoutHeader`。請讓閘道在轉送請求之前移除其 `Authorization` 標頭。Claude API 預期每個請求只有一個憑證。 `Anthropic::Client.new` 的憑證引數為 `api_key:`、`auth_token:`、`credentials:` 與 `config:`。`nil` 引數視為未傳入。平台用戶端保有各自的規則。 * **傳入兩個以上：** `Anthropic::Client.new` 會引發 `ArgumentError`。較早的版本只在同時傳入 `credentials:` 與 `config:` 時引發錯誤，其他情況下則會在有金鑰時送出金鑰，否則送出權杖。 * **傳入一個：** 用戶端會使用它，且不會退而使用來自環境或磁碟上設定檔的憑證。 * **未傳入任何憑證：** 用戶端會使用它找到的下列項目中的第一個：`ANTHROPIC_API_KEY`、`ANTHROPIC_AUTH_TOKEN`、`ANTHROPIC_PROFILE`、workload identity federation 變數、磁碟上的作用中設定檔。順序沒有改變，但當 `ANTHROPIC_API_KEY` 與 `ANTHROPIC_AUTH_TOKEN` 都已設定時，`client.auth_token` 現在為 `nil`。空的 `ANTHROPIC_API_KEY` 或 `ANTHROPIC_AUTH_TOKEN` 現在視為未設定，而較早的版本會讓空的 `ANTHROPIC_API_KEY` 遮蔽權杖及其後的所有項目。 當未傳入任何憑證，且 `ANTHROPIC_API_KEY` 與 `ANTHROPIC_AUTH_TOKEN` 都已設定時，SDK 也會透過 `Kernel#warn` 在標準錯誤輸出上發出警告，每個程序一次：`Anthropic: ANTHROPIC_API_KEY and ANTHROPIC_AUTH_TOKEN are both set. Using ANTHROPIC_API_KEY.` 取消設定您未使用的變數即可使其不再出現。 ```ruby # 之前：會傳送金鑰並忽略權杖。 # 之後：ArgumentError, "Pass at most one of `api_key:`, `auth_token:`, `credentials:`, or `config:`. Received `api_key:`, `auth_token:`." Anthropic::Client.new(api_key: api_key, auth_token: auth_token) # 請只傳入您要傳送的那一個。 Anthropic::Client.new(api_key: api_key) ``` ### 單一 SDK 或 CLI 中的變更 以下每項變更各自只影響一個 SDK 或 CLI。 **`--api-key` 與 `--auth-token` 已移除。** `ant` 不再接受以旗標值形式提供的 API 金鑰或驗證權杖，因為命令列上的值會顯示在 shell 歷史記錄與程序清單中。自 v1.27.0 起，這兩個旗標都會印出棄用警告。仍傳入其中之一的命令會以 `flag provided but not defined` 停止。 | 已移除 | 改用 | | ---------------------- | -------------------------------------------------------- | | `--api-key ` | `ANTHROPIC_API_KEY`、`--api-key-stdin` 或 `ant auth login` | | `--auth-token ` | `ANTHROPIC_AUTH_TOKEN` 或 `--auth-token-stdin` | ```bash # 修改前 ant --api-key "$KEY" models list # 修改後，從環境變數讀取 export ANTHROPIC_API_KEY="$KEY" ant models list # 修改後，從密鑰管理工具讀取 op read op://vault/anthropic/api-key | ant --api-key-stdin models list ``` `--api-key-stdin` 與 `--auth-token-stdin` 會讀取全部的標準輸入，因此使用其中之一的命令會從旗標取得其請求主體。 `ant auth status`、`ant apply` 的首次執行提示，以及關於多個驗證來源的說明，現在將這些憑證稱為 `ANTHROPIC_API_KEY` 與 `ANTHROPIC_AUTH_TOKEN`，而先前印出的是 `--api-key / ANTHROPIC_API_KEY` 與 `--auth-token / ANTHROPIC_AUTH_TOKEN`。 **聯集的 `Type` 是列舉。** 在 v12 中，聯集類別的 `Type` 屬性，例如 `ContentBlock.Type` 或 `RawMessageStreamEvent.Type`，是 `JsonElement`。在 v13 中，它是 `ApiEnum`，其中 `T` 是一個新的列舉，每個變體各有一個成員，例如 `ContentBlockType`。少數聯集改以 `Name` 或 `Command` 區分，例如 `BetaMemoryTool20250818Command.Command`，這些屬性也以相同方式變更。變體類別的 `Type`，例如 `TextBlock.Type`，仍然是 `JsonElement`。 ```csharp // 之前 if (block.Type.GetString() == "tool_use") { } // 之後 if (block.Type.Value() == ContentBlockType.ToolUse) { } ``` `block.Type.Raw()` 會傳回字串，包括此版本 SDK 沒有對應列舉成員的字串。 **`IChatClient` 會忽略取樣選項。** `IChatClient` 轉接器（`AsIChatClient()`）現在會忽略 `ChatOptions.Temperature`、`ChatOptions.TopK` 與 `ChatOptions.TopP`。請參閱[取樣參數已移除](https://platform.claude.com/docs/zh-TW/api/migration-2026-10-21#sampling-parameters)。 **現在傳回 `Optional` 的 getter。** `AnthropicBackend` 上的 `apiKey()` 與 `authToken()` 現在傳回 `Optional`，與 `AwsBackend` 和 `BedrockMantleBackend` 上的 `apiKey()` 原本的行為相同。在 v2 中，它們各自傳回 `String`，當後端沒有該類憑證時為 `null`。 ```java // 之前 String apiKey = backend.apiKey(); if (apiKey != null) {} // 之後 Optional apiKey = backend.apiKey(); if (apiKey.isPresent()) {} ``` 下列 getter 現在也傳回 `Optional`。在 v2 中，它們各自傳回值本身，沒有值時為 `null`： * `BedrockBackend` 上的 `apiKey()` 與 `awsCredentialsProvider()` * `McpResourceFile` 上的 `filename()` 與 `mimeType()` * `CredentialSource` 上的 `detail()` * `HttpRequest` 上的 `body()` * `FoundryBackend` 上的 `resource()`，原為 `getResource()` * `RequestOptions` 上的 `responseValidation()`、`timeout()`、`followRedirects()`、`fallbackState()` 與 `openTelemetry()`，原為 `getResponseValidation()`、`getTimeout()`、`getFollowRedirects()`、`getFallbackState()` 與 `getOpenTelemetry()` ```java // 之前 String filename = file.filename(); if (filename != null) {} String resource = backend.getResource(); // 之後 Optional filename = file.filename(); if (filename.isPresent()) {} Optional resource = backend.resource(); ``` `FoundryBackend` 上的 `getBaseUrl()` 已移除。請呼叫 `baseUrl()`，它會傳回請求所送往的 URL。也就是您設定的基礎 URL，或由資源建構而成的 URL，且以 `/anthropic` 結尾。 `AnthropicBackend` 上的 `getBaseUrl()` 也已移除。請呼叫 `baseUrl()`，它會傳回相同的值。 **`HttpRequest` 需要基礎 URL。** 如果您自行建立 `HttpRequest`，例如在攔截器的測試中，請設定其基礎 URL。若未設定，`build()` 現在會擲出 `IllegalStateException`。在 v2 中，它會傳回一個 `baseUrl()` 為 `null` 的請求。SDK 所建立的請求原本就已具備基礎 URL。 ```java // 之前 HttpRequest request = HttpRequest.builder() .method(HttpMethod.GET) .build(); // 之後 HttpRequest request = HttpRequest.builder() .method(HttpMethod.GET) .baseUrl("https://api.anthropic.com") .build(); ``` `baseUrl()` 仍然傳回 `String`，且現在永遠不會是 `null`。在建構器上，`baseUrl(Optional)` 已移除，且 `baseUrl(String)` 不再接受 `null`。 **攔截器可看到 `anthropic-version`。** 用戶端現在會在攔截器執行之前加入預設的 `anthropic-version` 標頭。在 v2 中，後端是在攔截器之後才加入。如果您的攔截器設定了自己的版本，請呼叫 `replaceHeaders`，因為 `putHeader` 現在會加入第二個值： ```java // 之前 request.toBuilder().putHeader("anthropic-version", version).build(); // 之後 request.toBuilder().replaceHeaders("anthropic-version", version).build(); ``` **您傳入的列舉案例會以其值讀回。** `with()` 以及 `withAllowedCallers()` 等 setter 仍然接受列舉案例或其值。較早的版本會保留您傳入的案例原樣。v1 則保留案例的值，這正是屬性型別原本所宣告的。SDK 從回應建立的物件不會改變，SDK 送出的 JSON 也相同。如果您讀回某個屬性並將其與案例比較，比較結果現在會是 false 且不會擲出任何錯誤，因此請改與案例的值比較： ```php $tool = CodeExecutionTool20250825::with(allowedCallers: [AllowedCaller::DIRECT]); // 之前 in_array(AllowedCaller::DIRECT, $tool->allowedCallers, true); // 之後 in_array(AllowedCaller::DIRECT->value, $tool->allowedCallers, true); ``` ### 授權條款為 Apache 2.0 從這些版本開始，SDK 與 CLI 採用 Apache License, Version 2.0 授權。較早的版本仍維持 MIT License。不需要變更任何程式碼。如果您有追蹤相依套件的授權條款，請更新其項目。 * **TypeScript：** 平台套件（`@anthropic-ai/bedrock-sdk`、`@anthropic-ai/vertex-sdk`、`@anthropic-ai/foundry-sdk`、`@anthropic-ai/aws-sdk` 與 `@anthropic-ai/google-cloud-sdk`）會在各自的 1.0.0 版本中變更授權條款。 * **C#：** 其他套件（`Anthropic.Bedrock`、`Anthropic.Vertex`、`Anthropic.Foundry`、`Anthropic.Aws`、`Anthropic.GoogleCloud` 與 `Anthropic.Mcp`）會在各自的 1.0.0 版本中變更授權條款。 * **Java：** 此變更涵蓋所有 `com.anthropic` 構件。