你的 OpenAI/Anthropic 賬單上的 AI 代理是誰花的錢？

Spaturzu 是一個由 Superchiu Ltd 開發的開源 SDK，旨在解決 AI 代理成本歸因和管理中的痛點。它允許開發者將現有的 LLM 提供者客戶端（如 OpenAI、Anthropic、Bedrock、Gemini、Mistral）包裝起來，從而為每個 API 呼叫分配代理標識，並在後臺進行計量，而無需更改呼叫程式碼。

遷移過程極為簡單：只需將匯入語句從 import OpenAI from "openai" 改為 import OpenAI from "@spaturzu/sdk/openai"，然後使用 withAgent 或 run 方法標記呼叫，即可將成本歸屬於特定代理。Python 版本的用法類似：from spaturzu.openai import OpenAI，然後使用 client.with_agent("support-triage").chat.completions.create(...)。這種一行匯入替換適用於所有支援的提供商，包括 Anthropic、Bedrock、Google Gemini 和 Mistral。

除了成本歸屬，Spaturzu 還提供預算控制功能。開發者可以為每個代理設定硬預算上限。當代理的預算耗盡時，包裝後的客戶端會在呼叫到達提供商之前丟擲 BudgetExceededError，從而避免產生任何費用。如果希望更溫和的處理方式，可以設定 onBreach: "warn" 來記錄警告並繼續執行。

對於需要高可用性的場景，Spaturzu 支援跨提供商故障轉移。透過配置一個備選提供商鏈，當主提供商返回可重試錯誤（如 HTTP 429 或 5xx）時，SDK 會自動重試下一個備選提供商，並將響應格式轉換為與主提供商一致的形狀，確保下游程式碼無需修改。目前支援所有 20 個方向的提供商對，但 v1 版本的故障轉移僅支援非流式文本響應，不支援工具呼叫或 response_format。

Spaturzu 的另一大特色是巢狀代理支援。開發者可以使用 run() 方法巢狀呼叫，從而為多步驟工作流構建成本樹。例如，一個“研究”代理可以包含一個“綜合”子代理，所有呼叫都會沿路徑歸屬到相應節點，在儀表盤上以樹狀結構呈現。此外，標籤系統允許在全域性或每個呼叫幀上設定標籤，從而按團隊、客戶或環境進行成本細分。

安裝方面，Spaturzu 支援 Python 和 TypeScript/Node。Python 包釋出在 PyPI 上，支援 Python 3.10+，可透過 pip install spaturzu 安裝核心包，並可選擇安裝特定提供商整合（如 pip install "spaturzu[openai]"）。TypeScript 包釋出在 npm 上，為 ESM 模組，可透過 npm install @spaturzu/sdk 安裝，同時需自行安裝所需提供商的客戶端包。

Spaturzu 的包裝過程是透明的：包裝後的客戶端擁有與原客戶端相同的方法和返回型別，開發者繼續以通常的方式呼叫模型，Spaturzu 在後臺默默計量每個呼叫。對於短生命週期的程序（如 CLI 工具或無伺服器函式），需要在退出前呼叫 flush() 以確保計量資料被髮送。

Spaturzu 採用 MIT 許可證釋出，其完整文件、API 參考和更多示例可在官方網站 spaturzu.superchiu.org 上找到。目前還提供了一個實驗性的 OpenClaw 外掛，用於計量和預算管理，但尚不建議用於生產環境。