console.go

Overview

The console.go file provides a console-based launcher to interact with an AI agent in a command-line interface (CLI) environment. It enables users to input text queries directly via the console and receive responses streamed from the agent. This file implements a sub-launcher adhering to the common launcher interface used across the system, allowing for integration with the broader agent framework and session management services.

The main purpose is to facilitate simple, interactive user-agent conversations without requiring a graphical interface or web server, making it suitable for quick testing, debugging, or lightweight deployments.

Types and Their Responsibilities

1. consoleConfig

Holds configuration options parsed from command-line flags specific to the console launcher.

• Fields:

  • streamingMode agent.StreamingMode
    Enum indicating how agent responses are streamed back to the user (e.g., Server-Sent Events or none).

  • streamingModeString string
    Raw string from CLI arguments to be converted to the StreamingMode enum.

2. consoleLauncher

Implements the launcher.SubLauncher interface and encapsulates the interactive console logic.

• Fields:

  • flags *flag.FlagSet
    Flag set used to parse command-line arguments for the console launcher.

  • config *consoleConfig
    Stores parsed configuration values.

Functions and Methods

NewLauncher() launcher.SubLauncher

• Purpose:
  Factory function to create a new instance of consoleLauncher with initialized flags for parsing.

• Details:
  Defines the streaming_mode flag with default value agent.StreamingModeSSE and valid options none or sse.

• Returns:
  A launcher.SubLauncher instance configured for console interaction.

• Usage Example:

  launcher := console.NewLauncher()
  

(l *consoleLauncher) Parse(args []string) ([]string, error)

• Purpose:
  Parses the command-line arguments specific to the console launcher.

• Parameters:

  • args []string - Arguments to parse.

• Returns:

  • Remaining unparsed arguments after console-specific flags are processed.

  • Error if parsing fails or invalid flag values are provided.

• Implementation Details:
  Converts the streaming_mode string to its corresponding enum and validates it. Accepts only none or sse.

(l *consoleLauncher) Run(ctx context.Context, config *launcher.Config) error

• Purpose:
  Starts the main interaction loop that reads user input from the console, sends it to the agent, and streams back the agent's response.

• Parameters:

  • ctx context.Context - Context for cancellation and deadlines.

  • config *launcher.Config - Configuration including agent loader, session service, artifact service.

• Returns:

  • Error if session creation or runner setup fails; otherwise runs indefinitely until terminated.

• Detailed Workflow:

  1. Creates or retrieves a user session using the provided session service.

  2. Instantiates a runner.Runner to execute the agent with the session.

  3. Reads user input line-by-line from standard input.

  4. Sends user input as a message (genai.Content) to the agent runner.

  5. Streams back the agent's response incrementally or in full, depending on the streaming mode.

  6. Handles errors during agent execution gracefully by printing error messages.

• Streaming Modes:

  • SSE (Server-Sent Events): Prints partial response chunks as they arrive.

  • None: Prints the entire response at once.

• Usage Example:

  err := launcher.Run(ctx, config)
  if err != nil {
      log.Fatal(err)
  }
  

(l *consoleLauncher) Keyword() string

• Purpose:
  Returns the CLI keyword console used to identify this sub-launcher.

(l *consoleLauncher) CommandLineSyntax() string

• Purpose:
  Returns the formatted command-line flag usage string for this launcher, leveraging utility functions.

(l *consoleLauncher) SimpleDescription() string

• Purpose:
  Provides a concise description: "runs an agent in console mode."

(l *consoleLauncher) Execute(ctx context.Context, config *launcher.Config, args []string) error

• Purpose:
  Convenience method that parses CLI arguments, validates no extra unknown arguments remain, and runs the console launcher.

• Parameters:

  • ctx context.Context

  • config *launcher.Config

  • args []string - CLI arguments

• Returns:

  • Error if argument parsing or execution fails.

• Implementation Detail:
  Calls Parse(), checks for unparsed arguments via universal.ErrorOnUnparsedArgs(), then calls Run().

Important Implementation Details and Algorithms

• Session Management:
  Uses a session service (sessionService) to create and maintain a session per user interaction. Defaults to an in-memory session if none provided.

• Agent Execution:
  The runner package coordinates sending user input to the root agent and managing the streaming of responses. This isolates the console launcher from agent internals.

• Streaming Logic:
  The console launcher supports two streaming modes, SSE and none, to control how partial responses are printed. It maintains a buffer prevText to avoid duplicate output when streaming.

• Command-Line Parsing:
  Uses Go's flag.FlagSet to define and parse CLI flags specific to the console launcher, separating concerns from other launchers.

• Error Handling:
  Provides user-friendly error messages on session creation or agent running failure, and logs fatal errors on I/O issues.

Interaction with Other System Components

• Agent Loading:
  Obtains the root agent from the provided launcher.Config's AgentLoader.

• Session Service:
  Interfaces with session.Service to create and manage user sessions, enabling stateful conversations.

• Runner:
  Uses runner.Runner to handle the actual agent execution and message streaming, which internally manages agent invocation context and event processing as described in Agent Invocation Context and Agent Execution Runner.

• Command-Line Utilities:
  Utilizes util.FormatFlagUsage for CLI help text formatting and universal.ErrorOnUnparsedArgs for argument validation.

Console Launcher Structure Diagram

classDiagram
class consoleLauncher {
-flags: FlagSet
-config: consoleConfig
+Parse(args)
+Run(ctx, config)
+Keyword()
+CommandLineSyntax()
+SimpleDescription()
+Execute(ctx, config, args)
}
class consoleConfig {
-streamingMode: StreamingMode
-streamingModeString: string
}
consoleLauncher --> consoleConfig

Usage Scenario Example

In a command-line environment, a user can invoke this launcher with:

myapp console --streaming_mode=sse

The launcher reads input lines from the console, sends them to the AI agent, and outputs the streaming responses directly below the prompt, allowing real-time conversational interaction.

This file is a critical part of the overall system enabling direct console-based interaction with agents, leveraging session management and agent execution infrastructure described in Session Management and Agent Execution Runner.