AgentToolSpec

org.llm4s.agent.graph.tool.AgentToolSpec
See theAgentToolSpec companion object
final case class AgentToolSpec[A]

What a tool tells the model and the loop: its name, description and argument schema, how its arguments decode, an optional check on the decoded value, and the question it may ask.

name must match [a-zA-Z0-9_-]{1,64}: apply throws IllegalArgumentException otherwise, and ToolSet.of refuses one too, so a spec built another way is still checked.

Arguments are validated against argumentSchema, the schema rendered non-strict, which is what core's Anthropic, Gemini and Vertex AI clients send. A call from a client that sends tools strict (OpenAI and the OpenAI-compatible ones) carries every property, which that schema also accepts.

Value parameters

hints

what the tool is likely to do, for a middleware to read; see ToolHints

locksOf

the locks a call holds, from its decoded arguments, when the tool declares any; see withLocks

question

the question this tool may ask; set by AgentTool.Asking

resourcesOf

what a call touches, from its decoded arguments; see withResources

timeout

how long one run of the tool may take; see withTimeout

validateDecoded

a check on the decoded arguments; Left becomes an error the model sees

Attributes

Companion
object
Source
AgentTool.scala
Graph
Supertypes
trait Serializable
trait Product
trait Equals
class Object
trait Matchable
class Any
Show all

Members list

Value members

Concrete methods

The resource a call of this tool touches when it declares none: invoking the tool.

The resource a call of this tool touches when it declares none: invoking the tool.

Attributes

Source
AgentTool.scala

The tool definition in OpenAI's strict format, the shape of ToolFunction.toOpenAITool(true), for callers that send definitions themselves; core's clients receive ToolSet.toolFunctions and render their own from schema. Its parameters are a fresh copy each time, so a caller that edits one definition cannot change another.

The tool definition in OpenAI's strict format, the shape of ToolFunction.toOpenAITool(true), for callers that send definitions themselves; core's clients receive ToolSet.toolFunctions and render their own from schema. Its parameters are a fresh copy each time, so a caller that edits one definition cannot change another.

Attributes

Source
AgentTool.scala

Declares what the tool is likely to do, replacing any earlier hints.

Declares what the tool is likely to do, replacing any earlier hints.

Attributes

Source
AgentTool.scala
def withLocks(locks: A => Set[LockKey]): AgentToolSpec[A]

Declares the locks a call holds, from its decoded arguments; by default it holds none. When one model message has several calls, a call whose locks conflict with an earlier call's (one LockKey a prefix of the other) waits for it: it runs in a later superstep, in call order, and sees the state the earlier call committed. Calls without conflicting locks run concurrently, as before. Each further round of calls costs two supersteps of RunBudgets.maxSupersteps. A function that throws gives the call the root lock, which conflicts with every lock.

Declares the locks a call holds, from its decoded arguments; by default it holds none. When one model message has several calls, a call whose locks conflict with an earlier call's (one LockKey a prefix of the other) waits for it: it runs in a later superstep, in call order, and sees the state the earlier call committed. Calls without conflicting locks run concurrently, as before. Each further round of calls costs two supersteps of RunBudgets.maxSupersteps. A function that throws gives the call the root lock, which conflicts with every lock.

As with withResources, they cover every run of the call, resume included: a tool whose answer chooses its target locks a key above every target it may pick, and an approval edit may narrow the locks but not take one they do not cover (it is refused).

Attributes

Source
AgentTool.scala
def withResources(resources: A => Vector[ToolResource]): AgentToolSpec[A]

Declares what a call touches, from its decoded arguments, replacing the default Vector(ToolResource(Operation.Invoke, name)); an empty vector is checked as that default. A PermissionMiddleware reads them from ToolCallRequest.resources. A function that throws refuses the call as invalid arguments.

Declares what a call touches, from its decoded arguments, replacing the default Vector(ToolResource(Operation.Invoke, name)); an empty vector is checked as that default. A PermissionMiddleware reads them from ToolCallRequest.resources. A function that throws refuses the call as invalid arguments.

They are the call's whole envelope, over every run of it: what execute may touch, and what resume may touch after a question, whatever the answer. The runtime checks them; it cannot see what the tool then does. So a tool whose answer chooses its target (asking for a missing destination) declares a resource covering every target it may pick (Write /out/**), and refuses an answer outside it as an error.

Attributes

Source
AgentTool.scala

Bounds each run of the tool - its execute, or its resume after a question - to timeout. A run past it is interrupted, and the call's outcome is ToolOutcome.Error("Tool '<name>' timed out after <n> ms"), an error the model sees; a wrapper that retries gets a fresh bound. The tool runs on a thread of its own, which is joined before the call goes on, so a tool that ignores its interrupt holds its batch past the timeout: block interruptibly. A cancelled run is still a cancellation, which records nothing. timeout must be positive.

Bounds each run of the tool - its execute, or its resume after a question - to timeout. A run past it is interrupted, and the call's outcome is ToolOutcome.Error("Tool '<name>' timed out after <n> ms"), an error the model sees; a wrapper that retries gets a fresh bound. The tool runs on a thread of its own, which is joined before the call goes on, so a tool that ignores its interrupt holds its batch past the timeout: block interruptibly. A cancelled run is still a cancellation, which records nothing. timeout must be positive.

Attributes

Source
AgentTool.scala
def withValidation(check: A => Result[Unit]): AgentToolSpec[A]

Adds a check on the decoded arguments, replacing any earlier one.

Adds a check on the decoded arguments, replacing any earlier one.

Attributes

Source
AgentTool.scala

Inherited methods

Attributes

Inherited from:
Product

Attributes

Inherited from:
Product

Concrete fields

lazy val argumentSchema: Value

The schema arguments are validated against, schema.toJsonSchema(strict = false), rendered once: only the required properties are required, so a call that omits an optional one is accepted, as core's non-strict clients allow. ToolSet.of checks its keywords. Do not mutate it.

The schema arguments are validated against, schema.toJsonSchema(strict = false), rendered once: only the required properties are required, so a call that omits an optional one is accepted, as core's non-strict clients allow. ToolSet.of checks its keywords. Do not mutate it.

Attributes

Source
AgentTool.scala

Givens

Givens

given codec: ReadWriter[A]

Attributes

Source
AgentTool.scala