adk-architecture について
adk-architectureは、google-adkのエージェントとワークフローの構造を解説するリファレンススキルです。ランタイムの利用や拡張にあたり、実行、コンテキスト、イベント、再開動作、コード構成を理解するための情報を提供します。
主な機能
- 01ノードとワークフローの実行モデル
- 02RunnerとNodeRunnerの役割
- 03コンテキストとイベントのライフサイクル
- 04一時停止と再開の動作
- 05ソースモジュールの案内
活用シーン
- 01ワークフローによるノードのスケジュール方法を理解する
- 02呼び出し中の状態とイベントを追跡する
- 03再開可能な人間参加型フローを設計する
- 04ADKの実装モジュールを探す
インストール
コマンドをコピーしてターミナルで実行します。
$
npx skills add https:/インストール後、Claude Code で/adk-architectureを入力して読み込まれたか確認します。
同梱ファイル
SKILL.md と一緒にインストールされる参考資料やスクリプト。
references/api-principles.mdarchitecture-checkpoint-resume.mdarchitecture-context.mdarchitecture-llm-context-orchestration.mdarchitecture-node-runner.mdarchitecture-observability.mdarchitecture-runner-roles.mdarchitecture-workflow-resumability.mdinterface-agent.mdinterface-base-agent.mdinterface-base-node.mdinterface-event.mdinterface-runner.mdinterface-workflow.md詳細
ADK アーキテクチャ
ランタイムはノードのグラフです。BaseNode は実行単位です。
Workflow は、宣言されたエッジに沿ってほかのノードをスケジュールするノードです。
NodeRunner はノードをちょうど1つ実行します。Runner は呼び出しとセッションを管理します。エージェントもノードであり、BaseAgent は BaseNode を拡張します。
ノードは実行ごとの Context を介して親と通信し、生成する Event を介してセッションと通信します。これらは別々の2つのチャネルです。
ctx は結果を上位へ渡し、イベントは永続化とストリーミングを担います。
ここに記載されたシグネチャを頼りにする前に、ソースコードを読んでください。この説明は古くなることがありますが、コードは変わりません。以下のパスは src/google/adk/ からの相対パスです。
リファレンスを選ぶ
| 質問 | リファレンス |
|---|---|
| ノードに実装が必須のものは何ですか？何を生成できますか？どの設定フィールドがありますか？ | BaseNode |
| グラフはどのようにノードをスケジュールし、動的な子ノードの重複を排除し、中断を伝播しますか？ | Workflow |
| 呼び出し元はどのように呼び出しを開始しますか？ | Runner |
Agent とは何ですか？どのメソッドを呼び出せますか？ | Agent |
| エージェントをサブクラス化する場合、何をオーバーライドすればよいですか？ | BaseAgent |
Event には何が含まれ、そのライフサイクルについて何を前提にできますか？ | Event |
ノードは ctx から何を読み取り、何を書き込みますか？ | Context |
子 Context の作成、イベントへのタイムスタンプの付与、再試行、エラーの捕捉は、誰が行いますか？ | NodeRunner |
Runner、NodeRunner、Workflow が別々のものなのはなぜですか？ | Runner の役割 |
| 1つのノードで、human-in-the-loop の一時停止と再開はどのように機能しますか？ | チェックポイントと再開 |
ワークフロー全体は一時停止をどのように乗り越えますか？また、is_resumable によって何が変わりますか？ | ワークフローの再開可能性 |
| スパンはどのように作成され、どのような属性を持ちますか？ | 可観測性 |
| モデルが未加工のイベントログを参照しないのはなぜですか？ | LLM コンテキストのオーケストレーション |
| この変更は破壊的変更ですか？新しいエクスポートはどこに追加すればよいですか？ | API の原則 |
コードの配置場所
| 概念 | モジュール |
|---|---|
BaseNode、START | workflow/_base_node.py |
Workflow、_LoopState | workflow/_workflow.py |
Graph、エッジのコンパイル | workflow/_graph.py |
NodeRunner | workflow/_node_runner.py |
DynamicNodeScheduler、DynamicNodeState、DynamicNodeRun | workflow/_dynamic_node_scheduler.py |
ReplayManager（再開時のスキャン） | workflow/utils/_replay_manager.py |
check_interception（リプレイの早送り） | workflow/utils/_replay_interceptor.py |
NodeInterruptedError、NodeTimeoutError | workflow/_errors.py |
Context、ctx.run_node() | agents/context.py |
ReadonlyContext | agents/readonly_context.py |
InvocationContext | agents/invocation_context.py |
BaseAgent、LlmAgent（Agent の別名） | agents/base_agent.py、agents/llm_agent.py |
BaseLlmFlow、SingleFlow、AutoFlow、flows/llm_flows/ のサブパッケージ（context/、prompt/、tools/、extensions/、core/） | flows/llm_flows/ |
Event、NodeInfo | events/event.py |
EventActions | events/event_actions.py |
分岐パス（parent.child@1） | events/_branch_path.py |
ノードパス（wf@1/child@2） | events/_node_path_builder.py |
Runner、InMemoryRunner | runners.py |
LiveRequestQueue、LiveRequest | live/live_request_queue.py |
ノードスパン、TelemetryContext | telemetry/node_tracing.py |
ResumabilityConfig | apps/_configs.py |
workflow/ 以下のモジュール名にはすべて先頭にアンダースコアが付いています。これらの名前は内部用として扱ってください。メジャーバージョンの更新を伴わずに変更される可能性があるため、これらの変更が自動的に破壊的変更になるわけではありません。
コメント
Markdown 対応