Module agentforge4j.runtime

Package com.agentforge4j.runtime.llm

Class LlmCallObserver

java.lang.Object

com.agentforge4j.runtime.llm.LlmCallObserver

public final class LlmCallObserver
extends Object

Observes each completed LLM call: emits a WorkflowEventType.LLM_CALL_COMPLETED event and maintains the ReservedContextKeys.LLM_TOKENS_TOTAL running total in WorkflowState context.

Separating this concern from AgentInvoker keeps the invoker focused on dispatch and retry while token accounting and audit emission are independently testable.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static final record	LlmCallObserver.LlmCallCompletedPayload	Typed shape of the WorkflowEventType.LLM_CALL_COMPLETED event payload.

Constructor Summary

Constructors

Constructor	Description
LlmCallObserver(EventRecorder eventRecorder, com.fasterxml.jackson.databind.ObjectMapper objectMapper)

Method Summary

Modifier and Type	Method	Description
void	observe(String agentId, String provider, LlmExecutionResponse response, String resolvedModel, ModelSource modelSource, ModelTier requestedModelTier, WorkflowState state, int attempt)	Called once for the LLM call whose parsed output the workflow actually uses.
void	recordAttempt(String agentId, String provider, LlmExecutionResponse response, String resolvedModel, ModelSource modelSource, ModelTier requestedModelTier, WorkflowState state, int attempt)	Records a discarded LLM call attempt for audit/usage purposes only.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Details

LlmCallObserver

public LlmCallObserver(EventRecorder eventRecorder,
 com.fasterxml.jackson.databind.ObjectMapper objectMapper)

Method Details

observe

public void observe(String agentId,
 String provider,
 LlmExecutionResponse response,
 String resolvedModel,
 ModelSource modelSource,
 ModelTier requestedModelTier,
 WorkflowState state,
 int attempt)

Called once for the LLM call whose parsed output the workflow actually uses. Emits the audit event and updates the ReservedContextKeys.LLM_TOKENS_TOTAL running total.

Parameters:

agentId - the agent that triggered the call

provider - the provider name (e.g. "claude")

response - the full provider response including usage and model metadata

resolvedModel - the model the runtime resolved and sent; null when the provider default was used

modelSource - how the model was determined (pin, tier, or provider default)

requestedModelTier - the requested capability tier, or null when none applied

state - mutable run state — token total is read-add-written here

attempt - 1-based ordinal of this call within its dispatch

recordAttempt

public void recordAttempt(String agentId,
 String provider,
 LlmExecutionResponse response,
 String resolvedModel,
 ModelSource modelSource,
 ModelTier requestedModelTier,
 WorkflowState state,
 int attempt)

Records a discarded LLM call attempt for audit/usage purposes only. A schema-parse-retried attempt still consumed real, metered provider tokens even though its output was rejected and superseded by a later attempt in the same dispatch. Unlike observe(java.lang.String, java.lang.String, com.agentforge4j.llm.api.LlmExecutionResponse, java.lang.String, com.agentforge4j.runtime.llm.ModelSource, com.agentforge4j.llm.api.ModelTier, com.agentforge4j.core.workflow.state.WorkflowState, int), this does not update ReservedContextKeys.LLM_TOKENS_TOTAL — that running total tracks only the response the workflow actually used, which observe(java.lang.String, java.lang.String, com.agentforge4j.llm.api.LlmExecutionResponse, java.lang.String, com.agentforge4j.runtime.llm.ModelSource, com.agentforge4j.llm.api.ModelTier, com.agentforge4j.core.workflow.state.WorkflowState, int) records exactly once per dispatch.

Parameters:

agentId - the agent that triggered the call

provider - the provider name (e.g. "claude")

response - the full provider response including usage and model metadata

resolvedModel - the model the runtime resolved and sent; null when the provider default was used

modelSource - how the model was determined (pin, tier, or provider default)

requestedModelTier - the requested capability tier, or null when none applied

state - mutable run state

attempt - 1-based ordinal of this call within its dispatch