im.ttalk.agent.tool

Liking cljdoc? Tell your friends :D

Clojure only.

build-tool-schema
call-with-timeout
check-timeout!
context-tool?
deftool
get-schema
get-tags
has-any-tag?
invoke
params->json-schema
retry-spec
return-direct-tool?
serial-tool?
timeout-spec
tool-function?
tool-meta
valid-retry?
valid-timeout?
validate-args

工具函数定义宏

deftool 宏同时生成：

普通 Clojure 函数（可直接调用）
完整的 tool schema 元数据（用于 LLM Function Calling）

参数声明使用向量格式: [名称类型描述] 支持可选参数: [名称类型描述 :default 默认值] 支持参数约束: [名称类型描述 :enum [..] :pattern ".." :minimum 1 :maximum 9 :min-length n :max-length n :items {:type "string"} :min-items n :max-items n :properties {…} :required [..] :additional-properties false] （进 input_schema，模型看得到；调用前按 schema 完整校验，见 tool-args）对象参数的属性表可写成 [[名称 schema] …] 键值对 vector——保序，字段多于 8 个时用这个写法（map 字面量多于 8 键会被 Clojure reader 变成 hash map，键序不再跟源码文本一致）。数组条目的对象（:items {:type "object" :properties …}）与更深的嵌套对象都吃同一套写法。

schema 在命名空间加载期构造（不是常量）：AOT 编译会把常量 map 重建（>8 键即 PersistentHashMap），参数声明顺序会丢；加载期构造则 eval 与 AOT 完全一致。支持敏感标记: {:sensitive true} 支持只读 context: {:context true} 支持串行标记: {:serial true}（副作用工具，批内并行时整批退化为按序执行）支持直接返回: {:return-direct true}（结果即最终答案，不再回灌 LLM）

状态读写（Tool 阶段 MapReduce 契约，见 docs/agent-loop-concurrency-design.md §9）：

读：{:context true} 工具收到只读的轮初 context 快照（ctx 变量自动绑定）
写：任意工具（无论是否声明 :context）返回 {:result r :writes {k v}} 声明写意图；批次屏障处按 tool-call 原始序经槽级 reducer 折叠进 context。同批工具互相看不到对方的写（快照隔离）；失败/超时/拒绝的调用 writes 不生效。

使用示例:

;; 基本用法 (deftool get-weather "获取指定城市的天气信息" [[city :string "城市名称"]] (fetch-weather city))

;; 带可选参数 (deftool calculate "执行数学计算" [[expression :string "数学表达式"] [precision :int "小数精度" :default 2]] (compute expression precision))

;; 标记敏感工具 (deftool delete-file "删除文件" [[path :string "文件路径"]] {:sensitive true} (io/delete-file path))

;; 带 tags 的工具 (deftool get-weather "获取天气" [[city :string "城市名称"]] {:tags [:weather :external-api :read-only]} (fetch-weather city))

;; 读 context（只读快照）+ 写状态（:writes 声明写意图） (deftool save-note "保存笔记" [[content :string "内容"]] {:context true} ;; ctx 是自动绑定的只读 context 变量 (let [user (context/get-var ctx :user-id)] {:result (str "已保存（" user "）") :writes {:notes content}})) ;; 槽 :notes 的 reducer 决定如何合并

;; 无参数函数 (deftool get-time "获取当前时间" [] (str (java.time.LocalDateTime/now)))

工具函数定义宏

deftool 宏同时生成：
1. 普通 Clojure 函数（可直接调用）
2. 完整的 tool schema 元数据（用于 LLM Function Calling）

参数声明使用向量格式: [名称 类型 描述]
支持可选参数: [名称 类型 描述 :default 默认值]
支持参数约束: [名称 类型 描述 :enum [..] :pattern ".." :minimum 1 :maximum 9
              :min-length n :max-length n :items {:type "string"} :min-items n :max-items n
              :properties {…} :required [..] :additional-properties false]
              （进 input_schema，模型看得到；调用前按 schema 完整校验，见 tool-args）
对象参数的属性表可写成 [[名称 schema] …] 键值对 vector——**保序**，字段多于 8 个时用这个写法
（map 字面量多于 8 键会被 Clojure reader 变成 hash map，键序不再跟源码文本一致）。
数组条目的对象（`:items {:type "object" :properties …}`）与更深的嵌套对象都吃同一套写法。

**schema 在命名空间加载期构造**（不是常量）：AOT 编译会把常量 map 重建（>8 键即
PersistentHashMap），参数声明顺序会丢；加载期构造则 eval 与 AOT 完全一致。
支持敏感标记: {:sensitive true}
支持只读 context: {:context true}
支持串行标记: {:serial true}（副作用工具，批内并行时整批退化为按序执行）
支持直接返回: {:return-direct true}（结果即最终答案，不再回灌 LLM）

状态读写（Tool 阶段 MapReduce 契约，见 docs/agent-loop-concurrency-design.md §9）：
- 读：{:context true} 工具收到只读的轮初 context 快照（ctx 变量自动绑定）
- 写：任意工具（无论是否声明 :context）返回 {:result r :writes {k v}}
  声明写意图；批次屏障处按 tool-call 原始序经槽级 reducer 折叠进 context。
  同批工具互相看不到对方的写（快照隔离）；失败/超时/拒绝的调用 writes 不生效。

使用示例:

;; 基本用法
(deftool get-weather
  "获取指定城市的天气信息"
  [[city :string "城市名称"]]
  (fetch-weather city))

;; 带可选参数
(deftool calculate
  "执行数学计算"
  [[expression :string "数学表达式"]
   [precision :int "小数精度" :default 2]]
  (compute expression precision))

;; 标记敏感工具
(deftool delete-file
  "删除文件"
  [[path :string "文件路径"]]
  {:sensitive true}
  (io/delete-file path))

;; 带 tags 的工具
(deftool get-weather
  "获取天气"
  [[city :string "城市名称"]]
  {:tags [:weather :external-api :read-only]}
  (fetch-weather city))

;; 读 context（只读快照）+ 写状态（:writes 声明写意图）
(deftool save-note
  "保存笔记"
  [[content :string "内容"]]
  {:context true}
  ;; ctx 是自动绑定的只读 context 变量
  (let [user (context/get-var ctx :user-id)]
    {:result (str "已保存（" user "）")
     :writes {:notes content}}))   ;; 槽 :notes 的 reducer 决定如何合并

;; 无参数函数
(deftool get-time
  "获取当前时间"
  []
  (str (java.time.LocalDateTime/now)))

raw docstring

build-tool-schema^clj

(build-tool-schema fn-name description parsed-params)

构建 Anthropic 兼容的 tool schema

参数:

fn-name: 函数名（keyword）
description: 函数描述
params: 解析后的参数列表

返回: {:name "函数名" :description "描述" :input_schema {:type "object" :properties {...} :required [...]}}

构建 Anthropic 兼容的 tool schema

参数:
- fn-name:     函数名（keyword）
- description: 函数描述
- params:      解析后的参数列表

返回:
{:name         "函数名"
 :description  "描述"
 :input_schema {:type "object" :properties {...} :required [...]}}

`Ctrl`+`k`	Jump to recent docs
`←`	Move to previous article
`→`	Move to next article
`Ctrl`+`/`	Jump to the search field

im.ttalk.agent.tool

build-tool-schemaclj

call-with-timeoutclj

check-timeout!clj

context-tool?clj

deftoolcljmacro

get-schemaclj

get-tagsclj

has-any-tag?clj

invokeclj

params->json-schemaclj

retry-specclj

return-direct-tool?clj

serial-tool?clj

timeout-specclj

tool-function?clj

tool-metaclj

valid-retry?clj

valid-timeout?clj

validate-argsclj

build-tool-schema^clj

call-with-timeout^clj

check-timeout!^clj

context-tool?^clj

deftool^cljmacro

get-schema^clj

get-tags^clj

has-any-tag?^clj

invoke^clj

params->json-schema^clj

retry-spec^clj

return-direct-tool?^clj

serial-tool?^clj

timeout-spec^clj

tool-function?^clj

tool-meta^clj

valid-retry?^clj

valid-timeout?^clj

validate-args^clj