adk-architecture

ADK Architecture Guide

Core Interfaces (references/interfaces/)

• BaseNode — node contract, output/streaming, state/routing, HITL, configuration
• Workflow — graph orchestration, dynamic nodes (tracking/dedup/resume), transitive dynamic nodes, interrupt propagation, design rules for node authors
• Runner — The public interface for executing workflows and agents. Documents entrance methods run and run_async.
• Agent — Blueprint defining identity, instructions, and tools. Documents that run is the preferred entrance method.
• BaseAgent — Base class for all agents. Defines the contract for subclassing with _run_impl as the primary override point.
• Event — Core data structure for state reconstruction and communication. Represents a conversation turn or action.

Key Principles (references/principles/)

• API Principles — stability, backward compatibility, and self-containment. Use when making design choices that affect the public API surface.

Runtime Knowledge (references/architecture/)

• Context — 1:1 node-context mapping, InvocationContext singleton, property reference
• NodeRunner — two communication channels, execution flow, output delegation. Internal runtime details.
• Runner Roles — Runner vs NodeRunner vs Workflow separation. Explains why they are separate to avoid deadlocks.
• Checkpoint and Resume — HITL lifecycle, rerun_on_resume, run_id
• Observability — span-on-Context design, NodeRunner integration, correlated logs, metrics
• LLM Context Orchestration — relationship between events and LLM context, task delegation translation, branch isolation. Use when modifying event processing, context preparation for LLMs, or debugging context pollution issues.