adk-sample-creator

ADK サンプル作成ツール

contributing/samples/ にサンプルを作成します。各サンプルは、1つか2つの機能を試すための意図的に最小限のエージェントです。エンドツーエンドのアプリケーションを提供する 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 があります。1つの機能に複数のバリエーションが必要な場合は、サンプルをさらに1階層ネストしていることがあります。たとえば、plugins/plugin_reflect_tool_retry/basic/ が該当します。

サンプルディレクトリには、実演する機能にちなんだ snake_case の名前を付けてください。 dynamic_nodes、fan_out_fan_in、streaming_tool_events。

_agent という接尾辞を付けたり、カテゴリ名を接頭辞として繰り返したりしないでください。すべてのサンプルがエージェントであり、カテゴリ名はすでにパスに含まれています。既存のディレクトリの多くには両方が付いていますが、それらを踏襲しないでください。

2. agent.py を作成する

サンプルディレクトリの内容：

ファイル	必須	用途
agent.py	はい	エージェントまたはワークフローです。root_agent を公開する必要があります。
README.md	はい	readme-template.md を参照してください。
__init__.py	場合による	サンプルをパッケージとしてインポートする場合に配置します。
tests/*.json	いいえ	評価セットとして使用する記録済みセッションです。

ファイルを直接実行およびインポートできるよう、絶対インポートを使用してください。

Agent インスタンスに model= を設定しないでください。サンプルはシステムで設定されたモデルを継承するため、デフォルトモデルが変更されても動作します。model="gemini-2.5-flash" とハードコードすると、廃止予定のモデルにサンプルが固定されます。ユーザーが特定のモデルを明示的に求めた場合に限り設定してください。

次に、2つのパターンのいずれかを選びます。

パターン 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

Workflow はプライベートな google.adk.workflow._* モジュールではなく、google.adk からインポートしてください。

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 でノードとして直接使用できます。ctx.run_node を呼び出すノードに対する rerun_on_resume=True など、オプションが必要な場合は @node(...) デコレーターを使用してください。

パターン B — 単体エージェント向けのスタンドアロンエージェント、またはシンプルなツール使用

グラフがなく、エージェントが独自のループを制御する場合に使用します。

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 のサンプルを作成する前に、次の2つを読んでください。動的グラフと静的グラフの例が1つずつあります。

• contributing/samples/workflows/dynamic_nodes/agent.py — ctx.run_node を使って while ループを実行する Python ノードです。エージェントの呼び出し回数はエッジではなく、実行時に決まります。

  @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 — 3つの関数が 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,
      )],
  )