adk-architecture
Explains how the ADK runtime fits together: the node and graph execution model, Context and Event flow, checkpoint and resume, tracing, and the rules governing the public API surface. Use when answering "how does X work" about ADK internals, tracing where an event or a piece of state comes from, deciding where a new capability belongs, reviewing a change to BaseNode, Workflow, Runner, Agent, Event or Context, working out why a node re-ran or stayed waiting after a resume, or judging whether a change breaks the public API. Don't use for assembling an agent from existing pieces (use adk-agent-builder), diagnosing one failing run or test (use adk-debug), or formatting and naming conventions (use adk-style).
- License 许可
- MIT
- 最近更新
- 2026-10-08
- Stars
- ★ 11
- Forks
- 3
01 前言 Front Matter
- name
- adk-architecture
- description
- Explains how the ADK runtime fits together: the node and graph execution model, Context and Event flow, checkpoint and resume, tracing, and the rules governing the public API surface. Use when answering "how does X work" about ADK internals, tracing where an event or a piece of state comes from, deciding where a new capability belongs, reviewing a change to BaseNode, Workflow, Runner, Agent, Event or Context, working out why a node re-ran or stayed waiting after a resume, or judging whether a change breaks the public API. Don't use for assembling an agent from existing pieces (use adk-agent-builder), diagnosing one failing run or test (use adk-debug), or formatting and naming conventions (use adk-style).
02 资源文件 14
- 参考文档references/api-principles.md1.9 KB
- 参考文档references/architecture-checkpoint-resume.md2.6 KB
- 参考文档references/architecture-context.md4.2 KB
- 参考文档references/architecture-llm-context-orchestration.md1.9 KB
- 参考文档references/architecture-node-runner.md4.4 KB
- 参考文档references/architecture-observability.md3.6 KB
- 参考文档references/architecture-runner-roles.md452 B
- 参考文档references/architecture-workflow-resumability.md7.7 KB
- 参考文档references/interface-agent.md2.0 KB
- 参考文档references/interface-base-agent.md2.0 KB
- 参考文档references/interface-base-node.md4.9 KB
- 参考文档references/interface-event.md3.0 KB
- 参考文档references/interface-runner.md1.7 KB
- 参考文档references/interface-workflow.md12.6 KB
03 SKILL.md 正文
ADK 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 |
workflow/_dynamic_node_scheduler.py |
ReplayManager (resume scan) |
workflow/utils/_replay_manager.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 |
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.
04 同仓库更多 Skills
obsidian-clipper-template-creator
Guide for creating templates for the Obsidian Web Clipper. Use when you want to create a new clipping template, understand available variables, or format clipped content.
obsidian-clipper-template-creator
Guide for creating templates for the Obsidian Web Clipper. Use when you want to create a new clipping template, understand available variables, or format clipped content.
python-api
Programmatic Object-Detection-Metrics API guidance for BoundingBox, BoundingBoxes, Evaluator, enums, coordinate conversion, AP/mAP semantics, and source-style import diagnostics.
file-evaluation
Folder-based PASCAL VOC AP/mAP evaluation from ground-truth and detection text files.
object-detection-metrics
Guides legacy Object-Detection-Metrics PASCAL VOC AP/mAP evaluation from detection text folders and direct Python API classes.
nx-workspace-patterns
Configure and optimize Nx monorepo workspaces. Use when setting up Nx, configuring project boundaries, optimizing build caching, or implementing affected commands.