llmagent.go

Overview

The llmagent.go file implements the LLMAgent, a specialized AI agent that integrates a large language model (LLM) with extensible tools, instructions, and lifecycle callbacks. This agent serves as a central component within the [LLM Integration and Agents](80562) system, providing a configurable interface to execute LLM-driven workflows, handle sub-agent delegation, and interact with session state.

The file defines the configuration schema (Config) for constructing an LLMAgent, the agent’s main struct (llmAgent), callback types for hooking into model and tool invocations, and the primary execution logic. It also manages dynamic instruction injection and stateful output persistence for multi-turn conversational AI scenarios.

Key Entities and Components

Config Struct

Config encapsulates all parameters required to initialize and configure an LLMAgent. It includes:

• Identification and Description

  • Name (string): Unique non-empty identifier for the agent in the agent tree; cannot be "user".

  • Description (string): One-line description of agent capabilities, used by the LLM to decide delegation.

• Agent Composition

  • SubAgents ([]agent.Agent): Child agents that this agent can delegate tasks to.

• Lifecycle Callbacks

  • BeforeAgentCallbacks ([]agent.BeforeAgentCallback): Invoked before the agent starts; can short-circuit execution.

  • AfterAgentCallbacks ([]agent.AfterAgentCallback): Invoked after the agent completes; can generate additional events.

• Model and Content Generation

  • Model (model.LLM): The LLM backend powering the agent.

  • GenerateContentConfig (*genai.GenerateContentConfig): Optional model generation parameters (e.g., temperature).

• Model Callbacks

  • BeforeModelCallbacks ([]BeforeModelCallback): Called before LLM request; can modify request or return cached responses.

  • AfterModelCallbacks ([]AfterModelCallback): Called after LLM response; can modify or replace the response.

• Instructions

  • Instruction (string): Static template guiding LLM behavior, supporting placeholders for session state and artifacts.

  • InstructionProvider (InstructionProvider): Optional dynamic instruction generator, overrides Instruction.

  • GlobalInstruction (string): Instruction for the entire agent tree; only root agent’s global instruction applies.

  • GlobalInstructionProvider (InstructionProvider): Dynamic provider overriding GlobalInstruction.

• Transfer Restrictions

  • DisallowTransferToParent (bool): Prevent agent transfer to parent.

  • DisallowTransferToPeers (bool): Prevent agent transfer to peer agents.

• Content Inclusion

  • IncludeContents (IncludeContents): Controls inclusion of conversation history in model requests (none or default).

• Input/Output Schema

  • InputSchema (*genai.Schema): Schema for validating input when agent is used as a tool.

  • OutputSchema (*genai.Schema): Schema for agent replies; restricts use of tools if set.

• Tooling

  • BeforeToolCallbacks ([]BeforeToolCallback): Called before tool execution; can alter args or skip tool.

  • Tools ([]tool.Tool): Tools available to the agent.

  • AfterToolCallbacks ([]AfterToolCallback): Called after tool execution; can modify results.

  • Toolsets ([]tool.Toolset): Toolsets integrated with the agent.

• Output Handling

  • OutputKey (string): Optional key in session state to save agent output.

Callback Types

• BeforeModelCallback

type BeforeModelCallback func(ctx agent.CallbackContext, llmRequest *model.LLMRequest) (*model.LLMResponse, error)

Called before sending the LLM request. Returning a non-nil response or error skips the actual model call.

• AfterModelCallback

type AfterModelCallback func(ctx agent.CallbackContext, llmResponse *model.LLMResponse, llmResponseError error) (*model.LLMResponse, error)

Called after receiving the LLM response. Returning a non-nil response or error replaces the actual model response/error.

• BeforeToolCallback

type BeforeToolCallback func(ctx tool.Context, tool tool.Tool, args map[string]any) (map[string]any, error)

Called before invoking a tool's Run method. Returning a non-nil result or error short-circuits tool execution.

• AfterToolCallback

type AfterToolCallback func(ctx tool.Context, tool tool.Tool, args, result map[string]any, err error) (map[string]any, error)

Called after tool execution regardless of success or failure. Allows modification of the tool’s result or error.

IncludeContents Enum

Controls whether prior conversation history is included in LLM requests:

• IncludeContentsNone: No prior conversation included; only current turn is used.

• IncludeContentsDefault: Default behavior including relevant conversation history.

llmAgent Struct

The core agent struct embedding:

• agent.Agent: The base agent interface.

• llminternal.State: Internal state including model, tools, instruction providers, etc.

• agentState: Alias for internal agent state.

• Callback slices for before/after model and tool invocations.

• Configured instruction strings and schemas.

InstructionProvider

type InstructionProvider func(ctx agent.ReadonlyContext) (string, error)

A function type for dynamic generation of instructions at each invocation. Overrides static instructions if provided.

Main Functions and Methods

New(cfg Config) (agent.Agent, error)

Constructor that creates a new LLMAgent instance from the provided configuration.

• Parameters:

  • cfg: Configuration struct specifying all agent parameters.

• Returns:

  • agent.Agent: The created LLMAgent implementing the agent.Agent interface.

  • error: Non-nil if agent creation fails.

• Functionality:

  • Converts user-provided model and tool callbacks into internal callback types.

  • Initializes the llmAgent struct with state and configuration.

  • Creates a base agent via agent.New with lifecycle callbacks and the LLMAgent's run method.

  • Sets agent type to TypeLLMAgent internally.

  • Returns the fully constructed agent or an error on failure.

