This updated edition incorporates several key architectural improvements, production hardening, and dependency upgrades over the initial release:
v0.2.0
to v1.5.1
google.golang.org/adk
), delivering enhanced model context handling and agent execution pipelines.v1.65.0
google.golang.org/genai
) with native Vertex AI authentication auto-detection.1.26.3
go 1.25.0
module directives across all sub-modules.github.com/a2aproject/a2a-go
(v0.3.15
) with sub-modules (a2a-client-go
, a2a-server-go
, a2a-master-go
, a2a-gemini3-go
) for multi-agent delegation.slog
) Standardizationslog
with JSONHandler
across all entrypoints for native Google Cloud Logging compatibility.signal.NotifyContext(context.Background(), os.Interrupt)
across all sub-module entrypoints to handle container termination cleanly.rollDieTool
(sides <= 0
) to prevent runtime panics from malformed LLM tool calls.CMD
Generationcloudrun.go
to construct container arguments with json.Marshal
, ensuring valid CMD
syntax regardless of feature flags.Makefile
to format (go fmt
), lint (go vet
), test (go test
), build, and clean across all 5 submodules (hello-agent
, a2a-client-go
, a2a-gemini3-go
, a2a-master-go
, a2a-server-go
).go test -v ./...
), formatting (go fmt
), linting (go vet ./...
), and make build
pass with 0 errors.This tutorial provides a comprehensive guide to building, running, and deploying native AI Agents using the Go programming language and the official Go Agent Development Kit (ADK) (google.golang.org/adk
).
Go (Golang) is an open-source programming language created at Google. Renowned for its simplicity, concurrency support via goroutines, and fast execution speed, Go is an exceptional choice for building high-throughput microservices and distributed agent systems.
This project has been updated to run on Go 1.26 (specifically ** go1.26.3 linux/amd64**) with
go 1.25.0
module directives across all sub-modules.If you are using gvm to manage Go installations:
sudo apt-get update
sudo apt-get install -y bison curl git mercurial make binutils gcc build-essential
bash < <(curl -s -S -L https://raw.githubusercontent.com/moovweb/gvm/master/binscripts/gvm-installer)
gvm install go1.26.3 -B
gvm use --default go1.26.3
Verify that your active Go binary is Go 1.26.3:
$ go version
go version go1.26.3 linux/amd64
go 1.25.0
)
All go.mod
files in this workspace have been upgraded from go 1.24.4
to go 1.25.0
to support modern language features and telemetry packages required by Go ADK v1.5.1
.
The Go Agent Development Kit (ADK) (google.golang.org/adk
) is a code-first toolkit developed by Google for building, evaluating, and deploying sophisticated AI agents.
github.com/a2aproject/a2a-go
(v0.3.15+) for multi-agent collaboration.Official Repositories & Docs:
go.mod
) The updated agent stack relies on the latest releases:
module hello-agent
go 1.25.0
require (
google.golang.org/adk v1.5.1
google.golang.org/genai v1.65.0
github.com/a2aproject/a2a-go v0.3.15
)
Clone the repository and set up environment credentials:
git clone https://github.com/xbill9/adk-hello-world-go
cd adk-hello-world-go
Run init.sh
to initialize settings:
$ source init.sh
--- Authentication Method ---
Do you want to use a Gemini API Key for authentication? (y/n): n
--- Setup complete ---
Then load project-wide environment variables using set_env.sh
:
$ source set_env.sh
--- Setting Google Cloud Environment Variables ---
Checking gcloud authentication status...
gcloud is authenticated.
Exported PROJECT_ID=comglitn
Exported PROJECT_NUMBER=1056842563084
Exported GOOGLE_CLOUD_PROJECT=comglitn
Exported GOOGLE_GENAI_USE_VERTEXAI=TRUE
Exported GOOGLE_CLOUD_LOCATION=us-central1
--- Environment setup complete ---
If Google Cloud authentication expires, refresh credentials:
gcloud auth login
gcloud auth application-default login
The project includes unified Makefile targets for linting, formatting, compiling, and testing all 5 agent submodules (hello-agent
, a2a-client-go
, a2a-gemini3-go
, a2a-master-go
, a2a-server-go
):
make format
make lint
make test
make build
make clean
slog
All entrypoints use slog
configured with JSONHandler
to emit logs compatible with Google Cloud Logging:
logger := slog.New(slog.NewJSONHandler(os.Stdout, nil))
slog.SetDefault(logger)
Service entrypoints use signal.NotifyContext
to handle SIGINT
and SIGTERM
signals gracefully during Cloud Run container lifecycle events:
ctx, cancel := signal.NotifyContext(context.Background(), os.Interrupt)
defer cancel()
Custom agent tools validate input bounds to prevent runtime panics when executing tool calls generated by LLMs:
func rollDieTool(tc tool.Context, args rollDieToolArgs) (int, error) {
if args.Sides <= 0 {
return 0, fmt.Errorf("number of sides must be greater than 0, got %d", args.Sides)
}
return rand.Intn(args.Sides) + 1, nil
}
Run the agent interactively in your terminal using cli.sh
:
$ source cli.sh
go run agent.go
User -> what can you do?
Agent -> I can help you with a variety of tasks! I can answer questions, search information on Google, and tell you current time or weather in any city.
User -> what is the weather in NYC?
Agent -> The current weather in New York City is sunny with a temperature of 65°F (18°C)...
Launch the embedded Web UI with web.sh
:
$ source web.sh
Navigate to http://localhost:8081
in your browser to interact with the visual chat interface.
The 2026 update introduces full Agent-to-Agent communication modules:
hello-agent
: Core single-agent implementation.a2a-server-go
: Exposes agent capabilities over A2A HTTP endpoints.a2a-client-go
: Client library for dispatching requests to remote A2A agents.a2a-master-go
& a2a-gemini3-go
: Orchestrators for complex multi-agent workflows using Gemini models.quickrun.sh
) Deploy to Google Cloud Run using the automated build script:
$ source quickrun.sh
Building using Dockerfile and deploying container to Cloud Run service [adk-hello-world-go]...
✓ Building Container...
✓ Creating Revision...
✓ Routing traffic...
Service URL: https://adk-hello-world-go-1056842563084.us-central1.run.app
adkgo
CLI Deployment
Build the adkgo
CLI tool from the adk-go
upstream repository:
cd ~
git clone https://github.com/google/adk-go
cd adk-go
go build ./cmd/adkgo
./adkgo deploy cloudrun \
-p $GOOGLE_CLOUD_PROJECT \
-r $GOOGLE_CLOUD_LOCATION \
-s adk-hello-world-go \
-e ./hello-agent/agent.go
proxy.sh
) Connect to your deployed Cloud Run service locally:
$ source proxy.sh
PROXY URL http://127.0.0.1:8081/ui/?app=hello_time_agent
Proxying to Cloud Run service [adk-hello-world-go] in region [us-central1]
In this updated version:
v1.5.1
v1.65.0