ADK Go Installation & Quick Verification: Run Your First Agent

Go environment ready, now install ADK Go. After installation, run the first Agent from the official Quickstart—a simple assistant that can answer “what time is it now”.

Installing ADK Go

Install ADK Go via go install:

go install google.golang.org/adk/cmd/adk@latest

This installs the ADK Go command-line tool adk to $GOBIN directory (usually $HOME/go/bin).

Verify installation:

adk version
# Expected output: adk version v0.2.0 or similar version

If command not found, confirm $GOBIN in PATH:

export PATH=$PATH:$HOME/go/bin
adk version

Method 2: Build from Source

Want to see source code or use the latest dev branch:

git clone https://github.com/google/adk-go.git
cd adk-go
go build -o adk ./cmd/adk
./adk version

Get Gemini API Key

ADK Go uses Google Gemini series models as the LLM backend, requiring an API Key.

How to get one:

  1. Visit Google AI Studio
  2. Click “Create API Key”
  3. Copy the generated key

Set environment variable:

export GOOGLE_API_KEY="your-api-key-here"

This key needs to be loaded before each Agent run. Can write to .env file in project root (covered later).

Quick Verification: Run Hello World Agent

An ADK Go project minimally needs only two files:

my_agent/
├── agent.go      # Agent code
└── .env          # API Key

Create Project

mkdir -p my_agent && cd my_agent
touch agent.go .env

Write Agent Code

Write following code to agent.go:

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())
	}
}

Write API Key

echo 'export GOOGLE_API_KEY="your-api-key"' > .env

Run Agent

source .env  # Load environment variables
go run agent.go

If normal, you’ll see ADK Go’s interactive interface prompting for input. Try asking:

What time is it in Shanghai?

Agent will query via Google Search tool and answer.

Two Agent Execution Modes

ADK Go supports two execution modes:

CLI Mode

go run agent.go

Pure command-line interaction, suitable for debugging and automation scripts.

Web Mode

go run agent.go web api webui

Starts a Web server (default localhost:8080), open browser to see chat interface.

Standard Directory Structure

A formal ADK Go project:

project_name/
├── agent.go              # Main entry
├── .env                  # Environment variables (not committed to git)
├── .gitignore
├── go.mod
├── go.sum
└── README.md

.gitignore content:

.env
.env.local
go.sum

Common Issues

Q: go install reports certificate signed by unknown authority A: May be corporate network proxy restrictions. Use go env -w GOPROXY=https://goproxy.cn,direct to switch proxy, or disable proxy.

Q: Running Agent reports 401 Unauthorized A: API Key invalid or not loaded. Confirm GOOGLE_API_KEY environment variable correctly set: echo $GOOGLE_API_KEY should have a value.

Q: Running Agent reports failed to create model A: Usually network issue, cannot access Gemini API. Proxy needed in Mainland China.

Next Steps

First Agent running. Next, understand Agent’s three elements: Model, Tool, Instruction—core concepts of ADK Go.

← Go Installation & Verification | Project Structure & .env Management →

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