• Usage Example:

cfg := llmagent.Config{
    Name:        "example-agent",
    Description: "Handles user queries with LLM",
    Model:       myLLMModel,
    Tools:       []tool.Tool{myTool},
    Instruction: "Answer concisely.",
}
agent, err := llmagent.New(cfg)
if err != nil {
    log.Fatalf("Failed to create agent: %v", err)
}

(a *llmAgent) run(ctx agent.InvocationContext) iter.Seq2[*session.Event, error]

The core execution method invoked when the LLMAgent runs.

• Parameters:

  • ctx: The invocation context containing session, memory, artifacts, user content, and run configuration.

• Returns:

  • An iterator sequence producing session.Event objects or an error.

• Functionality:

  • Wraps the invocation context with internal context that includes agent state and other runtime parameters.

  • Constructs an llminternal.Flow object which orchestrates model and tool calls, applying configured callbacks and processors.

  • Runs the flow, yielding session events representing partial or full LLM responses, tool calls, or other agent events.

  • Calls maybeSaveOutputToState to persist output text to session state if configured.

  • Supports streaming and early termination by yielding events until the caller stops iteration.

(a *llmAgent) maybeSaveOutputToState(event *session.Event)

Conditionally saves the textual output from an LLM response event into the session state under the configured OutputKey.

• Parameters:

  • event: The session event potentially containing model output.

• Behavior:

  • Skips saving if the event is nil, authored by another agent, or is a partial event.

  • Aggregates all text parts from the event content excluding "thought" parts.

  • If an output schema is defined, skips saving empty or whitespace-only results.

  • Inserts the aggregated string into the event’s StateDelta map under OutputKey.

• Purpose:

  • Enables downstream agents or workflows to access the textual output generated by this agent.

Implementation Details and Algorithms

• Callback Wrapping: The New constructor converts user-provided callbacks into internal callback types to enforce consistent signatures and integration with the internal flow.

• Flow-Based Execution: The run method leverages llminternal.Flow, a reusable orchestration engine that handles LLM request/response cycles, tool invocation, and lifecycle callbacks.

• Instruction Templating: Instructions can be static templates or dynamically generated via InstructionProvider. Templates support placeholders resolved at runtime with session state or artifact contents, following the conventions described in Instruction Template Processing.

• Stateful Output Saving: The agent captures output text from LLM events and saves it under a configurable key in the session state, enabling persistent multi-turn dialogues and agent chaining.

• Event Streaming: The run method returns a sequence generator of session.Event objects, allowing streaming responses to clients or intermediate processing.

Interaction with Other System Components

• Agent Framework (AI Agent Framework 80561): The llmAgent implements the generic agent.Agent interface and embeds a base agent created through the core agent framework, enabling hierarchical agent composition and lifecycle management.

• Session Management (Session Management 80559): The agent reads from and writes to the session state, storing conversation history and output results, leveraging session events and state deltas.

• Tooling System (Tooling System 80556): Tools and toolsets configured in the agent provide callable extensions invoked during LLM function calls, with callbacks enabling interception before and after tool execution.

• Instruction Injection (Instruction Template Processing 80563): Instruction strings or providers rely on dynamic injection and resolution of session variables and artifact data at runtime.

• Telemetry and Observability (Telemetry and Observability 80566): Callback hooks serve as extension points to trace and monitor LLM and tool invocations.

• Agent Execution Runner (Agent Execution Runner 80560): The LLMAgent is executed within sessions by the runner which manages session event appending and agent selection logic.

Visual Diagram of Agent Structure and Relationships

classDiagram
class Config {
+string Name
+string Description
+[]Agent SubAgents
+[]BeforeAgentCallback BeforeAgentCallbacks
+[]AfterAgentCallback AfterAgentCallbacks
+GenerateContentConfig GenerateContentConfig
+[]BeforeModelCallback BeforeModelCallbacks
+model.LLM Model
+[]AfterModelCallback AfterModelCallbacks
+string Instruction
+InstructionProvider InstructionProvider
+string GlobalInstruction
+InstructionProvider GlobalInstructionProvider
+bool DisallowTransferToParent
+bool DisallowTransferToPeers
+IncludeContents IncludeContents
+*genai.Schema InputSchema
+*genai.Schema OutputSchema
+[]BeforeToolCallback BeforeToolCallbacks
+[]tool.Tool Tools
+[]AfterToolCallback AfterToolCallbacks
+[]tool.Toolset Toolsets
+string OutputKey
}
class llmAgent {
+Agent Agent
+State llminternal.State
+[]BeforeModelCallback beforeModelCallbacks
+model.LLM model
+[]AfterModelCallback afterModelCallbacks
+string instruction
+[]BeforeToolCallback beforeToolCallbacks
+[]AfterToolCallback afterToolCallbacks
+*genai.Schema inputSchema
+*genai.Schema outputSchema
+run()
+maybeSaveOutputToState()
}
Config --> llmAgent : Instantiates
llmAgent --> model.LLM : Uses
llmAgent --> tool.Tool : Integrates Tools
llmAgent --> agent.Agent : Embeds Base Agent
llmAgent --> llminternal.State : Maintains State
llmAgent --> BeforeModelCallback : Executes
llmAgent --> AfterModelCallback : Executes
llmAgent --> BeforeToolCallback : Executes
llmAgent --> AfterToolCallback : Executes

This documentation provides a detailed technical description of the llmagent.go file’s purpose, entities, functions, and internal mechanisms, referencing relevant sections of the broader system for context.