adk-skill

Google Agent Development Kit（ADK）ガイド

概要

ADK は、Gemini モデルを利用した AI エージェントを構築するための、Google のオープンソースフレームワークです。ADK 2.0 以降では、エージェント、ツール、関数を組み合わせ可能な実行グラフのノードとして扱う、グラフベースのワークフローランタイムエンジンが導入されています。メモリ、アーティファクト、ツール、コールバック、デプロイオプションが組み込まれており、単一エージェント、マルチエージェント、協調型、動的なワークフローアーキテクチャをサポートします。

重要なルール

1. エントリーポイントは root_agent です — agent.py 内のモジュールレベル変数、またはグラフベースのエージェントの場合は Workflow オブジェクトです。
2. すべてのエージェントパッケージに __init__.py が必要です。このファイルでエージェントモジュールをインポートします：from . import agent
3. 実行前に .env で GOOGLE_API_KEY を設定するか、Vertex AI の認証情報を設定してください。
4. ADK 2.0 では、エージェントはノードです。 _run_async_impl() をオーバーライドしないでください。代わりに BeforeAgentCallback / AfterAgentCallback を使用してください。
5. context.session.events にイベントを直接追加しないでください。 ノードからイベントを yield してください。フレームワークが永続化とルーティングを管理します。
6. ツールで BaseException を捕捉しないでください — HITL の一時停止／再開や自動再試行が機能しなくなります。
7. 1 エージェントにつき 1 つの責務を持たせてください。 5 つ以上のツールを持つエージェントは、専門エージェントに分割してください。
8. エージェント間で確実にデータを受け渡すには output_key と output_schema を使用してください — フリーテキストではなく、こちらを使います。

ドキュメントとリソース

• ADK ドキュメント：https://adk.dev/llms.txt
• 公式サンプル：https://github.com/google/adk-samples
• 2.0 移行ガイド：https://adk.dev/2.0/

対応言語

言語	パッケージ	インストール	ADK 2.x
Python	google-adk	pip install google-adk	2.7（リファレンス）
Go	google.golang.org/adk/v2	go get google.golang.org/adk/v2	2.2
Java	com.google.adk:google-adk	Maven/Gradle	1.x のみ
Kotlin	com.google.adk:google-adk-kotlin-core	Gradle	0.8 pre-GA
TypeScript	@google/adk	npm install @google/adk	2.0

Go と TypeScript では、並行して 1.x の LTS 系列（google.golang.org/adk / @google/adk@^1）も公開されています。

このガイドでは Python の例を紹介します。Java、Go、Kotlin、TypeScript のパターンについては、references/multi-language.md を参照してください。

前提条件

Python 3.10 以降と pip install google-adk が必要です。.env で GOOGLE_API_KEY を設定するか、Vertex AI の認証情報（GOOGLE_CLOUD_PROJECT）を設定してください。その他の言語：Java 17 以降、Go 1.25 以降（v2）、Node 24 以降。オプションの追加機能：[a2a]、[bigquery-analytics]（2.7 以降で分割）、テンプレート用の Jinja2。

クイックリファレンス

タスク	ADK 2.x の方法
単一エージェント	モデル、指示、ツールを指定した LlmAgent
グラフベースのワークフロー	Agent／Function ノードを含む Workflow(edges=[...])
動的（コード駆動型）ワークフロー	@node デコレーターと ctx.run_node() によるループ／分岐
協調型チーム	sub_agents と mode='single_turn'/'task'/'chat' を指定した Agent
順次パイプライン	SequentialAgent または Workflow チェーン
並列実行	ParallelAgent または asyncio.gather(ctx.run_node(...))
反復的な改善	LoopAgent または動的ワークフロー内の while ループ
ツールとしてのエージェント	オンデマンドで委任する AgentTool
Google 管理のエージェント	ManagedAgent（プレビュー、2.4 以降）
MCP サーバーとしてのエージェント	agent.to_mcp_server()（2.5 以降）
リモートエージェント（A2A）	RemoteA2aAgent と to_a2a()
カスタムツール	型ヒントと docstring を備えた Python 関数
OpenAPI ツール	OpenAPI 仕様からの OpenAPIToolset
構造化出力	output_schema と output_key を介した Pydantic モデル
状態管理	callback_context.state と tool_context.state
セッション間のメモリ	MemoryService と PreloadMemoryTool／LoadMemory
バイナリデータの永続化	ArtifactService（save_artifact、load_artifact）
MCP 統合	接続パラメーターを指定した MCPToolset
YAML エージェント設定／セッションの巻き戻し	adk create --type=config／runner.rewind_async()
ストリーミング（Live API）	双方向の音声／動画に対応する LiveRequestQueue
テスト	InMemoryRunner を使った pytest
評価	.test.json を含む EvalSet、adk eval CLI

---

プロジェクト構成

コードベースのプロジェクト：

my_agent/
├── my_agent/
│   ├── __init__.py          # Must import agent module
│   ├── agent.py             # Defines root_agent (entry point)
│   ├── prompts.py           # Instruction strings (optional)
│   ├── tools.py             # Custom tool functions (optional)
│   └── sub_agents/          # Sub-agent packages (optional)
├── tests/test_agent.py
├── pyproject.toml
└── .env

YAML ベースのプロジェクト： adk create --type=config my_agent は my_agent/root_agent.yaml と .env を生成します。

重要：init.py と root_agent

# my_agent/__init__.py
from . import agent

ADK 2.0 では、root_agent に LlmAgent または Workflow オブジェクトを指定できます。

# my_agent/agent.py
from google.adk.agents import LlmAgent

root_agent = LlmAgent(
    name="my_agent",
    # model is optional — built-in default: gemini-3.5-flash
    description="Brief description for agent discovery",
    instruction="Detailed system prompt...",
    tools=[...],
)

---

ワークフローの種類

ADK 2.0 には、マルチエージェントの処理を構成する方法が 3 つあります。1.x のテンプレートワークフローも引き続き使用できますが、現在は後継の方式に置き換えられています。

1. グラフベースのワークフロー

ノード（Agent、Function、Tool）と明示的なルーティングエッジからなる宣言型グラフです。決定論的で構造化されたプロセスに最適です。

from google.adk import Workflow, Event
from google.adk.agents import LlmAgent

classifier = LlmAgent(
    name="classifier", model="gemini-flash-latest",
    instruction="Classify input as 'BUG', 'SUPPORT', or 'LOGISTICS'.",
    output_schema=str,
)

def router(node_input: str):
    routes = [r.strip() for r in node_input.split(",")]
    return Event(route=routes)

def handle_bug():    return Event(message="Handling bug...")
def handle_support(): return Event(message="Handling support...")
def handle_logistics(): return Event(message="Handling logistics...")

root_agent = Workflow(
    name="routing_workflow",
    edges=[
        ("START", classifier, router),
        (router, {"BUG": handle_bug, "SUPPORT": handle_support, "LOGISTICS": handle_logistics}),
    ],
)

2. 動的ワークフロー

@node デコレーターと ctx.run_node() を使ったプログラムによるオーケストレーションです。複雑な分岐や反復ロジックに最適です。

from google.adk import Context, Workflow
from google.adk.workflow import node

@node(name="process_item")
def process(item: str) -> str:
    return f"Processed: {item}"

@node(rerun_on_resume=True)
async def orchestrator(ctx: Context, items: list[str]) -> str:
    results = []
    for item in items:
        result = await ctx.run_node(process, item)
        results.append(result)
    return "\n".join(results)

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

HITL を実現するには、ノードから RequestInput を yield します。references/workflows.md を参照してください。

3. 協調型エージェント

コーディネーターが、動作モードを指定してサブエージェントに処理を委任します。

from google.adk.agents import LlmAgent

