org.llm4s.agent.events

Members list

Type members

Classlikes

object AgentEvents

The events an agent run sends, each an org.llm4s.agent.graph.EventType to match a StreamEvent with:

The events an agent run sends, each an org.llm4s.agent.graph.EventType to match a StreamEvent with:

agent.stream(threadId, "Explain monads") {
 case AgentEvents.TextDelta(d)          => print(d.text)
 case AgentEvents.ToolExecuted(t)       => println(s"${t.tool}: ${t.outcome} in ${t.duration}")
 case _                                 => ()
}

Durable (stored, replayed, no content): ModelCallCompleted, ToolExecuted, HandedOff, GuardrailBlocked. Live (current subscribers only): ModelCallStarted, TextDelta, ThinkingDelta, ToolCallStarted, ToolCallResult.

Attributes

Source
AgentEvents.scala
Supertypes
class Object
trait Matchable
class Any
Self type
final case class CallUsage(promptTokens: Int, completionTokens: Int, totalTokens: Int, thinkingTokens: Option[Int])

A model call's token usage, as plain numbers.

A model call's token usage, as plain numbers.

Attributes

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

Attributes

Companion
class
Source
AgentEventPayloads.scala
Supertypes
trait Product
trait Mirror
class Object
trait Matchable
class Any
Self type
CallUsage.type
final case class GuardrailBlock(guardrail: String, phase: GuardrailPhase)

A guardrail blocked the turn; the reason is on AgentStatus.Blocked, never in the log.

A guardrail blocked the turn; the reason is on AgentStatus.Blocked, never in the log.

Attributes

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

Where a guardrail blocked the turn.

Where a guardrail blocked the turn.

Attributes

Source
AgentEventPayloads.scala
Supertypes
trait Enum
trait Serializable
trait Product
trait Equals
class Object
trait Matchable
class Any
Show all
final case class HandedOff(from: String, to: String)

The active agent changed from from to to.

The active agent changed from from to to.

Attributes

Source
AgentEventPayloads.scala
Supertypes
trait Serializable
trait Product
trait Equals
class Object
trait Matchable
class Any
Show all
final case class ModelCallCompleted(agent: String, model: String, attempts: Int, toolCalls: Int, usage: Option[CallUsage], estimatedCost: Option[Double], provider: Option[ProviderId], adjustments: List[RequestAdjustment])

