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:

Package	Role
`adk/agent`	Agent core definitions, Loader for loading Agents
`adk/agent/llmagent`	LLM-based Agent, large language model-based Agent implementation
`adk/cmd/launcher`	Agent launcher, supports CLI and Web modes
`adk/cmd/launcher/full`	Full-featured launcher (includes CLI + Web)
`adk/model/gemini`	Gemini model client
`adk/tool/geminitool`	Google toolset (Search, etc.)
`genai`	Google 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:

Model	Characteristics	Use Case
`gemini-flash-latest`	Fastest, quick response	Daily conversation, production
`gemini-pro`	More capable, higher latency	Complex reasoning tasks
`gemini-2.0-flash-exp`	Experimental, more capable	Testing 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:

Field	Description	Example
Name	Agent’s identifier	`hello_time_agent`
Model	Which model to use	`model` (created above)
Description	Agent description, for Model reference	“Tells the current time…”
Instruction	System prompt	“You are a helpful…”
Tools	List of tools Agent can call	`GoogleSearch{}`

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 实战干货.

Frequently Asked Questions

What packages are needed to build a minimal ADK Go Agent?

You need packages from google.golang.org/adk, including agent, llmagent, launcher, model/gemini, and tool.

What does the Hello World Agent do?

It creates a simple Agent that can tell the current time in a specified city using a Google Search tool.

How do I run the Hello World Agent?

Set the GOOGLE_API_KEY environment variable and run `go run main.go` (or the file name you used).

What is the purpose of `llmagent.New`?

It creates a new LLM-based Agent by combining a Model, Tools, and an Instruction into a runnable Agent.

What common errors occur when first running an ADK Go Agent?

Typical errors include missing API keys, incorrect model names, and network issues. The article covers how to read error messages and fix them.

Complete Hello World Agent Code#

Code Line-by-Line Breakdown#

Part 1: import#

Part 2: Create Model#

Part 3: Create Agent#

Part 4: Launch Agent#

Running the Agent#

CLI Mode#

Web Mode#

Common Error Analysis#

Error 1: Failed to create model: UNAUTHORIZED#

Error 2: Failed to create model: PERMISSION_DENIED#

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

Extension Exercises#

Add More Tools#

Remove Tools and Observe Agent Behavior Change#

Next Steps#