第一章：快速开始 - 你的第一个 AI Agent

用户："帮我查一下北京今天天气"
  ↓
Agent 的脑子(LLM)理解了：用户想知道北京的天气
  ↓
Agent 的脑子决定：我需要用 Google 搜索来查一下
  ↓
Agent 的手脚(Tool)：调用 Google Search，搜索 "北京今天天气"
  ↓
Agent 的脑子(LLM)：把搜索结果整理成人话
  ↓
回复用户："北京今天晴，气温 -2 到 8 度，西北风 3-4 级..."

你提供：脑子(模型) + 技能(工具) + 岗位说明(指令)
   ↓
ADK 帮你：组装 Agent + 管理对话 + 提供运行环境
   ↓
产出：一个能跑在命令行/Web/API/A2A 协议上的 AI Agent

                    +-----------------+
                    |    Launcher     |
                    | (启动器/入口)    |
                    | console/web/    |
                    | rest/a2a        |
                    +--------+--------+
                             |
                             | 创建并驱动
                             v
                    +--------+--------+
                    |     Runner      |
                    | (运行时引擎)     |
                    | 管理执行流程     |
                    +--------+--------+
                             |
                    +--------+--------+
                    |                 |
                    v                 v
           +-------+-------+ +------+-------+
           |    Agent       | |   Session    |
           | (智能体)       | | (对话会话)    |
           +-------+-------+ +--------------+
                   |
          +--------+--------+
          |                 |
          v                 v
   +------+------+  +------+------+
   |    Model    |  |    Tools    |
   | (LLM大脑)   |  | (工具/技能)  |
   +-------------+  +-------------+

go version
# 输出类似：go version go1.22.0 darwin/arm64

# Linux / macOS
export GOOGLE_API_KEY="你的API Key"

# 建议加到 ~/.bashrc 或 ~/.zshrc 里，这样每次打开终端都能用
echo 'export GOOGLE_API_KEY="你的API Key"' >> ~/.zshrc
source ~/.zshrc

# Windows PowerShell
$env:GOOGLE_API_KEY="你的API Key"

# 或者永久设置（需要管理员权限）
[System.Environment]::SetEnvironmentVariable("GOOGLE_API_KEY", "你的API Key", "User")

# 创建项目目录
mkdir my-first-agent
cd my-first-agent

# 初始化 Go module
go mod init my-first-agent

# 安装 ADK-Go 和相关依赖
go get google.golang.org/adk
go get google.golang.org/genai

package main

import (
    "context"
    "log"
    "os"

    "google.golang.org/genai"

    "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"
)

func main() {
    ctx := context.Background()

    // =========================================
    // 第一步：创建模型 - 这是 Agent 的"大脑"
    // =========================================
    model, err := gemini.NewModel(ctx, "gemini-2.5-flash", &genai.ClientConfig{
        // 从环境变量读取 API Key
        APIKey: os.Getenv("GOOGLE_API_KEY"),
    })
    if err != nil {
        log.Fatalf("创建模型失败: %v", err)
    }

    // =========================================
    // 第二步：创建 Agent - 给它名字、大脑、指令和工具
    // =========================================
    a, err := llmagent.New(llmagent.Config{
        // Agent 的唯一标识名，在整个 Agent 树中必须唯一
        Name: "weather_time_agent",
        // Agent 的大脑，用哪个 LLM 模型来思考
        Model: model,
        // Agent 的能力描述（一句话说明它能做什么）
        Description: "回答关于城市天气和时间的问题",
        // Agent 的工作指令（相当于 System Prompt）
        Instruction: "你的唯一职责是回答关于特定城市的当前时间和天气的问题。" +
            "你必须拒绝回答与时间或天气无关的任何问题。" +
            "请用中文回答。",
        // Agent 可以使用的工具列表
        Tools: []tool.Tool{
            // Google 搜索工具 - 让 Agent 能联网搜索实时信息
            geminitool.GoogleSearch{},
        },
    })
    if err != nil {
        log.Fatalf("创建Agent失败: %v", err)
    }

    // =========================================
    // 第三步：配置启动器并运行
    // =========================================
    config := &launcher.Config{
        // AgentLoader 告诉启动器要加载哪个 Agent
        AgentLoader: agent.NewSingleLoader(a),
    }

    // 使用 full.NewLauncher() 创建一个功能最全的启动器
    // 它支持 console、web、rest、a2a 四种运行模式
    l := full.NewLauncher()

    // 根据命令行参数决定以哪种模式运行
    if err = l.Execute(ctx, config, os.Args[1:]); err != nil {
        log.Fatalf("运行失败: %v\n\n%s", err, l.CommandLineSyntax())
    }
}