A model call of agent's returned a completion: one event per provider call, whichever response the model wrappers kept, so the events sum to the thread's usage. attempts is the call's attempt number within its model step, from 1 - a retrying wrapper's calls are 1, 2, ... - and 0 for a call a hook made through ModelContext.accounted, or usage it recorded with ModelContext.recordUsage. toolCalls is the completion's. usage and estimatedCost (USD) are the completion's, when the provider reported them. provider is the canonical id of the provider called, when its client reported one (LLMClient.providerId); None in an event stored before it existed (#2275). adjustments are the completion's (Completion.adjustments): the options the client did not send as asked (RFC 0008, #2115); llm4s's own clients put no message content in them. Empty for usage recorded without a call, and in an event stored before the field existed. An adjustment this version cannot read, an option or a case added later, is left out rather than failing the event.

A model call of agent's returned a completion: one event per provider call, whichever response the model wrappers kept, so the events sum to the thread's usage. attempts is the call's attempt number within its model step, from 1 - a retrying wrapper's calls are 1, 2, ... - and 0 for a call a hook made through ModelContext.accounted, or usage it recorded with ModelContext.recordUsage. toolCalls is the completion's. usage and estimatedCost (USD) are the completion's, when the provider reported them. provider is the canonical id of the provider called, when its client reported one (LLMClient.providerId); None in an event stored before it existed (#2275). adjustments are the completion's (Completion.adjustments): the options the client did not send as asked (RFC 0008, #2115); llm4s's own clients put no message content in them. Empty for usage recorded without a call, and in an event stored before the field existed. An adjustment this version cannot read, an option or a case added later, is left out rather than failing the event.

Attributes

Source
AgentEventPayloads.scala
Supertypes
trait Serializable
trait Product
trait Equals
class Object
trait Matchable
class Any
Show all
final case class ModelCallStarted(agent: String, attempt: Int)

agent's model is being called; a higher attempt in the same task discards the earlier attempt's text.

agent's model is being called; a higher attempt in the same task discards the earlier attempt's text.

Attributes

Source
AgentEventPayloads.scala
Supertypes
trait Serializable
trait Product
trait Equals
class Object
trait Matchable
class Any
Show all
@Experimental

The events a delegating agent's runs send for its children (design 4.47), each an org.llm4s.agent.graph.EventType:

The events a delegating agent's runs send for its children (design 4.47), each an org.llm4s.agent.graph.EventType:

agent.stream(threadId, "Research these three topics", nested = true)(
 EventHandlers
   .on(SubagentEvents.TaskStarted)(s => println(s"started ${s.child.agent}"))
   .onChild(AgentEvents.TextDelta)((child, d) => print(s"[${child.agent}] ${d.text}"))
   .on(SubagentEvents.TaskEnded)(e => println(s"${e.child.agent}: ${e.status} in ${e.duration}"))
)

Durable (stored, replayed, no content): TaskEnded. Live: TaskStarted.

Attributes

Source
SubagentEvents.scala
Supertypes
class Object
trait Matchable
class Any
Self type
@Experimental
final case class TaskEnded(child: ChildRef, status: String, usage: UsageSummary, duration: FiniteDuration)

A delegated task ended (design 4.47): durable, committed with the task call's terminal result - a report, or a refusal the parent model sees as a tool error - so once per child. A call that fails its parent (under ChildFailure.Fail) commits nothing, and its replay sends the one TaskEnded.

A delegated task ended (design 4.47): durable, committed with the task call's terminal result - a report, or a refusal the parent model sees as a tool error - so once per child. A call that fails its parent (under ChildFailure.Fail) commits nothing, and its replay sends the one TaskEnded.

status is completed, blocked:<guardrail>, step_limit_reached, token_limit_reached, output_invalid or failed; a call whose child suspended commits none until a resumed call settles it. usage is the child's whole life's model usage, every attempt and phase, the roll-up added to the parent. duration runs from the child's first admission (RunOrigin.startedAt) to the call's end, by the runtime's clock; it is encoded in milliseconds. No request, report or reason: the child's own log and the parent's tool message hold those (rule 9). It is the source of per-subagent count, latency, outcome and token metrics.

Attributes

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

Attributes

Companion
class
Source
SubagentEvents.scala
Supertypes
trait Product
trait Mirror
class Object
trait Matchable
class Any
Self type
TaskEnded.type
@Experimental
final case class TaskStarted(child: ChildRef)

A delegated task's child run was admitted (design 4.47): live, sent for the parent's task call as the child's run claims its thread - only for a run that was admitted - and again on each reattach. It is the nested stream's handle: a parent subscription made with nested = true receives the child's events after it, as StreamEvent.Nested(child, _). child.runId is the run the call is about to drive, or, for a child already settled, the run that settled it.

A delegated task's child run was admitted (design 4.47): live, sent for the parent's task call as the child's run claims its thread - only for a run that was admitted - and again on each reattach. It is the nested stream's handle: a parent subscription made with nested = true receives the child's events after it, as StreamEvent.Nested(child, _). child.runId is the run the call is about to drive, or, for a child already settled, the run that settled it.

Attributes

Source
SubagentEvents.scala
Supertypes
trait Serializable
trait Product
trait Equals
class Object
trait Matchable
class Any
Show all
final case class TextDelta(attempt: Int, text: String)

A chunk of the model's answer, for attempt.

A chunk of the model's answer, for attempt.

Attributes

Source
AgentEventPayloads.scala
Supertypes
trait Serializable
trait Product
trait Equals
class Object
trait Matchable
class Any
Show all
final case class ThinkingDelta(attempt: Int, text: String)

A chunk of the model's thinking, for attempt.

A chunk of the model's thinking, for attempt.

Attributes

Source
AgentEventPayloads.scala
Supertypes
trait Serializable
trait Product
trait Equals
class Object
trait Matchable
class Any
Show all
final case class ToolCallResult(toolCallId: String, content: String, isError: Boolean)

The result the loop recorded for a call, as the model will see it.

The result the loop recorded for a call, as the model will see it.

Attributes

Source
AgentEventPayloads.scala
Supertypes
trait Serializable
trait Product
trait Equals
class Object
trait Matchable
class Any
Show all
final case class ToolCallStarted(toolCallId: String, tool: String, arguments: Value)

A tool call passed its argument checks and is about to run through the middleware chain.

A tool call passed its argument checks and is about to run through the middleware chain.

Attributes

Source
AgentEventPayloads.scala
Supertypes
trait Serializable
trait Product
trait Equals
class Object
trait Matchable
class Any
Show all
final case class ToolExecuted(agent: String, toolCallId: String, tool: String, duration: FiniteDuration, outcome: ToolExecutionOutcome, idempotencyKey: Option[String])

One tool call's outcome; duration is the middleware chain's, zero for a call refused before it. tool is the called tool's name when the agent has that tool, else "<unknown>" (ToolLoop.UnknownTool): a name the model invented is not stored. idempotencyKey is the call's org.llm4s.agent.graph.IdempotencyKey (a digest, no content), which names the call's trace span (design 4.58); None in an event stored before it existed.

One tool call's outcome; duration is the middleware chain's, zero for a call refused before it. tool is the called tool's name when the agent has that tool, else "<unknown>" (ToolLoop.UnknownTool): a name the model invented is not stored. idempotencyKey is the call's org.llm4s.agent.graph.IdempotencyKey (a digest, no content), which names the call's trace span (design 4.58); None in an event stored before it existed.

Attributes

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

Attributes

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

How a tool call ended for the loop.

How a tool call ended for the loop.

Attributes

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