The capability protocol.
An agent can do nothing on its own. Everything it can do - touch the
filesystem, run a command, call your API - comes from a capability you hand
to jj.bettong.agent/run explicitly. No capability, no tool, no way in.
A capability is anything satisfying Capability. A plain map already does:
{:id :weather :instructions "Temperatures are in celsius." :tools [{:name "get_weather" :description "Current weather for a city." :parameters {:city {:type "string" :description "City name." :required true}} :handler (fn [{:keys [city]}] (str "It is raining in " city))}]}
so does a defrecord or a reify, when you need state or a lifecycle.
The capability protocol.
An agent can do nothing on its own. Everything it can do - touch the
filesystem, run a command, call your API - comes from a capability you hand
to `jj.bettong.agent/run` explicitly. No capability, no tool, no way in.
A capability is anything satisfying `Capability`. A plain map already does:
{:id :weather
:instructions "Temperatures are in celsius."
:tools [{:name "get_weather"
:description "Current weather for a city."
:parameters {:city {:type "string" :description "City name." :required true}}
:handler (fn [{:keys [city]}] (str "It is raining in " city))}]}
so does a defrecord or a reify, when you need state or a lifecycle.Whether tool output is scrubbed of credential values before the model sees it. On by default; bind to false only if you mean to hand a secret over.
Whether tool output is scrubbed of credential values before the model sees it. On by default; bind to false only if you mean to hand a secret over.
(id this)A keyword or string naming this capability. Shown in events and errors.
A keyword or string naming this capability. Shown in events and errors.
(instructions this)Extra system-prompt text telling the model how to use this capability, or nil.
Extra system-prompt text telling the model how to use this capability, or nil.
(tools this)A seq of tool specs. Each is {:name :description :parameters :handler}, where :handler is (fn [args] -> anything printable) and args is a map with keyword keys, decoded from what the model sent.
A seq of tool specs. Each is {:name :description :parameters :handler},
where :handler is (fn [args] -> anything printable) and args is a map with
keyword keys, decoded from what the model sent.(invoke registry name args)Runs a tool. Always returns a string: a tool that throws is reported to the model so it can read the error and try something else, and a tool nobody granted is reported as exactly that.
Whatever comes back is redacted, because every tool result is uploaded to the model provider - including the output of tools you wrote.
Runs a tool. Always returns a string: a tool that throws is reported to the model so it can read the error and try something else, and a tool nobody granted is reported as exactly that. Whatever comes back is redacted, because every tool result is uploaded to the model provider - including the output of tools you wrote.
(parameters->json-schema parameters)Tool parameters may be given as a ready-made JSON schema object, or as the shorthand {:city {:type "string" :description "..." :required true}}.
Tool parameters may be given as a ready-made JSON schema object, or as the
shorthand {:city {:type "string" :description "..." :required true}}.(registry capabilities)Flattens capabilities into name -> {:schema :handler :capability :order}. Two capabilities offering the same tool name is an error: the agent would have no way to tell which one you meant.
:order records where each tool was declared, because the tool list is part
of the prompt the provider caches. Keeping declaration order means adding a
capability appends its tools instead of reshuffling the ones already there,
so the cached prefix survives.
Flattens capabilities into name -> {:schema :handler :capability :order}.
Two capabilities offering the same tool name is an error: the agent would
have no way to tell which one you meant.
`:order` records where each tool was declared, because the tool list is part
of the prompt the provider caches. Keeping declaration order means adding a
capability appends its tools instead of reshuffling the ones already there,
so the cached prefix survives.(schemas registry)The :tools payload for the API, in the order the capabilities declared them. A map's own order is arbitrary once it grows past a handful of keys, and an arbitrary order that changes when a capability is added would throw away the provider's cache of everything before the change.
The :tools payload for the API, in the order the capabilities declared them. A map's own order is arbitrary once it grows past a handful of keys, and an arbitrary order that changes when a capability is added would throw away the provider's cache of everything before the change.
(system-text capabilities)The capabilities' own instructions, ready to append to the system prompt.
The capabilities' own instructions, ready to append to the system prompt.
(tool-schema {:keys [name description parameters]})The JSON the API expects for one tool spec.
The JSON the API expects for one tool spec.
cljdoc builds & hosts documentation for Clojure/Script libraries
| Ctrl+k | Jump to recent docs |
| ← | Move to previous article |
| → | Move to next article |
| Ctrl+/ | Jump to the search field |