org.llm4s.agent.graph.tool

Members list

Type members

Classlikes

trait AgentTool[A]

A tool the agent loop can call: typed arguments, validated against AgentToolSpec.argumentSchema and decoded with its codec before execute runs. A tool writes only the state keys in writes.

A tool the agent loop can call: typed arguments, validated against AgentToolSpec.argumentSchema and decoded with its codec before execute runs. A tool writes only the state keys in writes.

Attributes

Companion
object
Source
AgentTool.scala
Supertypes
class Object
trait Matchable
class Any
Known subtypes
class Asking[A, Q, Ans]
object AgentTool

Attributes

Companion
trait
Source
AgentTool.scala
Supertypes
class Object
trait Matchable
class Any
Self type
AgentTool.type
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.

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
Supertypes
trait Serializable
trait Product
trait Equals
class Object
trait Matchable
class Any
Show all
object AgentToolSpec

Attributes

Companion
class
Source
AgentTool.scala
Supertypes
class Object
trait Matchable
class Any
Self type
@Experimental
final class Glob

A path pattern, matched against a whole target string: a tool name, a /-separated path, or a URL.

A path pattern, matched against a whole target string: a tool name, a /-separated path, or a URL.

  • * matches any run of characters other than /, so it stays within one segment;
  • ? matches one character other than /;
  • ** matches any run of characters, / included; as a whole segment it also matches zero segments, so src/**/a.scala matches src/a.scala, and src/** matches src.

Every other character is literal: there are no escapes, character classes or braces, so every string is a valid pattern. Two globs are equal when their patterns are.

Besides matching one target, two globs compare as sets of targets: overlaps (some target matches both) and covers (every target the other matches, this one matches). A permission check uses them for a resource whose target is itself a pattern, an envelope of the targets a call may touch. Matching and both comparisons run on one automaton built from the pattern, so they cannot disagree.

Attributes

Companion
object
Source
Glob.scala
Supertypes
class Object
trait Matchable
class Any
object Glob

Attributes

Companion
class
Source
Glob.scala
Supertypes
class Object
trait Matchable
class Any
Self type
Glob.type
@Experimental
object LockKey

Attributes

Source
LockKey.scala
Supertypes
class Object
trait Matchable
class Any
Self type
LockKey.type
@Experimental
enum Operation

What a tool call does to a ToolResource; permission rules match on it.

What a tool call does to a ToolResource; permission rules match on it.

Attributes

Source
ToolResource.scala
Supertypes
trait Enum
trait Serializable
trait Product
trait Equals
class Object
trait Matchable
class Any
Show all

Checks raw tool-call arguments against the JSON Schema a tool sent to the provider.

Checks raw tool-call arguments against the JSON Schema a tool sent to the provider.

The default implementation supports exactly the subset core's SchemaDefinition emits: type (a string or an array of strings), description (ignored), properties, required, additionalProperties (boolean), enum, minLength, maxLength, minimum, maximum, exclusiveMinimum, exclusiveMaximum, multipleOf, items, minItems, maxItems and uniqueItems. Any other keyword, and a supported one with a malformed value (a bound that is not a number, a length or count that is not a non-negative whole number, a non-boolean uniqueItems, a required that is not an array of strings, an enum that is not an array, properties that is not an object), is reported by unsupported so a tool set can refuse it when it is built, rather than silently skip the constraint on every call.

Attributes

Companion
object
Source
ToolArgumentValidator.scala
Supertypes
class Object
trait Matchable
class Any

Attributes

Companion
trait
Source
ToolArgumentValidator.scala
Supertypes
class Object
trait Matchable
class Any
Self type

A successful call's result for the model: JSON, or content parts - text, images and documents.

A successful call's result for the model: JSON, or content parts - text, images and documents.

The loop sends Json as one text part: a non-blank string as itself, anything else rendered as JSON. It sends Parts as they are, in the ToolMessage, for the provider to map; a provider that cannot send one fails the model call with an UnsupportedContentPartError. Parts with no content, or carrying more than ContentPart.MaxInlineBytes of inline bytes in total, is the call's error result instead: every checkpoint copies the thread's messages, so larger media goes in a MediaSource.Url or a MediaSource.ProviderFile.

It has a ReadWriter, so an effect guarded by ReplayGuard can record a ToolContent as its outcome and replay it, parts and all: its inline media is base64 in the record, and counts towards the guard's maxOutcomeBytes at that encoded size.

Attributes

Source
AgentTool.scala
Supertypes
trait Enum
trait Serializable
trait Product
trait Equals
class Object
trait Matchable
class Any
Show all
final case class ToolContext

What a tool call knows: the run, the call's id, the call's IdempotencyKey, the thread state it may read, and whether the call has been approved. Built with ToolContext(...); a field added later gets a default there and a with* setter, so existing callers keep compiling.

What a tool call knows: the run, the call's id, the call's IdempotencyKey, the thread state it may read, and whether the call has been approved. Built with ToolContext(...); a field added later gets a default there and a with* setter, so existing callers keep compiling.

A tool with an external side effect passes idempotencyKey to the system it calls (an Idempotency-Key header, a client token, a unique column), because the runtime may run the same call more than once: a retrying wrapper, recover after a failure, cancellation or crash, and an approval each run it again with the same key. A call can even run twice at once: a worker paused past its claim's lease may still be running it when another runtime takes the thread over and runs it too, with the same key. A system that can fence writers can refuse the stale worker: run.position.fencingToken is the run's claim token, which grows with every claim on the thread, so the system keeps the highest token it has seen and refuses a lower one.

Attributes

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

Attributes

Companion
class
Source
AgentTool.scala
Supertypes
trait Product
trait Mirror
class Object
trait Matchable
class Any
Self type

What a tool call produced, as data.

What a tool call produced, as data.

Attributes

Source
AgentTool.scala
Supertypes
trait Enum
trait Serializable
trait Product
trait Equals
class Object
trait Matchable
class Any
Show all
final case class ToolQuestion[Q, Ans](questionCodec: ReadWriter[Q], answerCodec: ReadWriter[Ans])

The codecs of a tool's question and of the answer it takes.

The codecs of a tool's question and of the answer it takes.

Attributes

Source
AgentTool.scala
Supertypes
trait Serializable
trait Product
trait Equals
class Object
trait Matchable
class Any
Show all
@Experimental
final case class ToolResource(operation: Operation, target: String)

One thing a tool call touches, as its tool declares with AgentToolSpec.withResources: the operation, and the target a permission rule's Glob matches - a tool name, a path or a URL. A tool that declares none touches ToolResource(Operation.Invoke, <its name>).

One thing a tool call touches, as its tool declares with AgentToolSpec.withResources: the operation, and the target a permission rule's Glob matches - a tool name, a path or a URL. A tool that declares none touches ToolResource(Operation.Invoke, <its name>).

Attributes

Source
ToolResource.scala
Supertypes
trait Serializable
trait Product
trait Equals
class Object
trait Matchable
class Any
Show all
final class ToolSet

The tools an agent loop offers, in order, with the validator that checks their arguments. Built only through ToolSet.of, so every name is valid and unique, every argument schema is an object, and every schema keyword is one the validator checks.

The tools an agent loop offers, in order, with the validator that checks their arguments. Built only through ToolSet.of, so every name is valid and unique, every argument schema is an object, and every schema keyword is one the validator checks.

Attributes

Companion
object
Source
ToolSet.scala
Supertypes
class Object
trait Matchable
class Any
object ToolSet

Attributes

Companion
class
Source
ToolSet.scala
Supertypes
class Object
trait Matchable
class Any
Self type
ToolSet.type

Types

opaque type LockKey

A lock a tool call holds while it runs, as its tool declares with AgentToolSpec.withLocks: a path of segments, such as files/state/files, workspace/<id> or workspace/<id>/src/a.scala. Two keys conflict when one is a prefix of the other, segment by segment, so a workspace-wide lock conflicts with every file lock in that workspace, and a directory's with every lock beneath it; a/b does not conflict with a/bc. The key with no segments is the root, and conflicts with every key.

A lock a tool call holds while it runs, as its tool declares with AgentToolSpec.withLocks: a path of segments, such as files/state/files, workspace/<id> or workspace/<id>/src/a.scala. Two keys conflict when one is a prefix of the other, segment by segment, so a workspace-wide lock conflicts with every file lock in that workspace, and a directory's with every lock beneath it; a/b does not conflict with a/bc. The key with no segments is the root, and conflicts with every key.

Calls of one model message whose locks conflict run one after another, in call order, each in its own superstep, so each sees the state the earlier one committed; see AgentToolSpec.withLocks. A batch records its calls' keys rendered (render), which LockKey(rendered) reads back exactly.

Attributes

Source
LockKey.scala