import (
    "context"
    "log"
    "os"

    "google.golang.org/genai"               // Google GenAI SDK，提供模型配置等类型

    "google.golang.org/adk/agent"            // Agent 基础接口和加载器
    "google.golang.org/adk/agent/llmagent"   // LLM Agent 的具体实现
    "google.golang.org/adk/cmd/launcher"     // 启动器的配置类型
    "google.golang.org/adk/cmd/launcher/full" // 功能最全的启动器
    "google.golang.org/adk/model/gemini"     // Gemini 模型的实现
    "google.golang.org/adk/tool"             // 工具接口
    "google.golang.org/adk/tool/geminitool"  // Gemini 内置工具（如 Google 搜索）
)

model, err := gemini.NewModel(ctx, "gemini-2.5-flash", &genai.ClientConfig{
    APIKey: os.Getenv("GOOGLE_API_KEY"),
})

a, err := llmagent.New(llmagent.Config{
    Name:        "weather_time_agent",
    Model:       model,
    Description: "回答关于城市天气和时间的问题",
    Instruction: "你的唯一职责是回答关于特定城市的当前时间和天气的问题。...",
    Tools:       []tool.Tool{
        geminitool.GoogleSearch{},
    },
})

Name: "weather_time_agent",

Model: model,

Description: "回答关于城市天气和时间的问题",

Instruction: "你的唯一职责是回答关于特定城市的当前时间和天气的问题。" +
    "你必须拒绝回答与时间或天气无关的任何问题。" +
    "请用中文回答。",

// 比如这样的指令，ADK 会在运行时把 {user_name} 替换成 Session 中的实际值
Instruction: "你好 {user_name}，我是你的天气助手。",

Tools: []tool.Tool{
    geminitool.GoogleSearch{},
},

// 创建启动配置
config := &launcher.Config{
    AgentLoader: agent.NewSingleLoader(a),
}

// 创建启动器
l := full.NewLauncher()

// 执行
if err = l.Execute(ctx, config, os.Args[1:]); err != nil {
    log.Fatalf("运行失败: %v\n\n%s", err, l.CommandLineSyntax())
}

type Config struct {
    SessionService   session.Service    // 会话存储服务（默认用内存）
    ArtifactService  artifact.Service   // 文件/制品存储服务
    MemoryService    memory.Service     // 长期记忆服务
    AgentLoader      agent.Loader       // Agent 加载器（必需）
    PluginConfig     runner.PluginConfig // 插件配置
    TelemetryOptions []telemetry.Option  // 遥测配置
}

// full.NewLauncher() 的内部实现（简化版）
func NewLauncher() launcher.Launcher {
    return universal.NewLauncher(
        console.NewLauncher(),     // 命令行交互模式
        web.NewLauncher(           // Web 模式（包含多个子模式）
            api.NewLauncher(),     //   REST API
            a2a.NewLauncher(),     //   Agent-to-Agent 协议
            webui.NewLauncher(),   //   Web UI 界面
        ),
    )
}

l := console.NewLauncher()

l.Execute(ctx, config, os.Args[1:])

go run . console

User -> 北京现在天气怎么样？

Agent -> 根据最新的搜索结果，北京现在的天气情况如下：
- 温度：-2°C 到 8°C
- 天气：晴转多云
- 风力：西北风 3-4 级
...

User -> 帮我写一首诗

Agent -> 抱歉，我只能回答关于城市天气和时间的问题。写诗不在我的职责范围内。
如果你想了解某个城市的天气或时间，请随时告诉我！

User -> （按 Ctrl+C 退出）

go run . web webui

go run . web -port 3000 webui

go run . web api

# 先创建一个会话
curl -X POST http://localhost:8080/apps/weather_time_agent/users/test_user/sessions \
  -H "Content-Type: application/json"

# 假设返回的 session id 是 "session_abc123"
# 发送消息给 Agent
curl -X POST http://localhost:8080/run \
  -H "Content-Type: application/json" \
  -d '{
    "app_name": "weather_time_agent",
    "user_id": "test_user",
    "session_id": "session_abc123",
    "new_message": {
      "role": "user",
      "parts": [{"text": "上海今天天气如何？"}]
    }
  }'

go run . web a2a

# 同时启动 REST API 和 Web UI
go run . web api webui

