ADK Go 安装与快速验证：跑通你的第一个 Agent

在正式构建生产级 Agent 之前，我们必须先完成开发环境的搭建与验证。ADK Go 的安装过程看似简单，但在实际工程实践中，网络环境、依赖版本、模块管理等因素往往成为新手的第一道门槛。本章将从零开始，带你完成 SDK 安装、API Key 配置，并跑通第一个可交互的 Agent 程序。更重要的是，我会分享在生产环境中积累的经验——那些官方文档不会告诉你的陷阱与最佳实践。

安装 ADK Go

方式一：go install（推荐）

ADK Go 作为 Google 官方维护的 Go 模块，遵循标准的 Go 工具链分发方式。通过 go install 安装是最简洁、最符合 Go 生态习惯的做法：

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

这条命令会将 adk 二进制文件编译并安装到 $GOBIN 目录（默认 $HOME/go/bin）。生产环境建议：在 CI/CD 流水线中，不要直接使用 @latest，而是锁定到具体版本号，例如 @v0.2.0。这样可以避免因为上游发布破坏性更新而导致构建失败。我们曾在一次凌晨的自动部署中吃过亏——@latest 拉取了新版本，API 签名变动导致整个服务无法启动。

验证安装：

adk version
# 预期输出：adk version v0.2.0（或更高版本）

如果遇到 command not found，说明 $GOBIN 未加入 PATH。在 macOS/Linux 环境下，将以下配置写入你的 shell 配置文件（.zshrc 或 .bashrc）：

export PATH=$PATH:$(go env GOPATH)/bin

注意：$(go env GOPATH) 比硬编码 $HOME/go 更健壮，因为有些开发者会自定义 GOPATH。

方式二：从源码编译

如果你需要阅读源码、调试框架内部逻辑，或者想使用尚未发布的开发分支，可以选择从源码编译：

git clone https://github.com/google/adk-go.git
cd adk-go
git checkout v0.2.0  # 切换到稳定标签，避免 main 分支的不稳定性
go build -o adk ./cmd/adk
./adk version

从源码编译的一个隐藏好处是：你可以通过 go mod graph 查看完整的依赖图谱，评估引入 ADK Go 后对你的项目依赖树的影响。在微服务架构中，依赖冲突是常见问题，提前了解 transitive dependencies 能避免很多麻烦。

获取 Gemini API Key

ADK Go 底层调用 Google Gemini 模型，因此必须配置有效的 API Key。这一环节在实际项目中有几个需要特别注意的点。

获取方式

访问 Google AI Studio
使用 Google 账号登录（建议使用团队共享的企业账号，便于配额管理）
点击 “Create API Key”
选择或创建一个 Google Cloud 项目（关键：配额和计费都是按项目维度管理的）
复制生成的 Key，妥善保存——Google 只会显示一次

环境变量配置

最基础的配置方式是通过环境变量注入：

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

生产环境警示：绝不要在代码中硬编码 API Key，也不要将其提交到版本控制系统。2023 年某知名 AI 创业公司就曾因为开发者在 GitHub 上泄露了 OpenAI API Key，导致被恶意调用产生数万美元账单。建议使用 .env 文件管理本地开发环境，生产环境则通过 Secret Manager 或 Kubernetes Secrets 注入。

快速验证：跑通 Hello World Agent

ADK Go 项目的最小可运行单元只需要两个文件。但别被"简单"骗了——理解每个文件背后的设计意图，是后续构建复杂 Agent 系统的基础。

项目初始化

mkdir -p my_agent && cd my_agent
go mod init my-agent/main  # 初始化 Go 模块
touch agent.go .env

Agent 代码详解

将以下代码写入 agent.go。这不是简单的复制粘贴——每一行都有工程上的考量：

package main

