Skip to content

Go Quickstart for ADK

ADK Go 快速入门

This guide shows you how to get up and running with Agent Development Kit for Go. Before you start, make sure you have the following installed:

本指南向您展示如何开始使用 Go 版智能体开发工具包。在开始之前,请确保您已安装以下内容:

  • Go 1.24.4 or later Go 1.24.4 或更高版本
  • ADK Go v0.2.0 or later ADK Go v0.2.0 或更高版本

Create an agent project

创建智能体项目

Create an agent project with the following files and directory structure:

创建一个具有以下文件和目录结构的智能体项目:

my_agent/
    agent.go    # main agent code
                 # 主要智能体代码
    .env        # API keys or project IDs
                 # API 密钥或项目 ID
Create this project structure using the command line

使用命令行创建此项目结构

mkdir my_agent\
type nul > my_agent\agent.go
type nul > my_agent\env.bat

mkdir -p my_agent/ && \
    touch my_agent/agent.go && \
    touch my_agent/.env

Define the agent code

定义智能体代码

Create the code for a basic agent that uses the built-in Google Search tool. Add the following code to the my_agent/agent.go file in your project directory:

创建使用内置 Google 搜索工具 的基本智能体的代码。将以下代码添加到项目目录中的 my_agent/agent.go 文件:

my_agent/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-3-pro-preview", &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.",
        Description: "返回指定城市的当前时间。",
        Instruction: "You are a helpful assistant that tells the current time in a city.",
        Instruction: "您是一个有用的助手,可以告诉您城市的当前时间。",
        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())
    }
}

Configure project and dependencies

配置项目和依赖项

Use the go mod command to initialize project modules and install the required packages based on the import statement in your agent code file:

使用 go mod 命令初始化项目模块并根据智能体代码文件中的 import 语句安装所需的包:

go mod init my-agent/main
go mod tidy

Set your API key

设置您的 API 密钥

This project uses the Gemini API, which requires an API key. If you don't already have a Gemini API key, create a key in Google AI Studio on the API Keys page.

本项目使用 Gemini API,该 API 需要 API 密钥。如果您还没有 Gemini API 密钥,请前往 Google AI Studio 在 API 密钥 页面创建密钥。

In a terminal window, write your API key into the .env or env.bat file of your project to set environment variables:

在终端窗口中,将您的 API 密钥写入项目的 .env 或 env.bat 文件以设置环境变量:

Update: my_agent/.env
echo 'export GOOGLE_API_KEY="YOUR_API_KEY"' > .env
Update: my_agent/env.bat
echo 'set GOOGLE_API_KEY="YOUR_API_KEY"' > env.bat
Using other AI models with ADK

在 ADK 中使用其他 AI 模型

ADK supports the use of many generative AI models. For more information on configuring other models in ADK agents, see Models & Authentication.

ADK 支持使用多种生成式 AI 模型。有关在 ADK 智能体中配置其他模型的更多信息,请参阅模型和身份验证。

Run your agent

运行您的智能体

You can run your ADK agent using the interactive command-line interface you defined or the ADK web user interface provided by the ADK Go command line tool. Both these options allow you to test and interact with your agent.

您可以使用您定义的交互式命令行界面或 ADK Go 命令行工具提供的 ADK Web 用户界面运行您的 ADK 智能体。这两个选项都允许您测试和与智能体交互。

Run with command-line interface

使用命令行界面运行

Run your agent using the following Go command:

使用以下 Go 命令运行您的智能体:

Run from: my_agent/ directory
# Remember to load keys and settings: source .env OR env.bat
# 记住加载密钥和设置: source .env 或 env.bat
go run agent.go

adk-run.png

Run with web interface

使用 Web 界面运行

Run your agent with the ADK web interface using the following Go command:

使用以下 Go 命令通过 ADK Web 界面运行您的智能体:

Run from: my_agent/ directory
# Remember to load keys and settings: source .env OR env.bat
# 记住加载密钥和设置: source .env 或 env.bat
go run agent.go web api webui

This command starts a web server with a chat interface for your agent. You can access the web interface at (http://localhost:8080). Select your agent at the upper left corner and type a request.

此命令启动一个带有智能体聊天界面的 Web 服务器。您可以在 (http://localhost:8080) 访问 Web 界面。在左上角选择智能体并输入请求。

adk-web-dev-ui-chat.png

Caution: ADK Web for development only

警告:ADK Web 仅用于开发

ADK Web is not meant for use in production deployments. You should use ADK Web for development and debugging purposes only.

ADK Web 不适用于生产环境部署。您应该仅将 ADK Web 用于开发和调试目的。

Next: Build your agent

下一步:构建您的智能体

Now that you have ADK installed and your first agent running, try building your own agent with our build guides:

既然您已经安装了 ADK 并运行了第一个智能体,请尝试使用我们的构建指南构建您自己的智能体: