runner_test.go

Overview

This file contains unit tests for key functionalities of the runner package, which is responsible for managing the execution of AI agents within user sessions. The tests primarily focus on verifying the correct behavior of agent selection, transfer permission logic, and the handling of input blobs as artifacts during agent execution.

These tests ensure that:

The runner correctly identifies which agent to run based on session event history and transfer permissions.
The recursive agent search (findAgent) behaves as expected with various agent tree configurations.
Transfer permission checks (isTransferableAcrossAgentTree) enforce agent-level policies correctly.
The runner saves inline blob data from user messages as artifacts, replacing the original inline data with a text placeholder, and persists these artifacts appropriately.

This file plays a vital role in maintaining the integrity of the Agent Execution Runner and its associated features, including Agent Selection Logic and Input Blob Artifact Saving.

Detailed Explanation of Tests and Functions

TestRunner_findAgentToRun

Purpose:
Verifies that the runner's findAgentToRun method selects the correct agent to process a user message based on the session event history and agent transfer permissions.

Test Setup:

Creates an agent tree with a root agent and two sub-agents: one that disallows transfer (DisallowTransferToParent = true) and one that allows transfer.
Creates sessions with different event patterns to simulate various last-event conditions.

Test Cases:

Case Name	Session Events	Expected Agent Selected
last event from agent allowing transfer	Last agent event from agent allowing transfer, then user event	Allows transfer agent
last event from agent not allowing transfer	Last agent event from agent disallowing transfer, then user event	Root agent
no events from agents, call root	Only user events, no agent events	Root agent

Key Assertions:

The agent returned by findAgentToRun matches the expected agent.
No error occurs unless explicitly expected.

Test_findAgent

Purpose:
Tests the recursive findAgent function that searches for an agent by name within an agent tree.

Test Setup:

Uses a multi-node agent tree and a single-node agent.
Tests various search scenarios including missing agents and empty trees.

Test Cases:

Case Name	Root Agent	Target Agent Name	Expected Result
ok	Multi-node tree	Name of allowsTransferAgent	AllowsTransferAgent
finds in one node tree	Single agent	Single agent's own name	Single agent
doesn't fail if missing	Multi-node tree	"random" (non-existent)	nil
doesn't fail on empty tree	nil	"random"	nil

Key Assertions:

The function returns the agent if found, otherwise nil, without errors.

Test_isTransferrableAcrossAgentTree

Purpose:
Validates the runner's logic to check if an agent and its parents allow transfer of control within the agent tree.

Test Setup:
Tests different agent configurations:

An LLM agent with DisallowTransferToParent: true.
A non-LLM agent.
A default LLM agent without transfer restrictions.

Test Cases:

Case Name	Agent Configuration	Expected Result (Transfer Allowed)
disallow for agent with flag	`DisallowTransferToParent = true`	false
disallow for non-LLM agent	Non-LLM agent type	false
allow for default LLM agent	LLM agent without restrictions	true

Key Assertions:

The isTransferableAcrossAgentTree method returns the expected boolean for transfer permission.

TestRunner_SaveInputBlobsAsArtifacts

Purpose:
Tests the runner's ability to detect inline blobs in user messages, save them as artifacts, and replace inline data with a placeholder text in the session event.

Test Setup:

Initializes in-memory session and artifact services.
Creates a basic agent that does not produce output events (no-op).
Creates a user message with two parts: text and inline blob data.
Sets SaveInputBlobsAsArtifacts to true in the run configuration.

Test Workflow:

Calls Run on the runner, which triggers the blob saving and message appending logic.
Checks the artifact service to confirm the blob was saved with an auto-generated filename.
Loads the saved artifact and confirms the data matches the original blob.
Retrieves the session and verifies the user event's blob part was replaced by the placeholder text referencing the artifact filename.

Key Assertions:

