開發 Inference hooks 整合

Inference hooks 整合是一個「AI security server」（AI 安全伺服器），也就是由 Anthropic 呼叫的 HTTPS 服務。對於每個受管控的請求，您的伺服器會收到一個已簽署的 POST，其中包含「transcript」（對話記錄）。您的伺服器需以允許或拒絕的「verdict」（判定）回應。本頁說明建置該伺服器所需的協定，包括請求與判定的結構描述、簽章驗證，以及運作合約。

若要啟用 Inference hooks 並將其指向您的端點，請參閱設定 Inference hooks。若要了解 Inference hooks 是什麼以及何時使用，請參閱 Inference hooks 概覽。

完成第一次判定往返

最小可運作的整合是一個讀取每個請求並允許它的伺服器。執行以下其中一個伺服器，將其公開於一個公開的 https:// URL（例如，放在您所控制主機上的 TLS 終止反向代理之後，而非反向通道服務；請參閱接收請求），然後請您的管理員將其設為端點並測試連線：Test connection 的結果會回報您的伺服器所傳回的允許判定。

# 執行方式：python server.py
from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer


class VerdictHandler(BaseHTTPRequestHandler):
    protocol_version = "HTTP/1.1"  # keep the connection open between verdicts

    def do_POST(self):
        # 讀完整個 body；逐字稿可能達數 MB。
        self.rfile.read(int(self.headers.get("Content-Length", 0)))
        verdict = b'{"action": "allow"}'
        self.send_response(200)
        self.send_header("Content-Type", "application/json")
        self.send_header("Content-Length", str(len(verdict)))
        self.end_headers()
        self.wfile.write(verdict)


ThreadingHTTPServer(("", 8000), VerdictHandler).serve_forever()

接收請求

Anthropic 會向您的管理員所設定的 URL 傳送 HTTPS POST。整個設定的 URL 就是端點：沒有固定的路徑後綴，因此您可以選擇任何適合您伺服器的路徑。

請將您的 AI 安全伺服器託管在 Anthropic 能夠連線的位置：一個使用連接埠 443 的 https:// URL，位於可公開路由的主機上（私有、迴路及電信級 NAT 範圍會在連線時被拒絕），具備可通過公開 CA 信任存放區驗證的憑證，且回應時不使用重新導向。主機必須具有 IPv4 位址，即使主機同時具有 IPv6 位址，Anthropic 也會使用 IPv4 位址；主機為 localhost 或 IPv6 位址的 URL 會被拒絕。設定的 URL 必須是最終目的地。不支援反向通道主機（ngrok 及類似的通道服務）：Anthropic 的網路政策會封鎖它們。請將您的伺服器託管在您所控制的網域上。設定 Inference hooks 說明了您的管理員如何設定和測試該 URL。

每個請求都會攜帶以下固定標頭，以及您的管理員所設定的任何自訂請求標頭，並且在您的組織擁有簽署密鑰後，還會攜帶驗證簽章中所述的 webhook-* 簽章標頭：

共有兩種掛鉤事件，以頂層的 type 欄位區分。「prompt frame」（提示訊框）會在每個受管控的推論請求開始推論之前傳送一次。「tool call frame」（工具呼叫訊框）會在模型回應包含工具呼叫時、任何工具呼叫執行之前傳送，僅適用於已開啟 Validate tool calls 的組織。無論哪種情況，Anthropic 都會等待，直到您的 AI 安全伺服器回應或判定逾時時間到期。

提示訊框

請求主體是一個包含以下欄位的 JSON 物件：

請求主體範例：

{
  "type": "prompt",
  "request_id": "req_abc123",
  "tenant_id": "11111111-1111-1111-1111-111111111111",
  "actor": {
    "type": "user",
    "id": "user_01AbCdEfGhIjKlMnOpQrStUv",
    "email_address": "alice@example.com"
  },
  "source": {
    "application": "claude-ai"
  },
  "session_id": "22222222-2222-2222-2222-222222222222",
  "model": "claude-sonnet-4-5",
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "Summarize the attached report."
        },
        {
          "type": "attachment",
          "file_name": "q2-report.pdf",
          "media_type": "application/pdf",
          "size_bytes": 48213,
          "text": "Q2 revenue grew 14% quarter over quarter..."
        }
      ]
    }
  ],
  "metadata": {}
}

內容區塊

