main.go

Overview

The main.go file serves as the entry point for an interactive command-line application that integrates an AI agent with artifact management and session handling capabilities. Its primary purpose is to create and configure a Large Language Model (LLM)–based agent, manage user sessions, load artifacts (such as images and text files), and enable conversational interactions with the agent. The agent is specifically designed to answer questions about artifacts by loading and describing them on demand.

This file orchestrates the initialization and connection of multiple core components:

• Model instantiation using a Gemini LLM.

• LLM agent creation configured with a custom tool for loading artifacts.

• Session and artifact services for user context and data persistence.

• A runner that manages the execution of agent requests.

• An interactive loop that reads user input and streams agent responses.

Detailed Components

Package and Imports

• package main: Defines the executable program package.

• Imports include standard library packages (bufio, context, fmt, log, os) and various Google AI and ADK (Agent Development Kit) modules:

  • genai: For interacting with generative AI models.

  • agent, llmagent, artifact, session, tool, runner: Implements core agent framework, artifact storage, session management, and runtime coordination.

  • gemini: Provides Gemini LLM model implementation.

  • loadartifactstool: Tool enabling the agent to load artifact contents during conversations.

func main()

The main function runs the entire application workflow:

Context Creation

ctx := context.Background()

Creates a root context for all subsequent calls, enabling cancellation and deadlines if extended.

Model Initialization

model, err := gemini.NewModel(ctx, "gemini-2.5-flash", &genai.ClientConfig{
    APIKey: os.Getenv("GOOGLE_API_KEY"),
})

• Creates a Gemini LLM model named "gemini-2.5-flash".

• Uses the API key from environment variables.

• Returns an error if model creation fails.

LLM Agent Setup

llmagent, err := llmagent.New(llmagent.Config{
    Name:        "artifact_describer",
    Model:       model,
    Description: "Agent to answer questions about artifacts.",
    Instruction: "When user asks about the artifact, load them and describe them.",
    Tools: []tool.Tool{
        loadartifactstool.New(),
    },
})

• Constructs an LLM agent named "artifact_describer".

• Configured with:

  • The Gemini model.

  • A description and instruction guiding its behavior.

  • The loadartifactstool which enables artifact loading during conversations.

• Logs fatal error if creation fails.

Session and Artifact Service Initialization

userID, appName := "test_user", "test_app"
sessionService := session.InMemoryService()

• Uses in-memory session service (InMemoryService) for storing user-agent interaction state.

Session creation:

resp, err := sessionService.Create(ctx, &session.CreateRequest{
    AppName: appName,
    UserID:  userID,
})
session := resp.Session

• Creates a new session for the user and application.

• Logs any failure.

Artifact service:

artifactService := artifact.InMemoryService()

• Uses an in-memory artifact service for storing files related to the session.

Artifact Loading and Saving

imageBytes, err := os.ReadFile("animal_picture.png")

• Reads image bytes from a local file animal_picture.png.

• Creates a new artifact part with MIME type "image/png".

Saving the image artifact:

_, err = artifactService.Save(ctx, &artifact.SaveRequest{
    AppName:   appName,
    UserID:    userID,
    SessionID: session.ID(),
    FileName:  "animal_picture.png",
    Part:      genai.NewPartFromBytes(imageBytes, "image/png"),
})

• Saves the image artifact in the session context.

Saving a text artifact (haiku.txt):

_, err = artifactService.Save(ctx, &artifact.SaveRequest{
    AppName:   appName,
    UserID:    userID,
    SessionID: session.ID(),
    FileName:  "haiku.txt",
    Part: genai.NewPartFromText(
        "An old silent pond..." +
        "A frog jumps into the pond," +
        "splash! Silence again."),
})

• Stores a text artifact containing a haiku poem.

Any errors during artifact saving cause the program to exit with a fatal log.

Runner Initialization

r, err := runner.New(runner.Config{
    AppName:         appName,
    Agent:           llmagent,
    SessionService:  sessionService,
    ArtifactService: artifactService,
})

• Creates a runner instance that manages agent execution using the given agent, session service, and artifact service.

