launcher.go

Overview

The launcher.go file defines the foundational interfaces and configuration structures for running ADK (Agent Development Kit) applications. It provides abstractions for command-line application launchers, supporting both monolithic and composable modes of operation. The file introduces two main launcher interfaces — Launcher and SubLauncher — to facilitate flexible execution patterns, including modular subcommands (or sub-launchers) that represent different operational modes (e.g., console or web modes).

Additionally, it defines the Config struct that encapsulates core services required for agent execution, such as session management, artifact storage, memory, and agent loading. This configuration object acts as a dependency injection container, enabling launchers and sublaunchers to operate with the necessary platform services.

The file serves as a key integration point between the command-line interface layer and the lower-level agent runtime components, bridging user input parsing with the invocation of agent workflows and services.

Types and Interfaces

Launcher Interface

type Launcher interface {
	Execute(ctx context.Context, config *Config, args []string) error
	CommandLineSyntax() string
}

Description

Launcher is the primary interface representing an ADK application launcher. It is responsible for parsing command-line arguments and executing the launcher logic accordingly.

Methods

• Execute

  • Signature: Execute(ctx context.Context, config *Config, args []string) error

  • Parameters:

    • ctx - Context for cancellation and deadlines.

    • config - Configuration object providing access to required services.

    • args - Command-line arguments passed to the launcher.

  • Return: An error if execution fails; otherwise nil.

  • Usage: This method parses the command-line arguments and triggers the corresponding launcher behavior, such as starting an agent session or launching a web UI.

• CommandLineSyntax

  • Signature: CommandLineSyntax() string

  • Return: A string describing the expected command-line flags and arguments.

  • Usage: Used to provide user-facing help or usage instructions.

SubLauncher Interface

type SubLauncher interface {
	Keyword() string
	Parse(args []string) ([]string, error)
	CommandLineSyntax() string
	SimpleDescription() string
	Run(ctx context.Context, config *Config) error
}

Description

SubLauncher represents a modular launcher that can be composed into a parent launcher. Each sublauncher corresponds to a distinct mode or command, enabling extensible CLI behavior. For example, sublaunchers might handle different interaction modes like "console" or "web".

Methods

• Keyword

  • Signature: Keyword() string

  • Return: The command-line keyword that activates this sublauncher.

  • Usage: Enables the parent launcher to identify which sublauncher to invoke based on the user’s input.

• Parse

  • Signature: Parse(args []string) ([]string, error)

  • Parameters:

    • args - The command-line arguments relevant to this sublauncher.

  • Return:

    • Remaining unparsed arguments.

    • An error if parsing fails.

  • Usage: Parses sublauncher-specific flags and arguments, allowing argument validation and extraction.

• CommandLineSyntax

  • Signature: CommandLineSyntax() string

  • Return: A string describing this sublauncher's flags and arguments for help output.

• SimpleDescription

  • Signature: SimpleDescription() string

  • Return: A brief one-line description of the sublauncher's purpose.

• Run

  • Signature: Run(ctx context.Context, config *Config) error

  • Parameters:

    • ctx - Context for execution control.

    • config - Shared configuration object with necessary services.

  • Return: An error if the sublauncher fails to run; otherwise nil.

  • Usage: Executes the main logic of the sublauncher, such as starting a web server or launching an interactive console.

Config Struct

type Config struct {
	SessionService  session.Service
	ArtifactService artifact.Service
	MemoryService   memory.Service
	AgentLoader     agent.Loader
	A2AOptions      []a2asrv.RequestHandlerOption
}

Description

Config holds the key service dependencies and options required by launchers and sublaunchers to run ADK agents and sessions.

Fields

• SessionService (session.Service): Manages user-agent interaction sessions, including state persistence and event history. Refer to Session Management for details.

• ArtifactService (artifact.Service): Provides storage, retrieval, and versioning of artifacts such as files and blobs. See Artifact Management.

• MemoryService (memory.Service): Manages agent memory, enabling stateful conversations and data retention across agent invocations.

• AgentLoader (agent.Loader): Loads agent definitions and implementations into the runtime environment.

• A2AOptions ([]a2asrv.RequestHandlerOption): Configuration options for Agent-To-Agent (A2A) communication handlers, supporting distributed multi-agent scenarios. See Remote Agent Communication (A2A).

Important Implementation Details

• The abstraction of Launcher and SubLauncher allows for a flexible CLI architecture where different modes can be plugged in and composed, facilitating extensibility and modularity.

• The Config struct centralizes service dependencies, promoting loose coupling and enabling dependency injection patterns.

• This design separates command-line parsing (Parse methods) from execution (Run/Execute methods), enabling clean separation of concerns.

• By using interfaces for session, artifact, memory, and agent loading services, the launcher can operate with various implementations (e.g., in-memory, database-backed) without modification.

• The inclusion of A2AOptions hints at integrated support for distributed agent communication, enabling scalability and remote agent orchestration.

Interactions with Other System Components

• Session Service: The launcher depends on session management to maintain persistent user-agent interaction contexts during execution. This links directly to the Session Management topic.

• Artifact Service: Used for managing files and data blobs related to agent workflows, as described in Artifact Management.

• Memory Service: Provides persistent or transient memory for agents, enabling contextual awareness across interactions.

• Agent Loader: Responsible for loading agent definitions and implementations into the launcher’s runtime environment, tying into the AI Agent Framework.

• A2A Request Handlers: These options configure the launcher to enable remote agent communication over the A2A protocol, facilitating distributed multi-agent workflows (Remote Agent Communication (A2A)).

• The launcher acts as the entry point that orchestrates these services for starting and managing agent execution lifecycles, bridging user commands with runtime agent behavior.

Example Usage

func main() {
    ctx := context.Background()

    // Setup configuration with required services
    config := &launcher.Config{
        SessionService:  mySessionService,
        ArtifactService: myArtifactService,
        MemoryService:   myMemoryService,
        AgentLoader:     myAgentLoader,
        A2AOptions:      []a2asrv.RequestHandlerOption{},
    }

    // Instantiate a concrete launcher implementing Launcher interface
    var l launcher.Launcher = NewUniversalLauncher()

    // Execute launcher with command-line args
    if err := l.Execute(ctx, config, os.Args[1:]); err != nil {
        log.Fatalf("Launcher failed: %v", err)
    }
}

Diagram: Launcher Structure and Relationships

classDiagram
class Launcher {
+Execute()
+CommandLineSyntax()
}
class SubLauncher {
+Keyword()
+Parse()
+CommandLineSyntax()
+SimpleDescription()
+Run()
}
class Config {
+SessionService
+ArtifactService
+MemoryService
+AgentLoader
+A2AOptions
}
Launcher <|.. SubLauncher : can contain
Launcher o-- Config : uses
SubLauncher o-- Config : uses

This diagram illustrates the main interfaces and configuration struct within launcher.go. The Launcher interface can contain or compose multiple SubLauncher instances, each representing a distinct command or operational mode. Both launcher types depend on the Config struct, which provides references to essential services for agent execution.