agent_transfer_test.go

Overview

This file contains a suite of tests validating the behavior of the agent transfer mechanism within LLM-based agents, specifically focusing on the TransferToAgentTool and the AgentTransferRequestProcessor function. These tests ensure that the agent transfer logic correctly modifies large language model (LLM) requests to facilitate delegation or transfer of tasks among agents in hierarchical or peer configurations.

Key functionalities tested include:

• Verification of tool metadata and declaration correctness.

• Proper injection of agent transfer instructions and tools into LLM requests.

• Handling of agent configurations with parents, peers, and subagents.

• Transfer restrictions (disallowing transfers to parents or peers).

• Correct operation of the transfer tool's runtime behavior.

• Interaction and integration of transfer tools with other tools and function declarations.

This test file interacts closely with components responsible for agent orchestration and LLM request construction, particularly those in the internal llminternal package and agent composition libraries.

Detailed Descriptions

TestAgentTransferRequestProcessor

This function tests the AgentTransferRequestProcessor method, which is responsible for modifying an LLM request to include instructions and tools for transferring tasks to other agents.

Key functionalities tested:

• Validates that the TransferToAgentTool has non-empty name, description, and declaration.

• Creates a parentmap from the root agent to track agent hierarchy.

• Sets up an invocation context for the current agent.

• Calls AgentTransferRequestProcessor to potentially modify the LLM request.

• Checks the resulting request for:

  • Inclusion of the transfer tool in the Tools dictionary.

  • Presence of transfer instructions mentioning the parent agent and subagents as expected.

  • Absence of instructions suggesting transfer to the current agent.

  • Correct addition of function declarations related to the transfer tool.

Parameters:

• t *testing.T: The testing context.

• curAgent agent.Agent: The current agent running the request.

• root agent.Agent: The root agent in the hierarchy.

• wantParent string: Expected name of the parent agent to transfer to (empty if none).

• wantAgents []string: Expected list of subagents or peers to transfer to.

• unwantAgents []string: List of agents that must not be suggested for transfer.

Usage:

The test runs multiple subtests simulating various agent topologies:

• Solo agent without peers or parents.

• Agents with parents and peers.

• Agents with subagents.

• Agents with transfer restrictions.

• Agents managed by parallel or sequential workflow agents.

These subtests verify that transfer instructions and tooling are correctly adapted to the agent's configuration and transfer policies.

TestAgentTransfer_ProcessRequest

This test validates the integration of the TransferToAgentTool in the LLM request processing pipeline.

Behavior tested:

• Creates a simple identity function tool and processes an empty LLM request using it.

• Processes the same request with the TransferToAgentTool.

• Verifies that exactly one tool is registered in the request config.

• Checks that two function declarations exist after processing (identity and transfer tool).

This confirms the tool's ability to augment LLM requests with appropriate function declarations and tooling required for agent transfer.

TestTransferToAgentToolRun

Tests the runtime behavior of the TransferToAgentTool's Run method, which executes the transfer to agent action.

Subtests:

• Success:
  Runs the tool with a valid agent_name argument and verifies that the tool sets the TransferToAgent field in the tool context's actions to the expected agent name.

• InvalidArguments:
  Tests various invalid argument scenarios such as missing agent_name, nil arguments, wrong argument types, or empty agent name strings, ensuring the tool returns errors as expected.

stringify

Helper function that converts any Go value into a JSON string representation. Used for debugging and error messages in test comparisons.

Important Implementation Details and Algorithms

• The tests rely on the parentmap utility to map the agent hierarchy, which is essential for determining valid transfer targets.

• The AgentTransferRequestProcessor applies logic to inject transfer instructions and tool declarations into the LLM request based on the current agent's relationship to others.

• Instruction validation uses substring containment checks and function declarations are verified by matching function names and descriptions.

• The transfer tool's Run method expects a single argument specifying the target agent name and sets this in a session event action to trigger transfer.

• Transfer restrictions such as DisallowTransferToParent and DisallowTransferToPeers are respected and tested to ensure transfer instructions exclude those agents.

• Subagents, peers, and parents are handled distinctly to tailor the transfer instructions properly.

Interactions with Other Parts of the System

• Agents: Works with the agent.Agent interface and various agent implementations such as LLM agents (llmagent), parallel agents (parallelagent), and sequential agents (sequentialagent).

• LLM Request: Modifies model.LLMRequest objects to embed transfer tooling and instructions, influencing downstream LLM behavior.

• Tools: Integrates with the modular tool framework (tool and functiontool) to augment requests and execute transfer commands.

• Invocation Context: Uses icontext.InvocationContext to track the current agent context and session state during request processing.

• Parent Map: Uses the parentmap package to resolve agent parent-child relationships for transfer logic.

• Utilities: Employs internal utilities for text and function declaration parsing (utils.TextParts and utils.FunctionDecls).

• Session and Event Actions: The transfer tool sets agent transfer actions in session event records, facilitating runtime agent switching.

These interactions enable the agent transfer mechanism to function seamlessly within the larger multi-agent orchestration and LLM integration framework described in LLM Integration and Agents.

Visual Diagram: Function Flow and Test Structure

flowchart TD
A[TestAgentTransferRequestProcessor] --> B[Setup TransferToAgentTool]
B --> C[Create parentmap from root agent]
C --> D[Create invocation context with current agent]
D --> E[Call AgentTransferRequestProcessor]
E --> F{Expect transfer?}
F -- No --> G[Assert no changes to LLMRequest]
F -- Yes --> H[Check Tools dictionary]
H --> I[Verify transfer tool present]
I --> J[Check system instructions]
J --> K[Validate presence/absence of agents]
K --> L[Check function declarations]
M[TestAgentTransfer_ProcessRequest] --> N[Create identity function tool]
N --> O[Process empty LLMRequest]
O --> P[Process LLMRequest with TransferToAgentTool]
P --> Q[Verify tools count]
Q --> R[Verify function declarations count]
S[TestTransferToAgentToolRun] --> T[Run with valid args]
S --> U[Run with invalid args]
T --> V[Check TransferToAgent action set]
U --> W[Expect errors]
subgraph Test Cases
A
M
S
end

This diagram illustrates the flow of key test functions and their main steps, showing how each test case sets up conditions, invokes the transfer logic, and verifies expected outcomes.

Summary of Key Components in This File

For further details on agent context and invocation, see Agent Invocation Context. For deeper understanding of agent lifecycle and callbacks, see Agent Lifecycle and Callbacks. The tool framework referenced here is detailed in Tooling System. The agent and LLM integration itself is part of LLM Integration and Agents.