• Responsible for processing user inputs and generating agent responses.

Interactive User Input Loop

reader := bufio.NewReader(os.Stdin)
for {
    fmt.Print("\nUser -> ")

    userInput, err := reader.ReadString('\n')
    ...
    userMsg := genai.NewContentFromText(userInput, genai.RoleUser)

• Reads user input line-by-line from the console.

• Converts input to a genai.Content object with role User.

Agent Run and Response Streaming

streamingMode := agent.StreamingModeSSE
for event, err := range r.Run(ctx, userID, session.ID(), userMsg, agent.RunConfig{
    StreamingMode: streamingMode,
}) {
    if err != nil {
        fmt.Printf("\nAGENT_ERROR: %v\n", err)
    } else {
        if event.LLMResponse.Content == nil {
            continue
        }
        for _, p := range event.LLMResponse.Content.Parts {
            if streamingMode != agent.StreamingModeSSE || event.LLMResponse.Partial {
                fmt.Print(p.Text)
            }
        }
    }
}

• Runs the agent with the user input.

• Streams partial or full responses to stdout.

• Handles and prints any agent errors.

• The streaming mode used is Server-Sent Events (SSE) for partial incremental output.

Important Implementation Details

• Model and Agent Integration: Uses the Gemini LLM model and an LLM agent configured with a specialized artifact-loading tool (loadartifactstool). This allows dynamic retrieval of artifact contents during conversations.

• Session and Artifact Services: Both implemented as in-memory services (session.InMemoryService() and artifact.InMemoryService()), facilitating transient but fast storage during execution. These abstractions are key to managing user context and data.

• Runner: Central component coordinating execution of the agent within the session and artifact context, handling message passing and streaming results.

• Streaming Responses: The program supports streaming partial results from the agent, enhancing responsiveness in the interactive console.

• Error Handling: Fatal errors during initialization and I/O operations cause immediate termination with diagnostic logs.

Interactions with Other System Components

• Gemini Model (gemini.NewModel): Provides the underlying LLM capabilities required by the agent. The model is configured with API credentials and named model variants.

• LLM Agent (llmagent.New): Wraps the model and tools, managing instructions and tool integration to provide conversational AI functionality.

• Artifact Management (artifact package): Handles storage and retrieval of artifacts such as images and text files, enabling the agent to access relevant data on demand.

• Session Management (session package): Manages user sessions, tracking the state and history of interactions.

• Runner (runner package): Orchestrates the agent execution lifecycle, message handling, and streaming of responses.

• Tool Integration (loadartifactstool): Extends agent capabilities by allowing direct loading of artifact content into agent conversations.

• The system expects the program to be run from a loadartifacts directory due to relative file path dependencies for artifacts.

Usage Example

To use the program, the environment variable GOOGLE_API_KEY must be set with a valid API key. The user runs the program and types queries about the artifacts (e.g., "Describe the animal picture" or "What is the haiku about?"). The agent processes these inputs, loads the relevant artifacts, and streams descriptive responses back to the console.

Mermaid Diagram: Flowchart of Main Functional Workflow

flowchart TD
A["Start: main()"] --> B[Create Context]
B --> C[Initialize Gemini Model]
C --> D[Create LLM Agent with loadartifactstool]
D --> E[Initialize Session Service]
E --> F[Create User Session]
F --> G[Initialize Artifact Service]
G --> H[Read & Save Image Artifact]
H --> I[Save Text Artifact]
I --> J[Create Runner with Agent and Services]
J --> K[Start User Input Loop]
K --> L[Read User Input]
L --> M[Convert Input to genai.Content]
M --> N[Run Agent via Runner]
N --> O[Stream Agent Response]
O --> K

Reference to Related Topics

• LLM Integration and Agents — for details on configuring and using LLM agents with tools and instructions.

• Artifact Management — for implementation of artifact storage and retrieval services.

• Session Management — for handling session lifecycle and state persistence.

• Agent Execution Runner — coordinating agent runs within sessions and streaming outputs.

• Artifact Loading Tool — tool enabling loading and appending artifact data in agents.