loader.go

Overview

The loader.go file defines the Loader interface and two concrete implementations—singleLoader and multiLoader—for managing and retrieving AI agents in the system by their names. This abstraction enables flexible loading and access to agents, whether there is a single root agent or multiple named agents managed together.

The primary responsibilities of this file are:

Providing a unified interface (Loader) to list available agents, load agents by name, and retrieve the root agent.
Implementing singleLoader for scenarios with only one agent.
Implementing multiLoader for scenarios with multiple agents, ensuring unique agent names.
Handling error conditions such as duplicate agent names or requests for non-existent agents.

This file plays a critical role in the AI Agent Framework by enabling agent discovery and management, supporting higher-level workflows that invoke agents dynamically by name.

Interfaces and Types

Loader Interface

type Loader interface {
    ListAgents() []string
    LoadAgent(name string) (Agent, error)
    RootAgent() Agent
}

Purpose: Abstracts agent loading mechanisms.
Methods:
- ListAgents() []string: Returns the list of all available agent names.
- LoadAgent(name string) (Agent, error): Loads an agent by its name; returns error if no agent with that name exists.
- RootAgent() Agent: Returns the root agent, considered the primary or default agent.

singleLoader

type singleLoader struct {
    root Agent
}

Purpose: Implements Loader for a single-agent environment.
Fields:
- root: The only agent instance and the root agent.

Methods

ListAgents() []string
Returns a slice containing only the root agent’s name.
LoadAgent(name string) (Agent, error)
Loads the root agent if name is empty or matches the root’s name. Otherwise, returns an error indicating the valid names.
RootAgent() Agent
Returns the root agent directly.

Usage Example

rootAgent := ... // some Agent instance
loader := NewSingleLoader(rootAgent)

names := loader.ListAgents() // returns []string{rootAgent.Name()}
agent, err := loader.LoadAgent("") // returns rootAgent

multiLoader

type multiLoader struct {
    agentMap map[string]Agent
    root     Agent
}

Purpose: Implements Loader for multiple agents.
Fields:
- agentMap: A map from agent names to their corresponding Agent instances.
- root: The designated root agent among the collection.

Construction

func NewMultiLoader(root Agent, agents ...Agent) (Loader, error)

Creates a multiLoader containing the root agent plus zero or more additional agents.
Enforces unique agent names; returns an error if duplicates are found.
Returns the constructed loader or an error.

Methods

ListAgents() []string
Returns a list of all agent names managed by this loader (including the root).
LoadAgent(name string) (Agent, error)
Returns the agent matching the provided name or an error listing all available agents if not found.
RootAgent() Agent
Returns the root agent instance.

Usage Example

rootAgent := ... // Agent instance
agent1 := ...    // Agent instance
agent2 := ...    // Agent instance

loader, err := NewMultiLoader(rootAgent, agent1, agent2)
if err != nil {
    // handle duplicate name error
}

allNames := loader.ListAgents() // returns slice with all agent names
agent, err := loader.LoadAgent("agent1") // returns agent1 instance

Important Implementation Details

multiLoader uses a map keyed by agent names for O(1) lookup in LoadAgent.
Duplicate agent names are prevented in NewMultiLoader to avoid ambiguity.
singleLoader simplifies the interface by only allowing loading the single root agent.
When loading an unknown agent, multiLoader returns an error listing all valid agent names to aid debugging.

Interaction with Other System Components

The Loader interface and implementations interact closely with the Agent interface defined in the AI Agent Framework (AI Agent Framework).
The loader is typically used by higher-level components to dynamically select and invoke agents by name, such as agent runners or workflow managers (Agent Workflow Management, Agent Execution Runner).
It supports scenarios from simple single-agent projects to complex multi-agent systems, enabling modular and scalable agent invocation.

Mermaid Diagram: Loader Structure and Relationships

classDiagram
class Loader {
+ListAgents()
+LoadAgent()
+RootAgent()
}
class singleLoader {
-root: Agent
+ListAgents()
+LoadAgent()
+RootAgent()
}
class multiLoader {
-agentMap: map[string]Agent
-root: Agent
+ListAgents()
+LoadAgent()
+RootAgent()
}
Loader <|.. singleLoader
Loader <|.. multiLoader

Summary

The loader.go file provides a clear and extendable abstraction for managing collections of agents, facilitating agent discovery and retrieval by name. The distinction between single and multi-agent loaders simplifies usage depending on application complexity. Error handling ensures robustness when accessing agents dynamically.

For detailed information about the Agent interface and its lifecycle, refer to the subtopics: