An agent's settings, immutable: every with* returns a new builder, and build compiles it, with every agent reachable through its handoffs, into an Agent. Start one with Agent.builder.
Tools, middleware, prompt and step limit belong to the agent, not to a run: the compiled graph's version covers them, so a thread is only ever continued by the graph it ran on. The runtime and tracing are the root's: a handoff target's are ignored.
Attributes
- Companion
- object
- Source
- AgentBuilder.scala
- Graph
-
- Supertypes
Members list
Value members
Concrete methods
Compiles this agent and every agent reachable through handoffs into one graph. Refuses an invalid id, a maxSteps below 1, a handoff whose id is invalid or differs from its target's, an id-only handoff (Handoff.toId) to an id no builder of the family defines, one id defined by two builders with different settings - their handoff targets and subagents compared too - a tool named like a task tool of any agent of the family (task calls are counted by name across handoffs), two agents of the family setting different DelegationConfigs (one turn runs under one set of bounds; an agent that sets none takes the family's), and whatever org.llm4s.agent.graph.toolloop.ToolLoop.build refuses: tool name clashes, invalid tool schemas, keys the loop owns, handoffs to self or twice to one target.
Compiles this agent and every agent reachable through handoffs into one graph. Refuses an invalid id, a maxSteps below 1, a handoff whose id is invalid or differs from its target's, an id-only handoff (Handoff.toId) to an id no builder of the family defines, one id defined by two builders with different settings - their handoff targets and subagents compared too - a tool named like a task tool of any agent of the family (task calls are counted by name across handoffs), two agents of the family setting different DelegationConfigs (one turn runs under one set of bounds; an agent that sets none takes the family's), and whatever org.llm4s.agent.graph.toolloop.ToolLoop.build refuses: tool name clashes, invalid tool schemas, keys the loop owns, handoffs to self or twice to one target.
Attributes
- Source
- AgentBuilder.scala
The options every model call of this agent is made with; their tools are replaced by the agent's.
The options every model call of this agent is made with; their tools are replaced by the agent's.
Attributes
- Source
- AgentBuilder.scala
The bounds on this agent's delegated tasks, replacing the defaults; build refuses a bound that is not positive, and this beside a harness, whose SubagentConfig.delegation sets them.
The bounds on this agent's delegated tasks, replacing the defaults; build refuses a bound that is not positive, and this beside a harness, whose SubagentConfig.delegation sets them.
Attributes
- Source
- AgentBuilder.scala
Appends handoffs to the agent's handoffs, in order.
Installs profile (design 4.37), replacing any set before: at build, its tools join this agent's, its middleware run outside this agent's own - permissions, summarisation, offload, skills, instructions, todos, outermost first, each when the profile sets it - and its prompt is the system prompt, so withSystemPrompt is refused beside it (use PromptMode.Replace or Suffix). On the root agent, its retention prunes each thread as each turn is admitted (RunConfig.withRetention, unless the run sets its own); a handoff target's is ignored, as its runtime is. build() refuses what the profile refuses (see org.llm4s.agent.harness.HarnessProfile).
Installs profile (design 4.37), replacing any set before: at build, its tools join this agent's, its middleware run outside this agent's own - permissions, summarisation, offload, skills, instructions, todos, outermost first, each when the profile sets it - and its prompt is the system prompt, so withSystemPrompt is refused beside it (use PromptMode.Replace or Suffix). On the root agent, its retention prunes each thread as each turn is admitted (RunConfig.withRetention, unless the run sets its own); a handoff target's is ignored, as its runtime is. build() refuses what the profile refuses (see org.llm4s.agent.harness.HarnessProfile).
Attributes
- Source
- AgentBuilder.scala
Static breakpoints that hold each task of these nodes of this agent after it ran, on every run: its update is stored, and what follows it waits. A step continued after an approval or a question - a model call after a wrapModelCall question, a tool call after an approval or a question, an answer guarded again after an afterAgent question - is held after it ran, as the step itself is. Each release replays the held routes in a superstep of its own, which counts against RunBudgets.maxSupersteps. See withInterruptBefore.
Static breakpoints that hold each task of these nodes of this agent after it ran, on every run: its update is stored, and what follows it waits. A step continued after an approval or a question - a model call after a wrapModelCall question, a tool call after an approval or a question, an answer guarded again after an afterAgent question - is held after it ran, as the step itself is. Each release replays the held routes in a superstep of its own, which counts against RunBudgets.maxSupersteps. See withInterruptBefore.
Attributes
- Source
- AgentBuilder.scala
Static breakpoints that hold each task of these nodes of this agent before it runs, on every run; added to those set before, and to those a run's RunConfig.interruptBefore names. A held task is an interrupt of its own - AgentStatus.Suspended.breakpoints - continued with AgentResult.proceed. Like streaming, breakpoints change nothing stored, so they are not part of the graph's version: a thread held by one agent is continued by one without them. A task continued after an approval or a question is not held before again: the reviewer has just seen it. Java and Kotlin call it with plain arguments: withInterruptBefore(AgentNode.valueOf("Tool")).
Static breakpoints that hold each task of these nodes of this agent before it runs, on every run; added to those set before, and to those a run's RunConfig.interruptBefore names. A held task is an interrupt of its own - AgentStatus.Suspended.breakpoints - continued with AgentResult.proceed. Like streaming, breakpoints change nothing stored, so they are not part of the graph's version: a thread held by one agent is continued by one without them. A task continued after an approval or a question is not held before again: the reviewer has just seen it. Java and Kotlin call it with plain arguments: withInterruptBefore(AgentNode.valueOf("Tool")).
Attributes
- Source
- AgentBuilder.scala
The most every middleware's prompt sections may add to one model request together, at least 1 and 8192 by default, estimated at four characters a token. A request over it fails the run, naming each section's size.
The most every middleware's prompt sections may add to one model request together, at least 1 and 8192 by default, estimated at four characters a token. A request over it fails the run, naming each section's size.
Attributes
- Source
- AgentBuilder.scala
Model calls per turn, at least 1; at the limit the turn ends StepLimitReached.
Model calls per turn, at least 1; at the limit the turn ends StepLimitReached.
Attributes
- Source
- AgentBuilder.scala
Appends middleware to the agent's stack, in order. The root agent's run-boundary hooks guard the whole family: its beforeAgent runs on every turn's query, before the active agent's own, and its afterAgent on every final answer, after the answering agent's own - so a org.llm4s.agent.graph.middleware.GuardrailMiddleware on the root still applies after a handoff. A handoff target's boundary hooks apply only while it is active, and model and tool wrappers (wrapModelCall, wrapToolCall) only to the agent they are given to.
Appends middleware to the agent's stack, in order. The root agent's run-boundary hooks guard the whole family: its beforeAgent runs on every turn's query, before the active agent's own, and its afterAgent on every final answer, after the answering agent's own - so a org.llm4s.agent.graph.middleware.GuardrailMiddleware on the root still applies after a handoff. A handoff target's boundary hooks apply only while it is active, and model and tool wrappers (wrapModelCall, wrapToolCall) only to the agent they are given to.
Attributes
- Source
- AgentBuilder.scala
The response format of this agent's answers (design 4.26): schema, rendered strict, replacing any set before - a hand-written ObjectSchema[O], or one derived with llm4s-schema-derivation: withOutput(SchemaOf[Invoice].definition). The system prompt states it on every model call, and a call that offers no tools carries it as responseFormat, replacing one given with withCompletionOptions; a call that offers tools carries none, since providers that cannot combine the two would refuse or suppress the tool calls (see ModelStep.fromClient). A final answer must be JSON that matches the schema and reads as O, and is stored as that JSON alone. An invalid answer is retried once in the same model step, with its problems; a second invalid answer ends the turn with Left(GraphError.OutputInvalid), the turn removed and both calls counted. Read the answer with AgentResult.decodeOutput. The format belongs to this agent only: a handoff target answers in its own. build refuses a schema whose root is not an object, one with a keyword the tool argument validator cannot check, and a format whose prompt section alone is over withMaxPromptSectionTokens, which the section counts against with the middleware's.
The response format of this agent's answers (design 4.26): schema, rendered strict, replacing any set before - a hand-written ObjectSchema[O], or one derived with llm4s-schema-derivation: withOutput(SchemaOf[Invoice].definition). The system prompt states it on every model call, and a call that offers no tools carries it as responseFormat, replacing one given with withCompletionOptions; a call that offers tools carries none, since providers that cannot combine the two would refuse or suppress the tool calls (see ModelStep.fromClient). A final answer must be JSON that matches the schema and reads as O, and is stored as that JSON alone. An invalid answer is retried once in the same model step, with its problems; a second invalid answer ends the turn with Left(GraphError.OutputInvalid), the turn removed and both calls counted. Read the answer with AgentResult.decodeOutput. The format belongs to this agent only: a handoff target answers in its own. build refuses a schema whose root is not an object, one with a keyword the tool argument validator cannot check, and a format whose prompt section alone is over withMaxPromptSectionTokens, which the section counts against with the middleware's.
Attributes
- Source
- AgentBuilder.scala
The runtime the agent's threads live on; by default a new GraphRuntime.inMemory per build. A runtime keeps every thread - a one-shot Agent.run's too - until Agent.forget removes it.
The runtime the agent's threads live on; by default a new GraphRuntime.inMemory per build. A runtime keeps every thread - a one-shot Agent.run's too - until Agent.forget removes it.
Attributes
- Source
- AgentBuilder.scala
Streams the model's answer: each model call uses streamComplete, and its text and thinking reach subscribers as live AgentEvents.TextDelta and ThinkingDelta events. Off by default. It changes nothing stored, so it is not part of the graph's version: a thread runs on with streaming switched on or off.
Streams the model's answer: each model call uses streamComplete, and its text and thinking reach subscribers as live AgentEvents.TextDelta and ThinkingDelta events. Off by default. It changes nothing stored, so it is not part of the graph's version: a thread runs on with streaming switched on or off.
Attributes
- Source
- AgentBuilder.scala
Appends agents to the subagents this agent may delegate to (design 4.44), in order. At build each is bound to this agent's client and runtime, and a delegation middleware, innermost in the stack, offers them: the task tool for every subagent taking a TaskRequest, a task_<id> tool for each other one, and a cacheable prompt section listing each subagent's id and description. A call runs the subagent on a child thread of the calling thread and returns only its typed report. build refuses two subagents with one id, a subagent that does not bind, and a task tool whose name clashes with another tool. Bounded by withDelegation. Beside a harness (design 4.48) they follow the profile's own subagents, the middleware runs inside the harness's permissions and outside its other middleware, and the profile's SubagentConfig.delegation bounds them.
Appends agents to the subagents this agent may delegate to (design 4.44), in order. At build each is bound to this agent's client and runtime, and a delegation middleware, innermost in the stack, offers them: the task tool for every subagent taking a TaskRequest, a task_<id> tool for each other one, and a cacheable prompt section listing each subagent's id and description. A call runs the subagent on a child thread of the calling thread and returns only its typed report. build refuses two subagents with one id, a subagent that does not bind, and a task tool whose name clashes with another tool. Bounded by withDelegation. Beside a harness (design 4.48) they follow the profile's own subagents, the middleware runs inside the harness's permissions and outside its other middleware, and the profile's SubagentConfig.delegation bounds them.
Attributes
- Source
- AgentBuilder.scala
Sent first on every model call of this agent; never stored in the thread's history.
Sent first on every model call of this agent; never stored in the thread's history.
Attributes
- Source
- AgentBuilder.scala
The agent's tools, replacing any set before, checked with the set's validator.
The agent's tools, replacing any set before, checked with the set's validator.
Attributes
- Source
- AgentBuilder.scala
The registry's tools, replacing any set before, each adapted with org.llm4s.agent.graph.tool.AgentTool.fromToolFunction; build checks them as a org.llm4s.agent.graph.tool.ToolSet.
The registry's tools, replacing any set before, each adapted with org.llm4s.agent.graph.tool.AgentTool.fromToolFunction; build checks them as a org.llm4s.agent.graph.tool.ToolSet.
Attributes
- Source
- AgentBuilder.scala
Traces each run to tracing: its events as graph.* and agent.* custom events, each model call's usage as TokenUsageRecorded, and its end as one AgentRunEnded.
Traces each run to tracing: its events as graph.* and agent.* custom events, each model call's usage as TokenUsageRecorded, and its end as one AgentRunEnded.
Attributes
- Source
- AgentBuilder.scala
