im.ttalk.agent.provider.anthropic — im.ttalk/clj-agent-provider 0.5.447

Anthropic Provider 实现

实现 ILLMProvider 协议，提供 Anthropic Claude API 的完整访问。

支持功能：

• 同步调用 / 流式调用（同步阻塞）/ 异步调用 / 异步流式调用
• 工具调用（Function Calling）+ 结构化输出
• 服务端内置工具：web_search（见 schema.anthropic/web-search-tool）
• Citations 引用：可引用文档块（schema.anthropic/text-document）+ 响应引用提取（extract-citations）
• Skills（beta）：技能容器 + code_execution 工具（schema.anthropic/skill 等，配合 config :beta）
• prompt caching 策略层（见 common.cache）
• 响应限流头解析（parse-rate-limit）

调用 config 支持的 Anthropic 专属能力（均「存在才发送」，详见 build-params）：

• 采样：:temperature :top-p :top-k :max-tokens :stop（=> stop_sequences）
• 推理：:thinking（如 {:type "adaptive"} / {:type "enabled" :budget_tokens 2048}）
• :metadata、:service-tier（"auto" | "standard_only"，容量路由）
• 工具：:tools（含 web_search 等 wire 工具）、:tool-choice
• 缓存：:cache-strategy + :cache-ttl（见下；可按断点给档 {:system "1h" :conversation nil}， 用到 "1h" 自动并入 beta extended-cache-ttl-2025-04-11）
• 宿主钩子：:configure-request（(fn [payload] payload')，发出前最后改一次请求体， 见 common.request-hook）

prompt caching 策略（:cache-strategy）：

• :none | :system | :tools | :system-and-tools | :conversation
• :tool-results 缓存到最后一个 tool_result（多轮工具循环跨轮复用）
• :system-and-conversation system + 对话历史双断点 命中/创建 token 归一化到响应 usage 的 :cache-read-tokens / :cache-write-tokens。

响应限流：同步调用成功时，响应体附加 :rate-limit {:requests-limit :requests-remaining :requests-reset :tokens-limit :tokens-remaining :tokens-reset :retry-after}（源自 anthropic-ratelimit-* 头）。

使用示例：

(require '[im.ttalk.agent.provider.anthropic :as anthropic] '[im.ttalk.agent.provider.schema.anthropic :as schema])

(def provider (anthropic/create-provider))

;; 同步调用 (anthropic/call-anthropic config messages tools)

;; 流式调用 (anthropic/call-anthropic-stream config messages tools on-token)

;; web_search + 缓存 + 服务层级 (anthropic/call-anthropic {:model "claude-opus-4-8" :max-tokens 4096 :service-tier "auto" :cache-strategy :system-and-tools :cache-ttl "1h"} messages [(schema/web-search-tool {:max-uses 5})])

;; Citations：可引用文档 -> 响应带引用 (let [resp (anthropic/call-anthropic {:model "claude-opus-4-8" :max-tokens 1024} [{:role "user" :content [(schema/text-document "地球绕太阳公转。" {:title "天文"}) {:type "text" :text "地球绕什么转？"}]}] [])] (anthropic/extract-citations resp))

;; Skills（beta）：需开 :beta 头 + code_execution 工具 (anthropic/call-anthropic {:model "claude-opus-4-8" :max-tokens 4096 :beta schema/default-skills-beta :container (schema/skills-container [(schema/skill "xlsx")])} messages [(schema/code-execution-tool)])

call-anthropic clj

(call-anthropic config messages tools)

调用 Anthropic API（同步）

参数：

• config: 配置 map {:model "..." :max-tokens 4096 ...}
• messages: 消息列表
• tools: 工具列表

返回： Anthropic API 响应

示例： (call-anthropic {:model "claude-sonnet-4-20250514" :max-tokens 4096} [{:role "user" :content "你好"}] [])

call-anthropic-deferred clj

(call-anthropic-deferred config messages tools)

调用 Anthropic API（异步，返回 deferred<响应体>）。

参数与语义同 call-anthropic（含限流头附加、canonical error），只是不阻塞。 无重试：重试在 ChatModel 层（im.ttalk.agent.retry/run-async）。

与同步版共用后处理：http/post-deferred 的响应 map 形状与 http/post 逐字相同，:success? 判定 / parse-rate-limit / response->error 只有一份 （docs/async-chat-model-design.md §0 / §5）。

call-anthropic-stream clj

(call-anthropic-stream config messages tools on-token)

流式调用 Anthropic API（同步，阻塞当前线程）

参数：

• config: 配置 map
• messages: 消息列表
• tools: 工具列表
• on-token: 回调函数 (fn [{:keys [token index accumulated]}] ...)

返回： 最终完整响应

call-anthropic-stream-deferred clj

(call-anthropic-stream-deferred config messages tools on-token)

流式调用 Anthropic API（异步，返回 deferred<最终响应>）。

参数与语义同 call-anthropic-stream（含 :retry 建链重试与取消）， 只是不阻塞。⚠️ on-token 在传输层 executor 上派发，不是调用线程。

create-provider clj

(create-provider)

(create-provider opts)

创建 Anthropic Provider 实例

参数：

• opts: 实例选项（可选），作为每次调用 config 的默认值并入：
  • :api-key API Key
  • :provider-name 逻辑名（默认 :anthropic；MiniMax 等兼容端点可覆盖）
  • :base-url :api-path :auth-scheme :anthropic-version 端点配置（见 default-endpoint）

返回： AnthropicProvider record（opts 存于实例，不再使用全局可变状态，支持多实例并存）

示例： (create-provider) (create-provider {:api-key "sk-ant-..."}) ;; Anthropic 兼容端点（如 MiniMax）： (create-provider {:provider-name :minimax :base-url "https://api.minimaxi.com" :api-path "/anthropic/v1/messages" :auth-scheme :bearer :anthropic-version nil :api-key "..."})

default-endpoint clj

默认端点：官方 Anthropic API（x-api-key + anthropic-version 头）

extract-citations clj

(extract-citations response)

从 Anthropic 响应提取引用（Citations）。

当请求带启用引用的 document 内容块（见 schema.anthropic/text-document）时， 响应的 text 块会携带 :citations 数组，标注引用了哪个文档的哪段文本。

参数：

• response: Anthropic API 响应

返回： 引用列表（如 [{:type "char_location" :cited_text "..." :document_index 0 :document_title "..." :start_char_index 0 :end_char_index 12} ...]） 无引用时返回 nil。

extract-text clj

(extract-text response)

从 Anthropic 响应中提取文本

参数：

• response: Anthropic API 响应

返回： 文本字符串

extract-tool-calls clj

(extract-tool-calls response)

从 Anthropic 响应中提取工具调用

参数：

• response: Anthropic API 响应

返回： 工具调用列表 [{:id "..." :name "字符串" :args {...}}]

get-stop-reason clj

(get-stop-reason response)

获取停止原因

参数：

• response: Anthropic API 响应

返回： 关键字 (:end_turn, :tool_use, :max_tokens, :stop_sequence)

get-usage clj

(get-usage response)

获取令牌使用情况

参数：

• response: Anthropic API 响应

返回： usage map {:input_tokens n :output_tokens m}

has-tool-calls? clj

(has-tool-calls? response)

检查 Anthropic 响应是否包含工具调用

参数：

• response: Anthropic API 响应

返回： boolean

normalize-response clj

(normalize-response raw-response)

将原始 Anthropic API 响应标准化为统一格式

参数：

• response: 原始 Anthropic API 响应

返回： 统一响应格式： {:text "..." :tool-calls [{:id :name :args}] :usage {:input-tokens n :output-tokens m :total-tokens t} :finish-reason :stop | :tool-use | :max-tokens | ... :model "..." :id "..." :provider :anthropic :raw-response {...}}

示例： (normalize-response raw-response) ; => {:text "你好" ; :tool-calls [] ; :usage {:input-tokens 100 :output-tokens 50 :total-tokens 150} ; :finish-reason :stop ; :provider :anthropic}

parse-rate-limit clj

(parse-rate-limit headers)

从响应头解析限流信息。

统一实现见 provider.common.rate-limit/parse-rate-limit（OpenAI x-ratelimit-* 与 anthropic-ratelimit-* 折成同一形状，designs/provider-reliability.md §6）；本函数保留为 向后兼容的入口。

返回： {:requests-limit n :requests-remaining n :requests-reset "ISO时间" :tokens-limit n :tokens-remaining n :tokens-reset "ISO时间" :retry-after n} 仅包含响应实际携带的字段；全部缺失时返回 nil。

valid-response? clj

(valid-response? response)

检查 Anthropic 响应是否有效

参数：

• response: Anthropic API 响应

返回： boolean