tool_test.go

Overview

The tool_test.go file provides a comprehensive test suite for validating the behavior of the Exit Loop Tool within the context of looping workflow agents. This file focuses on verifying that the tool correctly signals the termination of looping operations controlled by the loopagent, specifically testing scenarios where the tool is invoked to exit a loop early, when loops run up to their maximum iteration count, and when the exit is triggered immediately.

The tests simulate interactions between a mocked LLM model, an LLM agent, the looping agent, and the exit loop tool, ensuring the integration works as expected. This file is critical to guarantee that the exit loop control mechanism behaves correctly in complex agent workflows.

Detailed Explanation of Key Components

TestExitLoopToolExitsLoopAgent

The single exported test function TestExitLoopToolExitsLoopAgent contains multiple subtests verifying various exit loop scenarios.

Purpose

• To ensure that the Exit Loop Tool effectively causes the loop agent to terminate its iterations early when the "exit_loop" function call is encountered.

• To confirm the loop agent respects the MaxIterations limit when no exit is triggered.

• To verify immediate loop termination if the exit signal is triggered on the very first iteration.

Structure

The test defines a slice of test cases, each having:

• name (string): Descriptive name of the scenario.

• mockResponses ([]*genai.Content): Simulated LLM outputs, including normal text and explicit function calls to "exit_loop".

• maxIterations (uint): Maximum allowed iterations before forcing loop termination.

• want ([]*genai.Content): Expected sequence of LLM content outputs after the loop agent runs.

Test Case Examples

• ExitLoopToolStopsMidLoop: The LLM responds normally for two iterations, then issues the "exit_loop" function call. The loop agent should terminate immediately after processing the exit function call and produce the corresponding function response event.

• MaxIterationsStopsLoop: The LLM never calls "exit_loop", so the loop agent terminates after reaching the maxIterations limit.

• ExitLoopToolStopsImmediately: The first LLM response is an "exit_loop" function call, causing immediate loop termination.

Test Execution Flow

For each test case:

1. Setup

   • Instantiate a MockModel with the predefined mockResponses to simulate LLM outputs.

   • Create an instance of the exit loop tool (exitlooptool.New()).

   • Create an LLM agent (llmagent.New) configured with the mock model and the exit loop tool.

   • Create a looping agent (loopagent.New) configured with the LLM agent as its sub-agent and the specified maxIterations.

   • Initialize a test runner (testutil.NewTestAgentRunner) to run the looping agent.

2. Execution

   • Call runner.Run with a message to trigger the looping agent interaction.

   • Iterate over the event stream responses.

3. Assertions

   • Validate that the number of events matches the expected count.

   • Compare each generated event's content with the expected content, ignoring certain fields (ID) to allow flexibility in generated function call/response identifiers.

   • Fail the test if extra or fewer events are produced or if the content differs from expectations.

Parameters

• t *testing.T: Go's standard testing interface used to manage test lifecycle and assertions.

Return Value

• None; test failures are reported via t.Fatalf or t.Errorf.

Important Implementation Details

• MockModel: Used to simulate an LLM model by returning predefined content responses sequentially. This enables deterministic testing of agent and tool interactions.

• Exit Loop Tool Integration: The tool is included in the LLM agent’s toolset, allowing the LLM to issue a function call "exit_loop", which triggers loop termination logic.

• Event Stream Consumption: The test consumes a streaming output channel (ev), which yields events or errors, simulating real-time agent output.

• Comparisons Use go-cmp: The cmp package is employed to perform deep comparisons of content, with options to ignore certain fields that do not affect logic correctness.

• Escalation Handling: The actual exit loop mechanism is tested indirectly by verifying that the content stream ends appropriately after the exit function call and the tool’s function response.

Interactions with Other System Components

• exitlooptool Package: The file tests the tool implemented in this package, which provides the "exit_loop" function call to signal loop termination within looping agents.

• llmagent Package: The looping agent uses an LLM agent as a sub-agent; this LLM agent includes the exit loop tool in its toolset.

• loopagent Package: The loop agent executes the sub-agent repeatedly until it either receives a request to exit or reaches a maximum iteration count.

• testutil Package: Provides mocks (MockModel) and utilities (TestAgentRunner) for simulating agent execution and capturing output events in a controlled test environment.

• genai Package: Defines the structure for LLM content (genai.Content) representing text, function calls, and function responses.

This interplay ensures the exit loop tool is tested in a realistic agent workflow that involves looping, LLM generation, and tool invocation.

Usage Example

Within the test suite, a typical usage scenario looks like this (simplified pseudocode):

mockModel := &testutil.MockModel{Responses: testCase.mockResponses}
exitLoopTool, _ := exitlooptool.New()

agent, _ := llmagent.New(llmagent.Config{
	Name:  "simple agent",
	Model: mockModel,
	Tools: []tool.Tool{exitLoopTool},
})

loopAgent, _ := loopagent.New(loopagent.Config{
	AgentConfig: agent.Config{
		Name:      "looper",
		SubAgents: []agent.Agent{agent},
	},
	MaxIterations: testCase.maxIterations,
})

runner := testutil.NewTestAgentRunner(t, loopAgent)
events := runner.Run(t, "id", "message")

for event := range events {
	// Assertions to verify event content match expected outputs
}

This test pattern validates the exit loop tool's ability to terminate loops under various conditions.

Mermaid Diagram

flowchart TD
A[TestExitLoopToolExitsLoopAgent] --> B[Setup MockModel with Responses]
B --> C[Create ExitLoopTool]
C --> D[Create LLMAgent with MockModel and ExitLoopTool]
D --> E[Create LoopAgent with LLMAgent & MaxIterations]
E --> F[Start TestAgentRunner]
F --> G[Run LoopAgent]
G --> H{Iterate over Events}
H -->|Compare Event Content| I[Validate Output Matches Expected]
H -->|Error or Extra Events| J[Fail Test]
I --> K[All Events Matched?]
K -->|Yes| L[Test Pass]
K -->|No| J

References to Related Topics

• The tests validate the behavior of the Exit Loop Tool implemented as a function tool in the Exit Loop Tool subtopic.

• The looping workflow agent under test is detailed in the Loop Agent topic which supports repeated execution of sub-agents and handles loop termination signals.

• The test uses the LLM Agent Configuration and LLM Integration and Agents concepts to configure and simulate the LLM agent environment.

• The Tooling System topic provides context on the modular tool framework including function tools and their invocation.

• The Agent Execution Runner is referenced indirectly via the testutil.NewTestAgentRunner which manages agent execution lifecycle in tests.

This documentation describes the purpose, structure, and functionality of the tool_test.go file, focusing on the testing of the exit loop mechanism within looping agents and its interaction with LLM agents and tools.