import (
	"context"
	"fmt"
	"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()

	// 1. 读取并校验 API Key
	apiKey := os.Getenv("GOOGLE_API_KEY")
	if apiKey == "" {
		log.Fatal("GOOGLE_API_KEY environment variable is not set. " +
			"Please set it via: export GOOGLE_API_KEY=your-key")
	}

	// 2. 初始化 Gemini 模型客户端
	// 生产建议：将模型名称和配置参数化，便于不同环境使用不同模型
	modelName := getEnvWithDefault("GEMINI_MODEL", "gemini-2.0-flash")
	model, err := gemini.NewModel(ctx, modelName, &genai.ClientConfig{
		APIKey: apiKey,
		// 生产环境建议配置超时和重试策略
		HTTPOptions: &genai.HTTPOptions{
			Timeout: 30000, // 30秒超时
		},
	})
	if err != nil {
		log.Fatalf("Failed to create Gemini model client: %v", err)
	}

	// 3. 构建 LLM Agent
	// Name: 全局唯一标识，用于日志追踪和监控
	// Instruction: 系统提示词，决定 Agent 的行为边界和能力范围
	// Tools: Agent 可调用的外部工具集
	timeAgent, err := llmagent.New(llmagent.Config{
		Name:        "hello_time_agent",
		Model:       model,
		Description: "Tells the current time in a specified city using Google Search.",
		Instruction: "You are a helpful time assistant. When asked about the current time in a city, " +
			"use the Google Search tool to find accurate time information. " +
			"Always respond in the same language as the user's query.",
		Tools: []tool.Tool{
			geminitool.GoogleSearch{},
		},
	})
	if err != nil {
		log.Fatalf("Failed to create agent: %v", err)
	}

	// 4. 配置 Launcher
	// AgentLoader 负责在运行时加载 Agent 实例
	config := &launcher.Config{
		AgentLoader: agent.NewSingleLoader(timeAgent),
	}

	// 5. 执行
	// full.NewLauncher() 提供 CLI + Web 双模式支持
	l := full.NewLauncher()
	if err = l.Execute(ctx, config, os.Args[1:]); err != nil {
		log.Fatalf("Run failed: %v\n\nUsage: %s", err, l.CommandLineSyntax())
	}
}

// getEnvWithDefault 读取环境变量，若未设置则返回默认值
// 生产环境中，建议将这类工具函数提取到 internal/config 包中复用
func getEnvWithDefault(key, defaultValue string) string {
	if value := os.Getenv(key); value != "" {
		return value
	}
	return defaultValue
}

代码设计要点解析：

防御式编程：在创建模型前显式检查 GOOGLE_API_KEY 是否存在。这比让底层库返回晦涩的错误信息要友好得多。
可配置化：通过环境变量 GEMINI_MODEL 控制模型版本，无需重新编译即可切换模型。这在 A/B 测试和灰度发布中非常有用。
超时控制：为 HTTP 客户端配置 30 秒超时。在生产环境中，没有超时设置的请求是灾难性的——它可能导致 goroutine 泄漏和内存溢出。
错误处理：每个可能失败的步骤都进行了显式错误检查，并附带上下文信息（“Failed to create Gemini model client” 比 “connection refused” 更容易定位问题）。

环境变量文件

echo 'export GOOGLE_API_KEY="your-actual-api-key"' > .env
echo 'export GEMINI_MODEL="gemini-2.0-flash"' >> .env

运行 Agent

source .env
go mod tidy  # 自动解析并下载依赖
go run agent.go

首次运行 go mod tidy 时，由于需要下载 google.golang.org/adk 及其依赖（包括 google.golang.org/genai），可能会耗时较久。在中国大陆网络环境下，建议提前配置 Go 代理：

go env -w GOPROXY=https://goproxy.cn,direct

成功启动后，你会看到 ADK Go 的交互式 CLI 界面。尝试输入：

What time is it in Shanghai?

Agent 会调用 Google Search 工具查询上海当前时间，然后组织语言回答你。观察它的思考过程：这是理解 Agent 工作流的最佳方式——它如何解析意图、选择工具、调用工具、整合结果。

Agent 运行的两种方式

ADK Go 的启动器设计遵循了"一次编写，多处运行"的理念。同一个 Agent 代码，通过不同的命令行参数，可以在不同模式下运行。

CLI 模式（默认）

go run agent.go

CLI 模式是开发调试的首选。它的优势在于：启动速度快（无 Web 服务器初始化开销）、日志直接输出到终端、易于集成到 shell 脚本和自动化流程。我在日常开发中 80% 的时间都在使用 CLI 模式进行快速验证。

Web 模式

go run agent.go web api webui