messages 中的每個項目都有一個值為 user 或 assistant 的 role（工具結果出現在 user 角色下，與公開 Messages API 的內容模型一致），以及一個以 type 區分的區塊 content 陣列：

除了 type、text 區塊的 text，以及 tool_result 區塊的 content 和 is_error 之外，當值未知時，上述任何欄位都可能為 null；例如，圖片會以 attachment 區塊的形式送達，其 file_name 和 text 設為 null。

您無法辨識其 type 的區塊屬於向前相容的新增項目。它唯一保證的欄位是 type；您的政策可以檢查存在的任何其他欄位，但不得因為無法辨識的類型而拒絕請求。

對話記錄包含的內容

對話記錄是終端使用者所看到的對話，截至推論時間點為止。其中包含：

• 對話記錄文字
• 工具呼叫及其結果
• 擷取的附件文字
• 先前的回合

對話記錄絕不包含系統提示、工具定義、Anthropic 內部上下文、Claude 的隱藏推理或原始檔案位元組。

若某個回合的所有區塊都被排除，該回合會被完全省略。因此，請勿假設使用者與助理的回合會嚴格交替出現。

對話記錄會以未截斷的形式傳送，因此包含大型附件的長對話會產生很大的請求主體。實務上，模型的「context window」（上下文視窗）會讓主體維持在約 10 MB 以下，但協定允許最大 64 MiB。

許多常見的預設值遠小於此上限，例如 nginx 的 client_max_body_size 為 1 MB，Express 的 express.json() 為 100 kB。被拒絕的主體會被視為 webhook 失敗。因此，若失敗處理設定為 Allow the request，過大的提示會在未經檢查的情況下送達模型。

來源值

source.application 是一個開放字串，而非封閉的列舉。常見的值有 claude-ai、claude-code 和 cowork；連線測試和自動斷路器復原檢查使用 config-test。可能會出現新的值，您的伺服器不得因為無法辨識的值而拒絕請求。

請將 source.application 視為建議性的路由中繼資料，而非信任邊界：請勿僅依據它做出攸關安全的政策決策。

工具呼叫訊框

當 Claude 產生工具呼叫時，Anthropic 會傳送一個列出這些呼叫的工具呼叫訊框。對 claude.ai 部分自有工具的呼叫可能會被省略，而若回應中的工具呼叫全部被省略，則不會產生工具呼叫訊框；請參閱可用性。一個判定涵蓋整個訊框：您無法允許部分工具呼叫而拒絕其他呼叫。此訊框會傳送到與提示訊框相同的端點，並使用相同的標頭、簽章和頂層欄位。由 Claude 在程式碼執行工具中執行的程式碼所發出的工具呼叫，也會以相同方式在執行前以個別的工具呼叫訊框傳送。

它與提示訊框有三點不同：

• type 為 "tool_call"。
• messages 只包含最新的訊息，也就是 Claude 剛產生的 assistant 訊息：任何 text 區塊，以及訊框所列每個工具呼叫各一個 tool_use 區塊，依模型產生的順序排列。較早的對話會被省略，因為在該次模型呼叫之前傳送的提示訊框已攜帶這些內容。請讀取 messages 的最後一個項目，因為協定日後可能會在其之前加入較早的訊息。
• 每個 tool_use 區塊都攜帶一個 tool_info 物件，說明由誰執行或提供該工具。

若有設定 session_id，兩種訊框上的值會相同。工具呼叫訊框有自己的 request_id，與提示訊框的一樣是不透明的。

tool_info 說明的是由誰執行或提供該工具，而非該工具能存取什麼。它屬於四種類別之一，以其 type 欄位區分，且每種類別都攜帶各自的欄位。Anthropic 會傳送以下類別中第一個符合該工具的類別。可能會出現新的類別：請接受您無法辨識的 type，並且對於此類類別僅依賴 type。

不適用的選用欄位會被省略，絕不為 null，因此 tool_info 可能只是 {"type": "client"}。tool_name 由定義該工具的一方選定，而伺服器的 toolset_name 由撰寫請求的一方選定，因此請勿將兩者視為信任邊界。

平台工具

平台工具是 Claude API 本身在處理請求時執行的工具，例如網頁搜尋或程式碼執行。

應用程式工具

應用程式工具是發出請求的 Anthropic 應用程式本身所提供的工具，例如 claude.ai 的自有工具。

claude.ai 本身所提供的網頁搜尋工具的 tool_use 區塊：

{
  "type": "tool_use",
  "id": "toolu_01LmNoPqRsTuVwXyZaBcDeFg",
  "tool_name": "web_search",
  "input": {
    "query": "comparable deals for unannounced 4.2B USD Acme Corp acquisition"
  },
  "tool_info": {
    "type": "application"
  }
}

claude.ai 並不一定將此工具命名為 web_search，因此請勿僅依名稱比對。input 一律包含搜尋查詢，也可能包含其他欄位。

第三方工具

第三方工具是位於 Anthropic 所知伺服器上的工具，例如 claude.ai 連接器，或請求在 mcp_servers 中指名的 MCP 伺服器。這並不代表 Anthropic 已審查過該伺服器。

請求在 mcp_servers 中命名為 crm 的 MCP 伺服器上某個工具的 tool_use 區塊：

{
  "type": "tool_use",
  "id": "toolu_01GhIjKlMnOpQrStUvWxYzAb",
  "tool_name": "crm_search",
  "input": {
    "query": "accounts renewing in Q4"
  },
  "tool_info": {
    "type": "third_party",
    "toolset_name": "crm",
    "origin": "https://mcp.crm.example.com",
    "verified_origin": true
  }
}

用戶端工具

用戶端工具是任何其他工具，通常是呼叫 Claude 的應用程式所執行的工具。由 Anthropic 定義但由呼叫端應用程式執行的工具（例如 bash 或電腦使用）也是用戶端工具，並在 tool_type 中攜帶其版本化類型。對請求未宣告之工具的呼叫也屬於 "client"。

Claude Code 直接從使用者電腦連線的 MCP 伺服器（例如本機 MCP 伺服器）上的工具是用戶端工具。其 tool_info 為 {"type": "client"}，而其 tool_name 是 Claude Code 為其指定的名稱，格式為 mcp__<server>__<tool>。

拒絕會在 Claude Code 執行呼叫之前將其停止。Claude Code 與本機伺服器之間的交換不會經過 Anthropic，因此您的 AI 安全伺服器只有在 Claude Code 將工具結果傳回時才會看到它。屆時其文字會出現在下一個提示訊框的 tool_result 區塊中。

呼叫端應用程式所宣告之工具的 tool_use 區塊：

{
  "type": "tool_use",
  "id": "toolu_01AbCdEfGhIjKlMnOpQrStUv",
  "tool_name": "read_file",
  "input": {
    "path": "reports/q3.txt"
  },
  "tool_info": {
    "type": "client"
  }
}

bash 的 tool_use 區塊，該工具由 Anthropic 定義並由呼叫端應用程式執行：

{
  "type": "tool_use",
  "id": "toolu_01HiJkLmNoPqRsTuVwXyZaBc",
  "tool_name": "bash",
  "input": {
    "command": "ls -la reports/"
  },
  "tool_info": {
    "type": "client",
    "tool_type": "bash_20250124"
  }
}

回傳判定

無論哪種結果，都請以 HTTP 200 和 JSON 判定主體回應；由 action 欄位區分。若要允許請求：

{
  "action": "allow"
}

若要拒絕請求：

{
  "action": "deny",
  "deny_reason": "This prompt appears to contain customer payment card data, which your organization's policy does not allow.",
  "reference_id": "scan_01HXPT4R9V"
}

拒絕絕不會因為格式問題而被捨棄：過長的 deny_reason 會被截斷，格式錯誤的 reference_id 會被靜默捨棄，而 action 仍會被遵循。

反之則不成立。除了 HTTP 200 搭配可解析的判定之外，任何其他回應都是 webhook 失敗，此時會套用您組織的失敗處理，而非判定。特別是：

• 請勿以錯誤狀態表示拒絕。非 200 的回應是失敗，而非拒絕。
• 除了 allow 或 deny 之外的任何 action 值都會被視為 webhook 失敗。

Anthropic 最多讀取回應主體的 64 KiB，且主體必須未經壓縮。不會跟隨重新導向，且會忽略 cookie。判定主體中的未知欄位會被忽略，因此您可以在此處記錄的欄位之外回傳更豐富的物件。

工具呼叫訊框使用相同的判定主體，本節的每條規則都原封不動地適用於它。allow 讓工具呼叫執行，回應繼續進行；deny 會停止所有工具呼叫，並以與被拒絕提示相同的錯誤結束回應，包括您的 deny_reason。在第一個工具呼叫之前已傳遞的文字不會被收回。

