Module agentforge4j.runtime
Package com.agentforge4j.runtime.llm

Class AgentInvoker

java.lang.Object
com.agentforge4j.runtime.llm.AgentInvoker
public final class AgentInvoker extends Object
Drives a single agent invocation: resolves the agent definition, picks the first enabled provider preference, renders the input context as JSON, executes against the resolved LlmClient, and parses the structured command output.

  • Field Details

    • DEFAULT_LLM_OUTPUT_EVENT_CHAR_CAP

      public static final int DEFAULT_LLM_OUTPUT_EVENT_CHAR_CAP
      Default maximum characters recorded per WorkflowEventType.LLM_OUTPUT event.
      See Also:

    • DEFAULT_TOOL_CATALOG_CHAR_CAP

      public static final int DEFAULT_TOOL_CATALOG_CHAR_CAP
      Default maximum characters for the rendered, untrusted tool-catalog section appended to the system prompt. A registered MCP/HTTP tool server is an external, untrusted-provenance source; without a bound, an oversized description()/inputSchema() could mount a prompt-stuffing/token-cost attack. 0 disables truncation.
      See Also:

  • Method Details

    • builder

      public static AgentInvoker.Builder builder()
      Returns a new builder for AgentInvoker.
      Returns:
      new builder; never null

    • invoke

      public AgentInvocationResult invoke(String agentId, ContextMapping contextMapping, WorkflowState state, String stepPrompt)
      Invokes an agent without a step-level tier override (equivalent to passing null).
      Parameters:
      agentId - the agent to invoke; must not be blank
      contextMapping - context mapping for input rendering; must not be null
      state - mutable run state; must not be null
      stepPrompt - optional static step prompt material; may be blank
      Returns:
      the parsed invocation result; never null

    • invoke

      public AgentInvocationResult invoke(String agentId, ContextMapping contextMapping, WorkflowState state, String stepPrompt, String stepModelTier)
      Invokes an agent, optionally overriding the agent's capability tier for this step. Callers without an active-workflow context use the run's root workflow id (from state) as the invocation identity's workflow id; callers driving a nested workflow should use the activeWorkflowId overload so the identity reflects the innermost active workflow.
      Parameters:
      agentId - the agent to invoke; must not be blank
      contextMapping - context mapping for input rendering; must not be null
      state - mutable run state; must not be null
      stepPrompt - optional static step prompt material; may be blank
      stepModelTier - optional step-level tier name overriding the agent tier; null or blank inherits the agent tier
      Returns:
      the parsed invocation result; never null

    • invoke

      public AgentInvocationResult invoke(String agentId, ContextMapping contextMapping, WorkflowState state, String stepPrompt, String stepModelTier, String activeWorkflowId)
      Invokes an agent, carrying the innermost active workflow id onto the invocation identity. The run executes under a single root run/state (WorkflowState.workflowId is the root and is immutable), so the active workflow id of a nested workflow is not recoverable from state — the caller (which holds the execution context) supplies it here so that LlmInvocationIdentity.workflowId() distinguishes steps of different nested workflows under one run.
      Parameters:
      agentId - the agent to invoke; must not be blank
      contextMapping - context mapping for input rendering; must not be null
      state - mutable run state; must not be null
      stepPrompt - optional static step prompt material; may be blank
      stepModelTier - optional step-level tier name overriding the agent tier; null or blank inherits the agent tier
      activeWorkflowId - innermost active workflow id for this call (the run's root workflow id when not nested); must not be blank
      Returns:
      the parsed invocation result; never null