Exactly one artifact file is saved.
The saved artifact data matches the original blob.
The session event replaces inline blob data with the expected placeholder text.
The session event author is correctly set as "user".
The message contains 2 parts with the second part’s inline data removed.

Helper Functions

agentTree(t *testing.T) agentTreeStruct

Creates a test agent tree with a root agent and two sub-agents:

noTransferAgent: LLM agent with DisallowTransferToParent: true.
allowsTransferAgent: LLM agent allowing transfer.
root: parent LLM agent with the two sub-agents as children.

Returns references to these agents for use in tests.

must[T agent.Agent](a T, err error) T

Utility function that panics on error and returns the agent otherwise. Used to simplify agent creation in tests.

createSession

Creates a session with the given events appended. Uses the in-memory session service and appends the specified events to the session for test setup.

Parameters:

t *testing.T — testing instance for error handling.
ctx context.Context — context for service calls.
sessionID, appName, userID string — identifiers for the session.
events []*session.Event — events to append to the new session.

Returns the created session.Session.

Important Implementation Details

The tests leverage the in-memory services (session.InMemoryService, artifact.InMemoryService) for isolated and repeatable testing without external dependencies.
Agent trees are constructed with llmagent.New to simulate LLM-based agents with specific configurations, especially the DisallowTransferToParent flag which controls transfer permissions.
The recursive findAgent function is tested with multiple tree shapes, including empty and single-node trees, to ensure robustness.
Blob saving logic is verified by comparing saved artifact data with the original input blob and checking the session event's message part replacement.
Parallel test execution is enabled for TestRunner_findAgentToRun using t.Parallel() for better test performance.

Interaction With Other System Components

Agent Execution Runner: This test file validates critical parts of the runner's workflow, especially agent selection and artifact handling.
Session Management: Uses the in-memory session service to create, retrieve, and append events to sessions, simulating conversation histories.
Artifact Management: Verifies integration with the artifact service for saving and loading blobs as artifacts, ensuring persistence of binary data.
LLM Integration and Agents: Utilizes LLM agent configurations to test transfer permissions and agent hierarchy behaviors.
Agent Selection Logic: Directly tests the selection of agents based on session event authorship and transfer policies.
Input Blob Artifact Saving: Confirms that inline blob data is properly offloaded to artifacts before agent execution.

Visual Diagram: Structure of runner_test.go

flowchart TD
RunnerTest[TestRunner_findAgentToRun]
FindAgentTest[Test_findAgent]
TransferTest[Test_isTransferrableAcrossAgentTree]
SaveBlobTest[TestRunner_SaveInputBlobsAsArtifacts]
agentTreeFunc[agentTree Helper]
mustFunc[must Helper]
createSessionFunc[createSession Helper]
RunnerTest --> agentTreeFunc
FindAgentTest --> agentTreeFunc
TransferTest --> mustFunc
SaveBlobTest --> mustFunc
SaveBlobTest --> createSessionFunc
RunnerTest --> FindAgentTest
RunnerTest --> TransferTest
RunnerTest --> SaveBlobTest

This diagram shows the main test functions and their relationships to helper utilities within the file.

Usage Examples from Tests

Example: Selecting Agent Based on Last Transferable Agent Event

r := &Runner{
    rootAgent: rootAgent,
}
agent, err := r.findAgentToRun(session)
if err != nil {
    // handle error
}
fmt.Println("Agent selected:", agent.Name())

Example: Saving Input Blob as Artifact During Run

cfg := agent.RunConfig{
    SaveInputBlobsAsArtifacts: true,
}
for _, err := range runner.Run(ctx, userID, sessionID, userMessage, cfg) {
    if err != nil {
        // handle error
    }
}

This documentation outlines the test coverage and verification strategies for critical components of the runner package, focusing on agent selection and input blob artifact saving logic. It references the Agent Execution Runner, Agent Selection Logic, and Input Blob Artifact Saving topics for deeper understanding of the underlying mechanisms.