weather_agent = LlmAgent(
    name="weather_checker", mode="single_turn", tools=[get_weather],
)
flight_agent = LlmAgent(
    name="flight_booker", mode="task",
    input_schema=FlightInput, output_schema=FlightResult,
    tools=[search_flights, book_flight],
)
root_agent = LlmAgent(
    name="travel_planner",  # Coordinator — auto-injects request_task_* tools
    sub_agents=[weather_agent, flight_agent],
)

協調モード

モード：chat（デフォルト。引き継ぎまで会話を制御）、task（complete_task によって自動的に復帰。ユーザーへの確認は必要な場合のみ）、single_turn（ユーザーとのやり取りなし。並列実行に対応し、結果を返す）。表全体については、references/workflows.md を参照してください。

注： ルートエージェントに mode を設定しないでください。これはサブエージェント専用です。タスクモードのエージェントにはサブエージェントを設定できません。

4. テンプレートワークフロー（1.x 互換）

SequentialAgent、ParallelAgent、LoopAgent は引き続き使用できますが、現在は後継の方式に置き換えられています。references/advanced-patterns.md を参照してください。

---

ツール

関数ツール

型ヒントと docstring を備えた Python 関数は、すべてツールになります。

def get_weather(city: str, units: str = "celsius") -> dict:
    """Get current weather for a city.

    Args:
        city: The city name to look up weather for.
        units: Temperature units - 'celsius' or 'fahrenheit'.
    """
    return {"temperature": 22, "conditions": "sunny", "humidity": 45}

agent = LlmAgent(
    name="weather_agent", model="gemini-flash-latest",
    instruction="Help users check the weather.", tools=[get_weather],
)

要件： すべてのパラメーターに型ヒントを付け、説明と Args を含む docstring を記述し、戻り値の型を注釈してください。

状態にアクセスするツール

from google.adk.tools import ToolContext

def add_to_cart(item: str, quantity: int, tool_context: ToolContext) -> dict:
    """Add an item to the shopping cart."""
    cart = tool_context.state.get("cart", [])
    cart.append({"item": item, "quantity": quantity})
    tool_context.state["cart"] = cart
    return {"status": "added", "cart_size": len(cart)}

AgentTool

from google.adk.tools.agent_tool import AgentTool

specialist = LlmAgent(
    name="code_reviewer", model="gemini-flash-latest",
    instruction="Review code for bugs and best practices.",
)
coordinator = LlmAgent(
    name="coordinator", model="gemini-flash-latest",
    instruction="Coordinate tasks. Use code_reviewer for code reviews.",
    tools=[AgentTool(agent=specialist)],
)

組み込みツール、OpenAPI、MCP

from google.adk.tools import google_search, load_memory
from google.adk.tools.openapi_tool.openapi_spec_parser.openapi_toolset import OpenAPIToolset
from google.adk.tools.mcp_tool import MCPToolset, StdioConnectionParams
from mcp import StdioServerParameters

# Built-in
agent = LlmAgent(name="researcher", tools=[google_search, load_memory])

# OpenAPI (generate tools from REST API spec)
toolset = OpenAPIToolset(spec_str=openapi_spec_json, spec_str_type="json")

# MCP
mcp_toolset = MCPToolset(
    connection_params=StdioConnectionParams(
        server_params=StdioServerParameters(command="npx", args=["-y", "some-mcp-server"]),
    ),
)

高度なツールのパターン（FunctionTool、ToolboxToolset、ツール認証、ツールの確認、LoadArtifactsTool）については、references/tools-reference.md を参照してください。

---

メモリとアーティファクト

メモリ（セッション間）

長期メモリはセッションをまたいで保持されます。エージェントは組み込みツールを使ってメモリを取得します。

from google.adk.memory import InMemoryMemoryService
from google.adk.tools.preload_memory_tool import PreloadMemoryTool

memory_service = InMemoryMemoryService()  # Prototyping (or VertexAiMemoryBankService for prod)

agent = LlmAgent(
    name="memory_agent", model="gemini-flash-latest",
    instruction="Answer questions using past conversation history.",
    tools=[PreloadMemoryTool()],
)