Web 模式会同时启动 API 服务（默认 localhost:8080）和 Web UI（localhost:8080/webui）。这个模式适合给非技术同事演示、进行多轮对话测试，或者需要可视化观察 Agent 思考链的场景。

重要提醒：ADK Web UI 仅用于开发调试，官方明确不建议用于生产环境。生产部署应使用 ADK Runtime 或自行构建 API 服务（后续模块会详细讲解）。

目录结构规范

虽然最小项目只需要两个文件，但一个可维护的工程应该遵循以下结构：

my_agent/
├── agent.go              # 主入口文件
├── .env                  # 环境变量（绝对不要提交到 git）
├── .env.example          # 环境变量模板（提交到 git，供团队成员参考）
├── .gitignore            # 必须包含 .env 和 go.sum
├── go.mod                # Go 模块定义
├── go.sum                # 依赖校验和（建议提交，确保构建可复现）
└── README.md             # 项目说明，包含运行步骤

.gitignore 最小配置：

# 敏感信息
.env
.env.local
.env.*.local

# IDE
.idea/
.vscode/
*.swp

# OS
.DS_Store

关于 go.sum 的争议：有些团队选择将 go.sum 加入 .gitignore，认为它可以重新生成。但从工程严谨性角度，我建议提交 go.sum。它是 Go 模块的校验和数据库，确保所有开发者和 CI 环境使用完全一致的依赖版本。删除它可能导致"在我机器上能跑"的问题。

常见问题与排障指南

Q：`go install` 报 `certificate signed by unknown authority`

根因：企业网络或某些地区的网络环境对 HTTPS 证书进行了中间人检查。

解决方案：

# 方案 A：切换至可信的 Go 代理
go env -w GOPROXY=https://goproxy.cn,direct

# 方案 B：如果是企业自签证书，将企业 CA 加入系统信任库
# macOS 示例：
sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain /path/to/company-ca.crt

Q：运行 Agent 报 `401 Unauthorized`

排障流程：

# 1. 确认环境变量已加载
echo $GOOGLE_API_KEY

# 2. 确认 Key 格式正确（不应包含多余空格或换行）
# 3. 确认 Key 有 Gemini API 的访问权限（在 Google AI Studio 中检查）
# 4. 确认 Key 未过期或被撤销

Q：运行 Agent 报 `failed to create model` 或连接超时

根因：无法建立到 Google API 的网络连接。

解决方案：在中国大陆或其他受限网络环境下，需要为终端配置代理：

export HTTPS_PROXY=http://127.0.0.1:7890  # 根据你的代理软件调整端口
go run agent.go

进阶技巧：在代码中检测网络连通性，给出更友好的错误提示：

if err != nil {
	if os.Getenv("HTTPS_PROXY") == "" && os.Getenv("https_proxy") == "" {
		log.Printf("Warning: No proxy configured. If you are in a restricted network region, " +
			"consider setting HTTPS_PROXY environment variable.")
	}
	log.Fatalf("Failed to create model: %v", err)
}

下一步

第一个 Agent 成功运行后，你已经跨过了最重要的门槛。接下来，我们将深入理解 Agent 的三要素架构——Model、Tool、Instruction——这是构建任何复杂 Agent 系统的理论基石。同时，我们会探讨项目结构的工程化规范，让你的代码从"能跑"进化到"可维护"。

← Go 安装与验证 | 项目结构规范与 .env 管理 →

想跟着学更多 Go ADK 实战？关注「全栈之巅-梦兽编程」公众号，每周更新 Go / AI 编程实战干货。
也欢迎了解梦兽编程 AI 编程助手服务，帮你把 AI 编程工具用到生产环境。

ADK Go 安装与快速验证：跑通你的第一个 Agent#

安装 ADK Go#

方式一：go install（推荐）#

方式二：从源码编译#

获取 Gemini API Key#

获取方式#

环境变量配置#

快速验证：跑通 Hello World Agent#

项目初始化#

Agent 代码详解#

环境变量文件#

运行 Agent#

Agent 运行的两种方式#

CLI 模式（默认）#

Web 模式#

目录结构规范#

常见问题与排障指南#

Q：go install 报 certificate signed by unknown authority#

Q：运行 Agent 报 401 Unauthorized#

Q：运行 Agent 报 failed to create model 或连接超时#

下一步#