
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).
- Installs
- 119
- Last 24h
- —
- Trending rank
- —
- Security
- Not audited
Install
Works with every agent the skills CLI supports.
npx skills add https://github.com/google/adk-python --skill adk-architecture- 01
Install
Run the command in your project. The CLI asks which agents to install for.
- 02
Describe the task
Ask your agent for something this skill covers. It loads adk-architecture automatically when relevant.
- 03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.
SKILL.md
The instructions your agent reads when the skill is triggered.
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, 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.
FAQ
What does the adk-architecture skill do?
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).
How do I install adk-architecture?
Run npx skills add https://github.com/google/adk-python --skill adk-architecture in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/adk-architecture/ (personal) or .claude/skills/adk-architecture/ (project).
Which AI agents can use adk-architecture?
Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.
Is adk-architecture safe to install?
No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.
Who maintains adk-architecture?
It is published by google in google/adk-python. It has 119 recorded installs.
More from google/adk-python
adk-agent-builder
google/adk-python
Builds ADK (Agent Development Kit) Python agents: LLM agents with tools, graph workflows of function and agent nodes, conditional routing, fan-out and join, schema-validated delegation between agents, human-in-the-loop pauses, and pytest coverage for all of it. Use when asked to create an agent or a workflow, add a tool to one, branch or loop between nodes, run steps in parallel, pause for user approval, or test an agent. Don't use for explaining how ADK works internally or designing its core components (use adk-architecture), for an agent that already runs but misbehaves (use adk-debug), for authoring a sample under contributing/ (use adk-sample-creator), or for naming, typing, and formatting conventions (use adk-style).
adk-debug
google/adk-python
Diagnoses misbehaving ADK agents by inspecting sessions, events, tool calls, and the exact request that reached the model. Covers the adk run CLI and the adk web dev server with its session, trace, and debug HTTP endpoints. Use when an agent returns the wrong answer, ignores a tool or swallows a tool error, hangs, loops, emits raw JSON instead of calling tools, is not discovered by adk web, when a sub-agent cannot see the parent conversation, or when you need the LLM request/response, token counts, or logs for a run. Don't use for how ADK is designed internally (use adk-architecture), for building a new agent or workflow (use adk-agent-builder), for environment or dependency setup failures (use adk-setup), or for lint and style nits (use adk-style).
adk-setup
google/adk-python
Sets up a local ADK Python development environment in a git clone of the open-source adk-python repository: a uv virtual environment, all dependency extras, pre-commit hooks, and a first unit-test run. Runs only when explicitly requested, never on its own. Use when asked to set up, bootstrap, or repair a development checkout, install project dependencies, fix a missing or broken .venv, or prepare a machine for contributing a pull request. Don't use for debugging a running agent (use adk-debug), for commit and pull-request mechanics (use adk-git), or for re-running formatters on a checkout that is already set up (pre-commit run --all-files).
adk-sample-creator
google/adk-python
Creates a new sample agent in the ADK Python repository — the sample directory, its agent.py, and its README.md — following the conventions the existing samples already use. Use when the user wants to add a sample or example demonstrating a feature or agent pattern (dynamic nodes, fan-out/fan-in, a standalone tool-using agent), asks where a new sample belongs under contributing/samples/, or wants an existing sample's README brought up to the standard structure. Don't use for building a real working agent for the user's own project (use adk-agent-builder), or for checking whether the Python blocks in a Markdown file run (use adk-verify-snippets).
adk-git
google/adk-python
Writes commit messages and pull request descriptions for the adk-python repository: Conventional Commits types and scopes, subject lines that say why a change was made, and the linked-issue and testing-plan sections the PR template requires. Use when writing or rewording a commit message, squashing commits before a pull request, drafting a PR description, or checking that a change is shaped to land. Don't use for generic git mechanics such as rebasing, resolving conflicts, cherry-picking, or branch surgery; those need no skill. Don't use to judge the content of a change (use adk-review) or for code style and naming (use adk-style).
Popular code quality & workflow skills
grill-me
mattpocock/skills
A relentless interview to sharpen a plan or design.
improve-codebase-architecture
mattpocock/skills
Scan a codebase for deepening opportunities, present them as a visual HTML report, then grill through whichever one you pick.
handoff
mattpocock/skills
Compact the current conversation into a handoff document for another agent to pick up.
domain-modeling
mattpocock/skills
Build and sharpen a project's domain model. Use when discussing codebase terminology, writing or editing a GLOSSARY.md, or recording or editing an ADR.
codebase-design
mattpocock/skills
Shared vocabulary for designing deep modules. Use when the user wants to design or improve a module's interface, find deepening opportunities, decide where a seam goes, make code more testable or AI-navigable, or when another skill needs the deep-module vocabulary.
diagnosing-bugs
mattpocock/skills
Diagnosis loop for hard bugs and performance regressions. Use when the user says "diagnose"/"debug this", or reports something broken/throwing/failing/slow.