驗證簽章

請求依照 Standard Webhooks 規範進行簽署，並使用三個標頭。Anthropic 以小寫傳送標頭名稱，但代理伺服器可能會變更其大小寫，因此請以不區分大小寫的方式查找這些標頭。

有兩個細節造成了大多數的驗證錯誤：

• 驗證原始位元組。 請在進行任何 JSON 解析或重新編碼之前，對收到的原始主體計算 HMAC。
• 使用標準 base64 解碼器解碼密鑰。 簽署密鑰是 whsec_ 前綴之後的值，以標準 base64 字母表（+ 和 /）編碼，標頭中的簽章也是如此。若密鑰包含 + 或 /（大多數情況下都會包含），URL 安全解碼器會推導出錯誤的金鑰位元組。

當您的組織擁有簽署密鑰後，Anthropic 傳送的每個請求都會經過簽署，包括連線測試，因為設定流程會在第一次測試之前產生密鑰。由於啟用 Inference hooks 需要密鑰，請拒絕任何未簽署的請求。

唯一的例外是：若組織在密鑰成為必要條件之前就已啟用 Inference hooks，則在其管理員產生密鑰之前，會持續傳送未簽署的請求。請僅在管理員確認密鑰已存在之前接受未簽署的請求，確認之後即應拒絕。

輪替密鑰會立即切換，但在切換後約一分鐘內，仍可能收到以先前密鑰簽署的請求，此外還有已在傳輸中的請求。請讓您的 AI 安全伺服器在切換期間同時接受兩組密鑰的簽章，以免拒絕這些延遲抵達的請求。

下列範例是伺服器實作，因此沒有 shell 分頁，因為 AI 安全伺服器是長時間執行的 HTTPS 服務，而非一次性請求。每個範例都只使用該語言的標準函式庫。Standard Webhooks 專案也為大多數語言發布了驗證函式庫。

import base64
import hashlib
import hmac
import time

TOLERANCE_SECONDS = 300


def verify(secret: str, headers: dict[str, str], body: bytes) -> bool:
    """Return True if the body was signed by Anthropic for this organization.

    Anthropic sends header names in lowercase, but proxies are free to
    re-case them, so normalize the lookup to lowercase.
    """
    lowercased = {name.lower(): value for name, value in headers.items()}
    try:
        message_id = lowercased["webhook-id"]
        timestamp = lowercased["webhook-timestamp"]
        signatures = lowercased["webhook-signature"]
    except KeyError:
        return False  # unsigned request: not from Anthropic

    try:
        signed_at = int(timestamp)
    except ValueError:
        return False
    if abs(time.time() - signed_at) > TOLERANCE_SECONDS:
        return False  # replayed, or the clocks disagree

    try:
        key = base64.b64decode(secret.removeprefix("whsec_"), validate=True)
    except ValueError:
        return False  # misconfigured secret: reject rather than crash

    payload = f"{message_id}.{timestamp}.".encode() + body
    expected = b"v1," + base64.b64encode(
        hmac.new(key, payload, hashlib.sha256).digest()
    )

    # 比較位元組：對 str 使用 compare_digest 時，若輸入含非 ASCII 字元會引發例外。
    return any(
        hmac.compare_digest(expected, candidate.encode())
        for candidate in signatures.split()
    )

運作語意

逾時與重試

您的管理員會設定介於 1 到 10,000ms 之間的判定逾時（預設為 5,000ms）。此時間預算涵蓋整個交換過程：連線、TLS 交握、請求和回應。相同的逾時也適用於工具呼叫訊框。

Anthropic 只會重試一次，在延遲 100ms 之後，且僅在連線嘗試失敗時進行。重試共用相同的逾時預算，並攜帶相同的 webhook-id 和相同的簽章。一旦您的 AI 安全伺服器已回應，該交換就絕不會被重試。

Webhook 失敗

下列情況都屬於 webhook 失敗：

• 逾時
• 非 200 狀態碼（包括重新導向）
• 無法解析或過大的回應主體
• 無法連線的端點

Webhook 失敗絕不會變成拒絕。受影響的請求會被封鎖，或在未經檢查的情況下繼續進行，由您組織的失敗處理設定決定。

斷路器

