adk-sample-creator

ADK 示例创建器

在 contributing/samples/ 下创建示例。这些示例刻意保持精简，每个示例仅演示一两个功能；这与 adk-samples 仓库不同，后者包含完整的端到端应用。

如果还没有阅读过 adk-style 技能，请先阅读，了解 ADK 2.0 的约定。

1. 选择类别目录

几乎所有示例都位于 contributing/samples/{category}/{sample_name}/。列出类别，并在创建任何内容之前与用户确认示例所属类别——工作流示例放在 workflows/ 之外是最常见的错误。

ls contributing/samples/

类别包括 workflows、patterns、core、multi_agent、tools、models、live、mcp、a2a、evaluation 和 plugins。少数示例会再嵌套一层，因为某个功能需要多个变体，例如 plugins/plugin_reflect_tool_retry/basic/。

示例目录应以所演示的功能命名，并使用 snake_case：dynamic_nodes、fan_out_fan_in、streaming_tool_events。

不要添加 _agent 后缀，也不要将类别名作为前缀重复添加——每个示例都是一个 Agent，而类别已体现在路径中。许多现有目录仍同时带有这两者；不要照搬。

2. 编写 agent.py

示例目录中的内容：

文件	必需	用途
agent.py	是	Agent 或工作流。必须公开 root_agent。
README.md	是	参见 readme-template.md。
__init__.py	有时	当示例作为包导入时需要提供。
tests/*.json	否	用作评估集的记录会话。

使用绝对导入，以便直接运行和导入该文件。

不要为 Agent 实例设置 model=。示例会继承系统配置的模型，这样默认模型变更时仍能正常运行；硬编码 model="gemini-2.5-flash" 会将示例绑定到即将退役的模型。只有用户明确要求使用特定模型时才设置该参数。

然后选择以下两种结构之一。

模式 A — 工作流，适用于多步骤图

当示例需要多个节点、路由或并行执行时使用。

from google.adk import Agent
from google.adk import Context
from google.adk import Event
from google.adk import Workflow
from google.adk.workflow import JoinNode
from google.adk.workflow import node

从 google.adk 导入 Workflow，不要从私有的 google.adk.workflow._* 模块导入。

my_agent = Agent(name="my_agent", instruction="...")


@node()
async def my_node(node_input: str) -> str:
  return "result"


root_agent = Workflow(
    name="root_agent",
    edges=[("START", my_node)],
)

普通函数可以直接用作 edges 中的节点；只有在需要某个选项时才使用 @node(...) 装饰器，例如对调用 ctx.run_node 的节点设置 rerun_on_resume=True。

模式 B — 独立 Agent，适用于单 Agent 或简单工具调用

当没有图，且由 Agent 自行驱动循环时使用。

from google.adk import Agent
from google.adk.tools import google_search

root_agent = Agent(
    name="standalone_assistant",
    instruction="You are a helpful assistant.",
    description="An assistant that can help with queries.",
    tools=[google_search],
)

3. 编写 README.md

遵循 readme-template.md——包括章节顺序、提示词格式、Mermaid 拓扑规则，以及 docs/guides/ 的相对链接层级。

示例参考

编写新的模式 A 示例前，请先阅读以下两个示例——一个动态流程图，一个静态流程图。

• contributing/samples/workflows/dynamic_nodes/agent.py——Python 节点通过 ctx.run_node 驱动 while 循环，因此 Agent 调用次数由运行时决定，而不是由边决定。

  @node(rerun_on_resume=True)
  async def orchestrate(ctx: Context, node_input: str) -> str:
    yield Event(state={"topic": node_input})
  
    while True:
      headline = await ctx.run_node(generate_headline)
      # ...
  

• contributing/samples/workflows/fan_out_fan_in/agent.py——三个函数从 START 并行运行，由 JoinNode 收集，然后进行汇总。

  join_node = JoinNode(name="join_for_results")
  
  root_agent = Workflow(
      name="root_agent",
      edges=[(
          "START",
          (make_uppercase, count_characters, reverse_string),
          join_node,
          aggregate,
      )],
  )