# 同时启动所有 Web 子模式
go run . web api webui a2a

                         用户 / 客户端
                              |
                              v
    +-----------------------------------------------------+
    |                    Launcher (启动器)                   |
    |                                                       |
    |   console     web+webui    web+api      web+a2a      |
    |   (命令行)     (Web界面)   (REST API)   (A2A协议)     |
    +-------------------------+-----------------------------+
                              |
                              | 创建 Session，转发用户消息
                              v
    +-----------------------------------------------------+
    |                    Runner (运行引擎)                   |
    |                                                       |
    |  - 管理 Agent 的执行流程                               |
    |  - 找到正确的 Agent 来处理请求                          |
    |  - 将事件保存到 Session                                |
    |  - 管理插件的生命周期                                   |
    +-------------------------+-----------------------------+
                              |
               +--------------+--------------+
               |                             |
               v                             v
    +----------+----------+       +----------+----------+
    |   Agent (智能体)     |       |  Session (会话)      |
    |                      |       |                      |
    |  Name: 唯一标识      |       |  ID: 会话标识        |
    |  Description: 描述   |       |  Events: 事件列表    |
    |  Instruction: 指令   |       |  State: 状态存储     |
    |  Model: LLM大脑      |       |                      |
    |  Tools: 工具列表     |       |  (对话历史都存在这里)  |
    |  SubAgents: 子Agent  |       |                      |
    +----------+----------+       +---------------------+
               |
      +--------+--------+
      |                  |
      v                  v
+-----+------+    +------+-------+
| Model(LLM) |    | Tools(工具)   |
|             |    |              |
| Gemini      |    | GoogleSearch |
| 2.5 Flash   |    | 自定义函数    |
| 2.5 Pro     |    | MCP工具      |
| ...         |    | Agent工具    |
+-------------+    +--------------+

1. 用户发送消息 "北京天气怎么样？"
   |
   v
2. Launcher 接收到消息，转交给 Runner
   |
   v
3. Runner 从 Session 中加载对话历史
   |
   v
4. Runner 找到应该处理这条消息的 Agent（这里就是 weather_time_agent）
   |
   v
5. Agent 运行：
   a. 构建请求：系统指令 + 对话历史 + 用户新消息 + 可用工具列表
   b. 发送给 Model（Gemini）
   c. Model 返回：我要调用 google_search("北京天气")
   d. ADK 执行 Google Search 工具
   e. 搜索结果返回给 Model
   f. Model 根据搜索结果生成最终回复
   |
   v
6. Runner 将 Agent 的回复事件保存到 Session
   |
   v
7. Launcher 将回复返回给用户

llmagent.Config{
    // === 基础配置（我们已经用过了）===
    Name:        "agent_name",        // 必需：唯一标识
    Model:       model,               // 必需：LLM 模型
    Description: "做什么的",           // 推荐：能力描述
    Instruction: "你应该...",          // 推荐：行为指令
    Tools:       []tool.Tool{...},    // 可选：工具列表

    // === 子 Agent（多 Agent 协作时用）===
    SubAgents: []agent.Agent{...},    // 可选：子 Agent 列表

    // === 回调函数（拦截和定制行为）===
    BeforeAgentCallbacks:  []agent.BeforeAgentCallback{...},  // Agent 运行前
    AfterAgentCallbacks:   []agent.AfterAgentCallback{...},   // Agent 运行后
    BeforeModelCallbacks:  []llmagent.BeforeModelCallback{...}, // 模型调用前
    AfterModelCallbacks:   []llmagent.AfterModelCallback{...},  // 模型调用后
    BeforeToolCallbacks:   []llmagent.BeforeToolCallback{...},  // 工具调用前
    AfterToolCallbacks:    []llmagent.AfterToolCallback{...},   // 工具调用后

    // === 高级配置 ===
    GenerateContentConfig: &genai.GenerateContentConfig{
        Temperature: genai.Ptr(float32(0.7)), // 控制回答的随机性
    },
    OutputKey: "result",              // 把 Agent 输出保存到 Session 状态

    // === 全局指令（对整个 Agent 树生效）===
    GlobalInstruction: "你是一个友好的 AI 助手...",
}

Launcher  -->  Runner  -->  Agent  -->  Model + Tools
                              |
                           Session

User -> Please translate: 今天天气真好
Agent -> Today's weather is really nice.

User -> 翻译：The quick brown fox jumps over the lazy dog
Agent -> 敏捷的棕色狐狸跳过了那只懒狗

User -> 帮我写一首诗
Agent -> 抱歉，我只负责中英文翻译，无法为你写诗。请给我需要翻译的内容。

a, err := llmagent.New(llmagent.Config{
    // ... 其他配置 ...
    GenerateContentConfig: &genai.GenerateContentConfig{
        // 温度范围 0.0 - 2.0
        // 低温度（0.1）：回答更确定、更一致
        // 高温度（1.5）：回答更有创意、更多样
        Temperature: genai.Ptr(float32(0.1)),
    },
})