runner = Runner(
    agent=agent, app_name="my_app",
    session_service=session_service,
    memory_service=memory_service,
)

バックエンドは 3 種類あります：InMemoryMemoryService、VertexAiMemoryBankService、VertexAiRagMemoryService。references/memory-artifacts.md を参照してください。

アーティファクト（バイナリデータ）

バージョン管理されたバイナリデータ（ファイル、画像、音声）：

from google.adk.artifacts import InMemoryArtifactService

artifact_service = InMemoryArtifactService()  # Or GcsArtifactService

runner = Runner(
    agent=agent, app_name="my_app",
    session_service=session_service,
    artifact_service=artifact_service,
)
# In tools: tool_context.save_artifact(filename, part)
#            tool_context.load_artifact(filename)
#            tool_context.list_artifacts()

references/memory-artifacts.mdを参照してください。

---

状態管理

状態は、エージェント、ツール、コールバック間で共有される辞書です。スコープは次のとおりです。state["key"]（セッション）、app:key（アプリ全体）、user:key（ユーザー全体）。output_keyとoutput_schemaを使って、エージェント間でデータを渡します。指示では{var}／{prefix:var}プレースホルダーを使用できます。オプトインのJinja2テンプレート（use_jinja2=True、2.7以降、オプションの依存関係）では、条件分岐、ループ、ドット記法によるアクセスが可能です。

researcher = LlmAgent(name="researcher", output_key="findings", output_schema=ResearchOutput, ...)
writer = LlmAgent(name="writer", instruction="Write report based on state['findings'].", ...)
pipeline = SequentialAgent(name="pipeline", sub_agents=[researcher, writer])

---

コールバック

コールバックはエージェントのライフサイクルに介入します。続行するにはNoneを返し、処理を短絡させるには値を返します。ADK 2.0では、_run_async_impl()をオーバーライドする代わりにコールバックを使用してください。

コールバック	シグネチャ	用途
before_agent_callback	(CallbackContext)	状態を初期化する
before_tool_callback	(BaseTool, dict, CallbackContext) -> dict|None	入力を検証する
after_tool_callback	(BaseTool, dict, ToolContext, dict) -> dict|None	結果を後処理する
before_model_callback	(CallbackContext, LlmRequest)	レート制限、安全性

def before_tool(tool, args, tool_context) -> dict | None:
    if tool.name == "approve_discount" and args.get("value", 0) > 50:
        return {"status": "rejected", "reason": "Discount too large"}
    return None  # Proceed normally

---

構造化出力

型付けされ、検証済みのエージェント出力にはPydanticモデルを使用します。

from pydantic import BaseModel

class AnalysisResult(BaseModel):
    summary: str
    key_findings: list[str]
    confidence: float
    recommendations: list[str]

agent = LlmAgent(
    name="analyzer", model="gemini-flash-latest",
    instruction="Analyze the provided data and return structured results.",
    output_schema=AnalysisResult,
    output_key="analysis",
)

---

実行とテスト

pip install google-adk
export GOOGLE_API_KEY="your-key"
adk run my_agent          # Interactive CLI
adk web my_agent          # Web UI (includes Visual Builder)
adk api_server my_agent   # REST API server
adk create --type=config my_agent  # YAML-based agent

テスト

import pytest
from google.adk.runners import InMemoryRunner
from google.genai import types

@pytest.mark.asyncio
async def test_agent():
    runner = InMemoryRunner(agent=root_agent, app_name="test")
    session = await runner.session_service.create_session(
        user_id="test_user", app_name="test",
    )
    content = types.Content(
        role="user", parts=[types.Part.from_text(text="Hello")],
    )
    events = []
    async for event in runner.run_async(
        user_id="test_user", session_id=session.id, new_message=content,
    ):
        events.append(event)
    assert "expected" in events[-1].content.parts[0].text.lower()

評価

.test.jsonファイルで評価ケースを定義し、adk eval、pytest、またはWeb UIで実行します。ADK 2.2以降ではRubricBasedMultiTurnTrajectoryEvaluatorが追加されています。references/evaluation.mdを参照してください。

