Hello World Agent: A Complete Minimal Runnable Agent Example

Last article covered the three elements, this article actually writes a runnable program. Decompose the official Quickstart example, explain each part line by line, then run it.

Complete Hello World Agent Code

package main

import (
    "context"
    "log"
    "os"

    "google.golang.org/adk/agent"
    "google.golang.org/adk/agent/llmagent"
    "google.golang.org/adk/cmd/launcher"
    "google.golang.org/adk/cmd/launcher/full"
    "google.golang.org/adk/model/gemini"
    "google.golang.org/adk/tool"
    "google.golang.org/adk/tool/geminitool"
    "google.golang.org/genai"
)

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

    model, err := gemini.NewModel(ctx, "gemini-flash-latest", &genai.ClientConfig{
        APIKey: os.Getenv("GOOGLE_API_KEY"),
    })
    if err != nil {
        log.Fatalf("Failed to create model: %v", err)
    }

    timeAgent, err := llmagent.New(llmagent.Config{
        Name:        "hello_time_agent",
        Model:       model,
        Description: "Tells the current time in a specified city.",
        Instruction: "You are a helpful assistant that tells the current time in a city.",
        Tools: []tool.Tool{
            geminitool.GoogleSearch{},
        },
    })
    if err != nil {
        log.Fatalf("Failed to create agent: %v", err)
    }

    config := &launcher.Config{
        AgentLoader: agent.NewSingleLoader(timeAgent),
    }

    l := full.NewLauncher()
    if err = l.Execute(ctx, config, os.Args[1:]); err != nil {
        log.Fatalf("Run failed: %v\n\n%s", err, l.CommandLineSyntax())
    }
}

Code Line-by-Line Breakdown

Part 1: import

import (
    "context"
    "log"
    "os"
    // ADK Go core packages
    "google.golang.org/adk/agent"
    "google.golang.org/adk/agent/llmagent"
    "google.golang.org/adk/cmd/launcher"
    "google.golang.org/adk/cmd/launcher/full"
    "google.golang.org/adk/model/gemini"
    "google.golang.org/adk/tool"
    "google.golang.org/adk/tool/geminitool"
    "google.golang.org/genai"
)

Package roles:

PackageRole
adk/agentAgent core definitions, Loader for loading Agents
adk/agent/llmagentLLM-based Agent, large language model-based Agent implementation
adk/cmd/launcherAgent launcher, supports CLI and Web modes
adk/cmd/launcher/fullFull-featured launcher (includes CLI + Web)
adk/model/geminiGemini model client
adk/tool/geminitoolGoogle toolset (Search, etc.)
genaiGoogle AI common package, ClientConfig is here

Part 2: Create Model

model, err := gemini.NewModel(ctx, "gemini-flash-latest", &genai.ClientConfig{
    APIKey: os.Getenv("GOOGLE_API_KEY"),
})
if err != nil {
    log.Fatalf("Failed to create model: %v", err)
}

gemini.NewModel creates a Gemini model client. First parameter is context, second is model name (gemini-flash-latest), third is config (includes API Key).

Optional model names:

ModelCharacteristicsUse Case
gemini-flash-latestFastest, quick responseDaily conversation, production
gemini-proMore capable, higher latencyComplex reasoning tasks
gemini-2.0-flash-expExperimental, more capableTesting new features

Part 3: Create Agent

timeAgent, err := llmagent.New(llmagent.Config{
    Name:        "hello_time_agent",
    Model:       model,
    Description: "Tells the current time in a specified city.",
    Instruction: "You are a helpful assistant that tells the current time in a city.",
    Tools: []tool.Tool{
        geminitool.GoogleSearch{},
    },
})

Config field meanings:

FieldDescriptionExample
NameAgent’s identifierhello_time_agent
ModelWhich model to usemodel (created above)
DescriptionAgent description, for Model reference“Tells the current time…”
InstructionSystem prompt“You are a helpful…”
ToolsList of tools Agent can callGoogleSearch{}

Part 4: Launch Agent

config := &launcher.Config{
    AgentLoader: agent.NewSingleLoader(timeAgent),
}

l := full.NewLauncher()
if err = l.Execute(ctx, config, os.Args[1:]); err != nil {
    log.Fatalf("Run failed: %v\n\n%s", err, l.CommandLineSyntax())
}

launcher.Config defines how to load Agent. agent.NewSingleLoader wraps a single Agent. full.NewLauncher() creates a full-featured launcher (includes CLI and Web modes).

Execute’s second parameter os.Args[1:] is command-line arguments, deciding which mode to run.

Running the Agent

CLI Mode

source .env
go run agent.go

Output:

[INFO] Agent "hello_time_agent" started
> What time is it in Shanghai?

Web Mode

go run agent.go web api webui

After startup, visit http://localhost:8080 and chat with Agent via browser.

Common Error Analysis

Error 1: Failed to create model: UNAUTHORIZED

Cause: API Key invalid or not loaded.

Solution:

echo $GOOGLE_API_KEY  # Confirm env var has value
source .env && go run agent.go  # Reload environment variables

Error 2: Failed to create model: PERMISSION_DENIED

Cause: API Key doesn’t have corresponding API permission enabled. Need to confirm in Google AI Studio that Key has Gemini API permission.

Error 3: google.golang.org/adk/agent/llmagent: module not found

Cause: Didn’t run go mod tidy.

Solution:

go mod tidy
go run agent.go

Extension Exercises

Add More Tools

Add more tools in the Tools array:

Tools: []tool.Tool{
    geminitool.GoogleSearch{},
    myCustomTool{},  // Own tool
},

Remove Tools and Observe Agent Behavior Change

Change Tools to empty array, rerun. Agent changes from “can query weather” to “can only chat”—observe how Model handles queries needing real-time info without tools.

Next Steps

Agent running, complete sensory understanding of the process. Next, learn about Agent’s two execution modes—CLI and Web—各自适合什么场景。

← Agent Core Concepts | CLI vs Web →

Follow “Mengshou Programming” on WeChat for more Go ADK hands-on tutorials, weekly updates on Go / AI programming 实战干货.