可歸因於您 AI 安全伺服器的持續 webhook 失敗會觸發「circuit breaker」（斷路器），停止強制執行：Anthropic 會停止聯繫您的伺服器，且失敗處理會套用到每個請求。

從觸發後 10 分鐘開始，Anthropic 會檢查您的伺服器是否已復原：大約每分鐘最多一次，它會向您的伺服器傳送與 Test connection 相同的合成測試請求（source.application 為 config-test），該請求與其他請求一樣經過簽署，且不攜帶任何使用者內容。請正常回應它。有效的判定（允許或拒絕）會重設斷路器並恢復強制執行；webhook 失敗則會讓斷路器保持觸發狀態，檢查也會持續進行。管理員也可以隨時重設斷路器，而管理員的設定變更會停止自動檢查；請參閱斷路器。

提示訊框和工具呼叫訊框共用一個斷路器，兩者的失敗都會計入其中。

每次觸發都會在活動摘要中記錄為一筆 inference_hooks_circuit_breaker_tripped 活動，每次觸發一筆活動。在斷路器觸發期間，不會記錄任何個別請求的 Inference hooks 活動，因此觸發活動是摘要中關於觸發期間的唯一記錄。

延遲

強制執行會將您 AI 安全伺服器的往返時間加到您組織中每個受管控請求的「latency」（延遲）上。開啟 Validate tool calls 時，產生工具呼叫訊框的回應也會等待其判定，在影子模式下亦然。請讓判定保持快速，並在將伺服器推廣到大型組織之前先進行負載測試。

來源 IP 位址

傳送至您 AI 安全伺服器的請求來自 160.79.106.0/24，此範圍屬於 Anthropic 公布的輸出 IP 範圍。請將此區塊加入允許清單，而非同一頁面上的輸入範圍，因為輸入範圍並未涵蓋此區塊。

加入允許清單可以縮小您伺服器的暴露面，但無法取代簽章驗證，因為此區塊承載的 Anthropic 輸出流量不僅限於 Inference hooks。

向前相容性

協定的擴充不會破壞正確撰寫的伺服器。您的伺服器必須忽略：

• 任一種訊框上的未知頂層欄位。
• metadata 中的未知鍵。
• 新的 source.application 值。
• 新的 actor.type 值。actor 是以 type 區分的聯集，目前唯一傳送的類別是 "user"；未來的類別僅保證 type 存在。
• 具有無法辨識之 type 的內容區塊。
• role 不是 user 或 assistant 的訊息，後續修訂版本可能會加入此類訊息。

絕不要因為無法辨識的區塊類型或欄位而拒絕請求；請讀取您已知的欄位並略過其餘部分。

未來將會推出其他掛鉤事件類型。新的事件類型是您的伺服器無法透過略過欄位來處理的新增項目：該請求仍然需要判定。當頂層 type 是您無法辨識的值時，請回傳允許判定，而非錯誤狀態；錯誤回應屬於 webhook 失敗，而持續的失敗會觸發斷路器。

設計您的整合

除了傳輸協定之外，正式環境的 AI 安全伺服器還需要做出幾項設計選擇。

依據 webhook-id 去除重複。 webhook-id 標頭在每次傳遞中都是唯一的，其值等於主體的 request_id，且連線失敗時的重試會沿用此值，因此可作為冪等性金鑰使用。若您會記錄判定，請以此值作為記錄的鍵。

記錄判定並關聯拒絕事件。 請儲存您回傳的每個判定及其 reference_id。每次拒絕都會記錄為一筆 inference_hooks_request_denied 合規活動，其中包含您伺服器所回傳的 reference_id。如此一來，您就能將活動摘要中的拒絕事件，與您自有系統中的對應記錄關聯起來。

使用一律允許的伺服器進行封存。 若要即時擷取對話記錄而不加以管控，請無條件回傳 {"action": "allow"}，並在回應之後保存框架。這是輪詢 Compliance API 之外的推送式替代方案。先回應再保存，可讓您的往返時間不會落在使用者的關鍵路徑上。

為終端使用者撰寫 deny_reason。 當使用者的請求遭到封鎖時，他們看到的就是您回傳的文字，且超過 500 個字元的部分會被截斷。請告訴使用者需要修改什麼，例如應移除哪一類內容，而不是輸出只有您的團隊才能解讀的掃描器代碼。

後續步驟