---

モデルの選択

組み込みのデフォルトはgemini-3.5-flashです。ドキュメントの例では、ローリングエイリアスgemini-flash-latestを使用しています。リージョナルエンドポイントでは、固定ID（例：gemini-3.6-flash、複雑な推論にはgemini-3.1-pro-preview）を使用してください。Gemini以外では、Claude、Ollama、LiteLLM、vLLM、OCI GenAIを利用できます。プロバイダーのプレフィックスが付いたGemini IDも使用できます（2.4以降）。generate_content_config=types.GenerateContentConfig(...)で設定します。temperature／top_p／top_kはGemini APIでは非推奨です。

---

設計パターン

パターン	使用する場面	ADK 2.0 での実装
グラフワークフロー	決定論的な複数ステップのプロセス	明示的な edges を使用した Workflow
動的ワークフロー	複雑な分岐や反復	@node と ctx.run_node() のコード
協調チーム	自律的に管理する専門家グループ	コーディネーターとモード付きの sub_agents
ファンアウト／ファンイン	独立した並列タスク	ParallelAgent または asyncio.gather
リフレクションループ	速度より品質を重視する場合	LoopAgent または動的ワークフロー内の while
動的ルーティング	入力に応じたハンドラーの選択	Workflow のエッジ内のルーター関数
段階的フォールバック	エラーからの適切な復旧	SequentialAgent：プライマリ -> フォールバック
ガードレール付きエージェント	安全性／コンプライアンスを適用する場合	before_model_callback と before_tool_callback
リソースの階層化	コストの最適化	エージェントごとに異なる model

主な設計ルール：

• 新規開発では、テンプレートワークフローよりグラフベースまたは動的ワークフローを優先してください。
• 5 つ以上のツールを持つエージェントは、専門分野ごとに分割してください。1 つのエージェントに 1 つの責任を持たせます。
• エージェント間でデータを渡すには、output_key と output_schema（Pydantic）を使用してください。自由形式のテキストには決して依存しないでください。
• 生成と評価は分離し、批評には別のエージェントを使用してください。
• サブエージェントの description フィールドは正確に記述してください。Auto-Flow のルーティング判断に使用されます。
• 推論ステップを指示に埋め込んでください：「1. 分析 2. 計画 3. 実行 4. 検証」。
• グラフのエッジには、入力が不明確な場合のフォールバックルートを含めてください。

関連項目：references/workflows.md（グラフルーティング、HITL、動的ループ） | references/advanced-patterns.md（Agent Config、デプロイ、AG-UI） | references/design-patterns.md（チェーン、リフレクション、計画） | references/a2a-protocol.md（A2A サーバー／クライアント） | references/memory-artifacts.md（メモリバックエンド、アーティファクト） | references/troubleshooting.md（デバッグ、1.x->2.0 の移行）。

---

選択ガイド

ワークフロータイプの選択については、上記のクイックリファレンス表を参照してください。ツールの種類：

Simple function? -> Python function with type hints
Need state access? -> Add ToolContext parameter
Delegate to another agent? -> AgentTool
Remote agent over network? -> RemoteA2aAgent
External MCP server? -> MCPToolset
REST API from spec? -> OpenAPIToolset
Database access? -> ToolboxToolset
Web search? -> google_search (built-in)
Cross-session memory? -> PreloadMemoryTool / LoadMemory
Modular skill package? -> SkillToolset

制限事項

グラフワークフロー：Live ストリーミングは非対応です。レガシーオーケストレーターはノードとして使用できません。チャットモードのエージェントは START からのみ使用できます。グラフ内のタスクモードには、2.5 以降の再開機能が必要です。全項目については、references/workflows.md を参照してください。

トラブルシューティング

セットアップ、ランタイム、A2A、MCP、セッション、および 1.x→2.0 の移行に関するエラー → 原因 → 修正のパターンについては、references/troubleshooting.md を参照してください。