About adk-architecture
adk-architecture is a reference skill describing the architecture of google-adk agents and workflows. It helps developers understand execution, context, events, resumability, and code organization before working with or extending the runtime.
Key features
- 01Node and workflow execution model
- 02Runner and NodeRunner roles
- 03Context and event lifecycles
- 04Pause and resume behavior
- 05Source module map
Use cases
- 01Understanding how a workflow schedules nodes
- 02Tracing state and events across an invocation
- 03Planning a resumable human-in-the-loop flow
- 04Locating ADK implementation modules
Install
Copy the command and run it in a terminal.
npx skills add https:/After installing, type/adk-architecturein Claude Code to confirm it loaded.
Bundled files
References and scripts installed along with 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.mdDetails
From the project READMEADK Architecture
The runtime is a graph of nodes. BaseNode is the unit of execution.
Workflow is a node that schedules other nodes along declared edges.
NodeRunner executes exactly one node. Runner owns the invocation and the
session. Agents are nodes too — BaseAgent extends BaseNode.
A node communicates with its parent through a per-execution Context, and
with the session through Events it yields. Those are two separate channels:
ctx carries the result upward, events carry persistence and streaming.
Read the source before relying on any signature here. These notes drift; the
code does not. Paths below are relative to src/google/adk/.
Pick a reference
| Question | Reference |
|---|---|
| What must a node implement? What may it yield? Which config fields exist? | BaseNode |
| How does the graph schedule nodes, dedup dynamic children, propagate interrupts? | Workflow |
| How does a caller start an invocation? | Runner |
What is Agent, and which methods do I call on it? | Agent |
| I am subclassing an agent — what do I override? | BaseAgent |
What is on an Event, and what may I assume about its lifetime? | Event |
What does a node read and write on ctx? | Context |
| Who creates the child Context, stamps events, retries, catches errors? | NodeRunner |
| Why are Runner, NodeRunner and Workflow three separate things? | Runner roles |
| How does a human-in-the-loop pause and resume work for one node? | Checkpoint and resume |
How does a whole workflow survive a pause, and what does is_resumable change? | Workflow resumability |
| How are spans created, and what attributes do they carry? | Observability |
| Why does the model not see the raw event log? | LLM context orchestration |
| Is this change a breaking change? Where does a new export belong? | API principles |
Where the code lives
| Concept | Module |
|---|---|
BaseNode, START | workflow/_base_node.py |
Workflow, _LoopState | workflow/_workflow.py |
Graph, edge compilation | workflow/_graph.py |
NodeRunner | workflow/_node_runner.py |
DynamicNodeScheduler, DynamicNodeState, DynamicNodeRun | workflow/_dynamic_node_scheduler.py |
ReplayManager (resume scan) | workflow/utils/_replay_manager.py |
check_interception (replay fast-forward) | 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 (aliased Agent) | agents/base_agent.py, agents/llm_agent.py |
BaseLlmFlow, SingleFlow, AutoFlow, flows/llm_flows/ subpackages (context/, prompt/, tools/, extensions/, core/) | flows/llm_flows/ |
Event, NodeInfo | events/event.py |
EventActions | events/event_actions.py |
Branch paths (parent.child@1) | events/_branch_path.py |
Node paths (wf@1/child@2) | events/_node_path_builder.py |
Runner, InMemoryRunner | runners.py |
LiveRequestQueue, LiveRequest | live/live_request_queue.py |
Node spans, TelemetryContext | telemetry/node_tracing.py |
ResumabilityConfig | apps/_configs.py |
Everything under workflow/ is a leading-underscore module. Treat those names
as internal — they can change without a major version bump, so a change there
is not automatically a breaking change.