Google ADK最简Hello,World Skill:Python函数注册为Agent可调用的 Tool

本文以Google ADK（Python）为例，演示如何将一个Python函数注册为Agent可调用的Tool，实现最简"Hello, World"技能。核心在于通过tools=[hello_world]将函数注入Agent，由模型根据用户意图自主调用。该模式可扩展至真实业务能力（如查询Jira、读取飞书文档），强调输入输出规范、职责单一与可观测性，是构建可复用、可测试研发智能Agent的基础路径。

以 Google ADK（Python） 为例，一个最简单的 "Hello, World Skill" 本质上就是把一个 Python 函数注册为 Agent 可调用的 Tool。

在 ADK 的语境中，通常没有必须叫 Skill 的固定对象；一个 Skill 常以以下形式接入：

复制代码

Skill = 可被 Agent 调用的 Function Tool / MCP Tool / Sub-Agent / Workflow

对于 Hello World，最小形态就是 Function Tool。

1. 最简单的 Hello World Skill

目录结构示例：

复制代码

hello_agent/
└── agent.py

agent.py：

复制代码

from google.adk.agents import Agent


def hello_world(name: str = "World") -> dict:
    """
    向指定用户返回问候语。

    Args:
        name: 要问候的名称。

    Returns:
        包含执行结果的字典。
    """
    return {
        "success": True,
        "message": f"Hello, {name}!"
    }


root_agent = Agent(
    name="hello_agent",
    model="gemini-2.5-flash",
    description="一个可以调用 Hello World 技能的示例 Agent。",
    instruction="""
你是一个友好的问候助手。

当用户要求打招呼、问候某个人，或要求调用 Hello World 能力时：
1. 调用 hello_world 工具；
2. 将用户提到的名字作为 name 参数；
3. 清晰返回工具的执行结果。

如果用户没有提供名字，使用 World。
""",
    tools=[hello_world],  # 将函数作为 Tool / Skill 注入 Agent
)

这里最关键的一行是：

复制代码

tools=[hello_world]

它把 hello_world() 注册给了 root_agent。之后模型会根据用户意图，自主决定是否调用它。

2. 如何运行

先安装 ADK：

复制代码

pip install google-adk

再配置模型所需的 API Key。以 Gemini API 为例：

复制代码

export GOOGLE_API_KEY="你的_API_KEY"

进入 hello_agent 的上级目录，运行 ADK 开发界面：

复制代码

adk web

然后在浏览器中选择 hello_agent，输入：

复制代码

请向 AI 打个招呼

3. 预期 Agent 的执行过程

复制代码

用户输入：
请向 AI 打个招呼

Agent 判断：
需要调用问候能力

调用 Skill / Tool：
hello_world(name="AI")

工具返回：
{
  "success": true,
  "message": "Hello, AI!"
}

Agent 最终回复：
Hello, AI!

4. 为什么不让 Agent 直接回答 Hello World？

确实，下面这类任务：

复制代码

"你好"
"请说 Hello World"

模型不调用 Tool 也能直接完成。

但这个例子的目的不是为了证明"问候一定要用 Tool"，而是演示 Skill 的接入模式：

复制代码

业务函数
  ↓
注册为 Agent Tool
  ↓
由 Agent 按意图和指令决定是否调用
  ↓
Tool 返回结构化结果
  ↓
Agent 整理结果回复用户

把 hello_world 换成真实企业能力，模式完全相同：

复制代码

hello_world(name)
    ↓ 替换为
query_jira(issue_id)
read_feishu_doc(url)
get_git_commits(repo, branch)
analyze_android_trace(trace_file)
create_feishu_report(content)

5. 更像"业务 Skill"的版本

例如希望这个 Skill 不只是打招呼，而是返回当前环境、执行时间等结构化信息：

复制代码

from datetime import datetime
from google.adk.agents import Agent


def hello_world_skill(name: str, language: str = "zh") -> dict:
    """
    示例业务 Skill：生成结构化问候结果。

    Args:
        name: 被问候人的名称。
        language: 问候语言，仅支持 zh 或 en。

    Returns:
        Skill 的结构化执行结果。
    """
    greetings = {
        "zh": f"你好，{name}！欢迎使用研发智能助手。",
        "en": f"Hello, {name}! Welcome to R&D Assistant."
    }

    if language not in greetings:
        return {
            "success": False,
            "error": f"不支持的语言：{language}，仅支持 zh / en。"
        }

    return {
        "success": True,
        "skill_name": "hello_world_skill",
        "message": greetings[language],
        "executed_at": datetime.now().isoformat(timespec="seconds")
    }


root_agent = Agent(
    name="gallery_assistant",
    model="gemini-2.5-flash",
    instruction="""
你是研发智能助手。
当用户要求问候、验证系统连通性、验证 Skill 是否可调用时，
调用 hello_world_skill。

如果用户使用中文，language 传 zh；
用户使用英文，language 传 en。
""",
    tools=[hello_world_skill],
)

用户输入：

复制代码

用中文向 Zhangsan 问好，并验证 Skill 是否正常。

Skill 的返回可能是：

复制代码

{
  "success": true,
  "skill_name": "hello_world_skill",
  "message": "你好，Zhangsan！欢迎使用研发智能助手。",
  "executed_at": "2026-10-27T23:34:33"
}

6. 接入真实 Skill 时建议遵循的规范

Hello World 很简单，但未来接 Jira、飞书、Git、性能平台时，建议统一遵守：

复制代码

1. 输入明确：参数有类型、含义和边界；
2. 输出结构化：success、data、error、message；
3. 职责单一：一个 Skill 聚焦一类能力；
4. 无副作用优先：查询类与写入类 Skill 分开；
5. 写操作加确认：创建 Jira、发邮件、改文档必须确认；
6. 可观测：记录调用人、参数摘要、耗时、结果；
7. 可测试：函数本身可脱离 Agent 直接单测。

例如查询 Jira 的 Skill 建议长这样：

复制代码

def query_jira_issue(issue_key: str) -> dict:
    try:
        # 调 Jira API 的逻辑
        issue = {
            "key": issue_key,
            "summary": "首页卡顿",
            "status": "处理中"
        }
        return {
            "success": True,
            "data": issue
        }
    except Exception as e:
        return {
            "success": False,
            "error": str(e)
        }

然后直接：

复制代码

tools=[hello_world_skill, query_jira_issue]

这就是从一个 Hello World Skill 演进到真实研发 Agent 的基本方式。