AgentZ

org.llm4s.zio.AgentZ
See theAgentZ companion object
trait AgentZ

ZIO wrapper for Agent.

Lifts every Result[AgentResult] into ZIO[Any, LLMError, AgentResult]. run and continueConversation start the turn on ZIO's blocking pool and then await it, so interrupting the fiber cancels the turn itself (AgentRun.cancel) and returns once it has ended: its model call and tool calls are interrupted, and the thread is left for recover. recover and resume do the same through Agent.startRecover and Agent.startResume.

stream, streamResume and streamRecover run a turn as a ZStream of its events (AgentStreamItem.Event), then its result (AgentStreamItem.Done); interrupting the stream cancels the turn as interrupting run does. Stopping early (take(n), runHead) also cancels the turn. A consumer too slow for the stream's buffer never holds the run up: it loses live events (text deltas, tool progress) and receives one StreamEvent.LiveGap with their count where they were dropped; durable events are kept, and the run carries on. A consumer that stops draining altogether fails the stream (and so cancels the turn) once more than Agent.StreamCapacity durable events wait, as the runtime disconnects a listener that far behind.

A model call that throws instead of returning Left ends the turn with a GraphError.NodeFailed whose cause is the LLMError the runtime made of the throwable; it fails the effect with that error, not as a defect.

Intentionally a thin wrapper: build the Agent with its tools, middleware (guardrails), handoffs and options through Agent.builder, or LLMClientZ.agent.

Attributes

Companion
object
Source
AgentZ.scala
Graph
Supertypes
class Object
trait Matchable
class Any

Members list

Value members

Abstract methods

def continueConversation(previous: AgentResult, query: String, config: RunConfig): ZIO[Any, LLMError, AgentResult]

The next turn on previous's thread; see Agent.continueConversation.

The next turn on previous's thread; see Agent.continueConversation.

Attributes

Source
AgentZ.scala
def events[A](run: AgentRun, eventType: EventType[A]): ZStream[Any, LLMError, A]

The events of run that eventType names - durable and live - decoded: events with EventHandlers.on(eventType)(identity); see the overload taking handlers.

The events of run that eventType names - durable and live - decoded: events with EventHandlers.on(eventType)(identity); see the overload taking handlers.

Attributes

Source
AgentZ.scala
def events[R](run: AgentRun, handlers: EventHandlers[R]): ZStream[Any, LLMError, R]

What handlers make of run's events: one element for each event a handler takes, in delivery order. It observes the run, through AgentRun.subscribe: it replays the run's durable events from its start and then follows it live, but misses the live events sent before the stream started - use stream to see every one. It ends after the run's terminal event, or once a run that ends without one has delivered its last event; the run's own outcome is not failed with - await the run for it. Ending the stream early, or interrupting it, cancels its subscription only: the run carries on.

What handlers make of run's events: one element for each event a handler takes, in delivery order. It observes the run, through AgentRun.subscribe: it replays the run's durable events from its start and then follows it live, but misses the live events sent before the stream started - use stream to see every one. It ends after the run's terminal event, or once a run that ends without one has delivered its last event; the run's own outcome is not failed with - await the run for it. Ending the stream early, or interrupting it, cancels its subscription only: the run carries on.

Handlers run on the stream, not on the subscription: a slow handler slows the stream, never the run, and one that throws dies the stream (a defect). A consumer too slow for the stream's buffer loses live events, as stream's does - a LiveGap, which a handler sees through otherwise. A subscription that disconnects, or a consumer that falls more than Agent.StreamCapacity durable events behind, fails the stream with an LLMError.

Attributes

Source
AgentZ.scala
def nestedEvents[R](run: AgentRun, handlers: EventHandlers[R]): ZStream[Any, LLMError, R]

events, with the events of every child run delegates to (design 4.47): the subscription is made with nested = true, so handlers also see each StreamEvent.Nested - matched with EventHandlers.onChild, or otherwise - after the parent's SubagentEvents.TaskStarted for its child. Nested events are live: a consumer too slow for the buffer loses them as a LiveGap.

events, with the events of every child run delegates to (design 4.47): the subscription is made with nested = true, so handlers also see each StreamEvent.Nested - matched with EventHandlers.onChild, or otherwise - after the parent's SubagentEvents.TaskStarted for its child. Nested events are live: a consumer too slow for the buffer loses them as a LiveGap.

Attributes

Source
AgentZ.scala
def recover(threadId: ThreadId, config: RunConfig): ZIO[Any, LLMError, AgentResult]

Continues threadId's failed or interrupted run; see Agent.recover.

Continues threadId's failed or interrupted run; see Agent.recover.

Attributes

Source
AgentZ.scala
def resume(threadId: ThreadId, answers: Map[InterruptId, Value], config: RunConfig): ZIO[Any, LLMError, AgentResult]

Answers pending approvals and questions and continues; see Agent.resume.

Answers pending approvals and questions and continues; see Agent.resume.

Attributes

Source
AgentZ.scala
def run(query: String, config: RunConfig): ZIO[Any, LLMError, AgentResult]

One turn on a new thread; see Agent.run.

One turn on a new thread; see Agent.run.

Attributes

Source
AgentZ.scala
def stream(threadId: ThreadId, query: String, config: RunConfig): ZStream[Any, LLMError, AgentStreamItem]

One turn on threadId, as a stream: every event of the turn (Agent.stream), then Done(result). A refused start or a failed turn fails the stream with the LLMError; so does a subscription that disconnects (its listener failed), which also cancels the run. A slow consumer loses live events and gets a StreamEvent.LiveGap instead; it does not cancel the run. Interrupting the stream, or stopping it early (take(n), runHead), cancels the turn and returns once it has ended, leaving the thread for recover.

One turn on threadId, as a stream: every event of the turn (Agent.stream), then Done(result). A refused start or a failed turn fails the stream with the LLMError; so does a subscription that disconnects (its listener failed), which also cancels the run. A slow consumer loses live events and gets a StreamEvent.LiveGap instead; it does not cancel the run. Interrupting the stream, or stopping it early (take(n), runHead), cancels the turn and returns once it has ended, leaving the thread for recover.

Attributes

Source
AgentZ.scala

recover as a stream; see stream.

recover as a stream; see stream.

Attributes

Source
AgentZ.scala
def streamResume(threadId: ThreadId, answers: Map[InterruptId, Value], config: RunConfig): ZStream[Any, LLMError, AgentStreamItem]

resume as a stream; see stream.

resume as a stream; see stream.

Attributes

Source
AgentZ.scala