Glossary
The ADK is opinionated, so its vocabulary is too. These are the words the docs use as if you already know them — the concepts and coined terms that carry the architecture. Raw API types (MediaReader, SpoolReader, every field and enum) live in the API reference, not here; this page is the mental model, not the type signatures.
Terms are written as nouns — "turn runner", "trust tier" — because that is how you think about them. When a specific API type is the thing you'd reach for in code, it appears as a code symbol (TurnRunner, Retrievable) linked to its reference. The noun is the concept; the symbol is its implementation. That split is deliberate; do not "correct" one into the other.
Definitions take a position. If one of them annoys you, that is the design talking, and the page that owns the rationale is linked from the term.
The execution loop
Turn
One end-to-end agent request: input arrives, middleware shapes it, dispatch may call the model several times, state gets persisted, the runner resolves. The whole unit of work — not the model call. A turn is not a chat session; it is one execution unit inside whatever conversation loop your product owns. See The Loop.
Dispatch
The model-execution cycle inside a turn: the loop that calls the executor, chases tool calls, and exits only on a terminal signal or abort. The ADK supplies the loop; you supply the stopping logic, because infinite loops are still bad. The executor's contract is the DispatchExecutorFn, and it reads a DispatchContext. See LLM dispatch.
Iteration
One trip through the dispatch loop: dispatch-input middleware → executor → dispatch-output middleware. Tool results become useful across the boundary — iteration N persists a tool result, iteration N+1 shows it back to the model.
Harness
The deterministic structure around the agent — the turn runner, contexts, pipelines, validation, event buses, and lifecycle signals. The harness runs the loop; it does not decide behavior. The ADK is the harness; the agent is yours.
Turn runner
The bookkeeper for one turn, not the agent hiding behind the curtain. TurnRunner validates config eagerly, threads a fresh context through middleware and dispatch, emits events, and refuses to invent behavior you did not wire. It returns nothing — everything leaves through the event buses. See Turn Runner.
Executor seam
The hard boundary where ADK stops and your model integration begins. The runner invokes one callback per iteration and judges only what it streams, persists, and signals; provider plumbing is your problem — mercifully and dangerously. Your model client stays yours. See Bring your own LLM.
Ack
ctx.ack() — the executor's "this dispatch succeeded, stop here" signal. One of the three terminal outcomes of signalling; see also the ack/nack invariant. The opposite verdict is nack.
Nack
ctx.nack(error) — the executor's "this dispatch failed" signal, carrying the error that should propagate instead of a silent stall. The failure counterpart to ack; both are governed by signalling and the ack/nack invariant. A nack is a reported failure, not an abort — abort is deliberate, nack is something going wrong.
Signalling
The contract that terminates a dispatch: ack, nack, or abort. Deliberately not silently idempotent — two seams each claiming the final word is a bug wearing a race-condition hat. See Signalling.
Ack/nack invariant
ADK's terminal-signal law: every executor invocation must call exactly one of ctx.ack() or ctx.nack(error), exactly once. Ignore it and you get infinite loops, double-signal explosions, or failures that vanish instead of propagating. The invariant is absolute. See Bring your own LLM.
Abort
Intentional cancellation or refusal — not an error. It short-circuits the relevant path and emits nothing on the error bus. Use it when middleware means "stop, on purpose"; reaching for an exception instead is how you make a clean cancellation look like a crash. See Abort.
Pipelines and middleware
Pipeline
An ordered sequence of middleware that transforms a shared context. In ADK these sequences are the agent's behavior surface — the runner walks them in order, and that walking is the runtime. No hidden guardian angel runs behind them. See Pipelines.
Middleware
A function handed a context and a next continuation, owning both its pre-step (before next) and post-step (after). Not a lifecycle hook, not a decorative callback — it is where retrieval, policy, budgets, cleanup, and most actual behavior live.
Turn-scoped pipelines
The once-per-turn bookends: turnInputPipeline before dispatch, turnOutputPipeline after a successful dispatch. Retrieval, history packing, and memory updates belong here so they do not accidentally run once per model iteration.
Dispatch-scoped pipelines
The per-iteration sandwich around the executor: dispatchInputPipeline and dispatchOutputPipeline. Put loop bounds, retry shaping, and repetition detection here — and put retrieval here only if you enjoy paying the same bill ten times.
Pipeline short-circuit
What happens when middleware returns without calling next() and without aborting. ADK reports it as a bug (E_PIPELINE_SHORT_CIRCUITED), because intentional refusal already has its own channel: abort. See Composition.
Stash
The sanctioned scratchpad for cross-middleware state inside one context. Deliberately unschemed — flexible enough for strangers' middleware to cooperate, sharp enough to cut you if you do not namespace your keys. See Stash.
Context hydration
The explicit act of fetching messages, memories, retrievables, tools, and instructions into the turn context. ADK does not do it for you; an empty turnInputPipeline is a perfectly valid way to build a confident idiot. See Assembly → pipelines.
Helpers vs persistence
Two decoupled concerns inside the executor: helper methods stream the wire shape (for the UI); ctx.store* writes the canonical record (for durable history). They are kept apart because a UI delta and an agent's memory are not the same thing — call the helper without the store and you get a ghost message the user saw but storage never did. See Inside one turn.
Trust and safety
Trust tier
A structural provenance label for content — not a vibe check on whether the prose sounds safe. Trust tiers exist so the renderer can keep developer authority, user data, tool output, and retrieved material from collapsing into one undifferentiated prompt soup. Declared at the source; the battery uses it to pick the envelope. See Trust Tiers.
Envelope
The prompt-rendering discipline that wraps content in authority-specific XML boundaries, with hostile content closed by an unguessable nonce-keyed tag. It exists because asking the model to politely ignore injected instructions is not a security boundary — it is theater with a tokenizer. See Envelopes.
Tag escape attack
Hostile content that includes a forged closing tag (</trusted_content>) to break out of its envelope and run with the surrounding authority — the SQL injection of the agentic era. Nonce-keyed closing tags are the structural fix; a content-derived id is not a nonce. See Envelopes.
Prompt injection
The attack the entire trust-tier system exists to blunt: untrusted input carrying instructions the model follows as if they were yours. The defense is structural — declare provenance, render untrusted content fenced — and mis-declaring a trust tier is an immediate vulnerability, not a style nit. See Bring your own retrieval.
Memory poisoning
A delayed prompt injection: hostile content stored now, detonating when it is recalled later. Persistence turns yesterday's attacker into today's invisible co-author — you step on the landmine months after they walked away. See Persistence.
Reasoning fence
A nonce-keyed boundary around thought records that stops an attacker from ending a reasoning trace and inserting their own. It treats chain-of-thought as a control surface, because that is exactly what it is — own the model's reasoning and you own its decisions. See Identity and reasoning.
Multi-identity
The two-channel rendering of participant identity: a sanitized structural channel for the provider API, and verbatim identity inside a bounded content envelope for the model. It exists because an identity string is both operational metadata and attacker-controlled text — and one channel cannot safely be both. See Identity and reasoning.
Modality hazard
The second trust axis for media: not where the bytes came from, but how instructions might be hidden in or extracted from them. Text has one read path; media has OCR, ASR, vision encoders, and embedded text — plenty of places for trouble to squat. Orthogonal to provenance, and required at construction. See Media trust.
Trusted Courier Fallacy
The mistake of assuming output is safe because it arrived through a trusted tool. Delivery fidelity is not semantic safety — a trusted tool that fetches a stranger's web page still hands you third-party content. The courier's integrity does not launder the payload. See Media research.
Retrieval, memory, and budgets
Synthetic RAG
Giving a model retrieval behavior by injecting precomputed retrievable records into context through middleware — no tool-calling required. RAG as prompt architecture, not as a tool-calling talent show. It is how a tool-less small model can still answer from a corpus. The pattern and its trust rationale live in Trust Tiers; for the whole thing built end-to-end on a 3B model, see the Ask ADK showcase.
Synthetic chain-of-thought
Precomputed reasoning injected into context as thought records, letting a fast model continue from expensive reasoning it never performed. The trick is only safe because the injected reasoning stays inside a reasoning fence. See Trust Tiers.
RAG
Retrieval-Augmented Generation: staging external documents into the context before dispatch so the model answers from a prepared corpus rather than memorized weights. In ADK, retrieval belongs in the turn-scoped input pipeline — it runs once per turn, not once per iteration — and every retrievable carries a trust tier.
HyDE
A hypothetical-answer retrieval trick (Hypothetical Document Embeddings): generate a fake answer and embed that to widen semantic recall. The generated text is bait for the embedding space, not evidence — in Ask ADK it seeds a cosine lane and gets no vote in lexical ranking.
Sufficiency floor
A coded relevance threshold below which retrieved chunks are deemed too weak to answer from. Below it, the system refuses deterministically rather than handing the model tangential scraps and asking it nicely not to make things up. See Ask ADK.
Abstain
A deliberate refusal to answer when the sufficiency floor is not cleared. In Ask ADK the model's output is never used on the abstain path — a refusal is assembled in code, naming the closest pages as links — because the moment of lowest evidence is exactly when a generator is most tempted to invent.
Token-Thrift
Ask ADK's RAG-first budgeting policy for a hard 4096-token window: measure the prompt cost once, give retrieval the largest useful allocation, and shed low-priority context instead of pretending the window is elastic. The window is a compiled ceiling, not a preference knob. It is one concrete shedding policy built on the general context window budget primitives; the Ask ADK showcase builds it end-to-end, Budgets covers the primitives underneath.
Context window budget
The model-visible content you can afford in one dispatch. A budget, not a wish. ADK primitives are built so large content can be referenced, queried, or spooled instead of shoved wholesale into the next call — and Tokenizable makes the cost measurable before you spend it. See Budgets.
Primitives
The eight validated data shapes the ADK threads through every turn. The entries below define the concept; field-level contracts live in the API reference and the per-primitive pages under Primitives.
Tokenizable
The text concept that makes token cost estimable instead of pretending strings are free. Every prompt-adjacent field is a Tokenizable so budget decisions can be made locally, without a remote call. See Tokenizable.
Message
One unit of dialogue, attributed to a speaker — exactly two roles, user and assistant. A Message is not a system or tool record. Tool results and RAG context are not messages; shoving them into a user role nukes the trust boundary and turns your data into a privilege-escalation vector. See Message.
Memory
Long-term context: what was learned or decided in previous conversations that should still inform this one. ADK defines the Memory primitive and the retrieval/storage contracts; it does not decide where memories live, how they are ranked, or when they are forgotten — the retrieval middleware sets the scores at query time. See Memory.
Retrievable
Fresh external context pulled in for this turn: RAG chunks, web results, KB snippets, uploaded-document passages. A Retrievable is not memory. It must declare a trust tier before the executor is asked to trust it — there is no unknown tier and no safe default. See Retrievable.
Thought
Reasoning kept separate from dialogue. A Thought exists because reasoning has different authority, replay behavior, and compaction value than something the assistant actually said to the user — and because it needs its own reasoning fence. See Thought.
Media
A typed handle to a binary asset — image, audio, video, document — that rides on messages and tool results without inlining bytes into a string. Media keeps bytes lazy; the renderer reaches into the asset only at the wrap site. It carries a required two-axis trust pair: provenance (trust tier) and modality hazard. See Media.
Tool call
A request for a tool invocation plus its eventual result, bound by a stable checksum so the loop can detect repetition and tie output to the call that produced it. Persisted ToolCall records are the audit trail and the model-visible history your tool loop needs. See ToolCall.
Tools and artifacts
Tool
A validated callable capability offered to the model: name, description, input schema, and handler, with the schema as the single source of truth for the contract. A Tool has its arguments validated and downstream errors wrapped by ADK; you decide which tools exist and how their results are handled. See Tools.
Trusted tool
A tool marked trusted: true, whose string/artifact results render in the trusted envelope. The flag describes delivery, not the safety of whatever the tool fetched — see the Trusted Courier Fallacy — and it is not consulted for media results, which always carry their own trust. See Trust and safety.
Ephemeral tool
A one-dispatch capability, usually forged around a specific artifact handle. If it survives past its dispatch the model sees stale handles, so the registry prunes it on ack. See bindContext and describe.
Artifact
The ADK's answer to a tool that produces more output than belongs in a context window: a produced result with identity that can be inspected without pretending it is just another string in the prompt. Small results inline; serious ones get a handle. See Artifacts.
Spooled artifact
An artifact backed by a re-openable reader instead of an eagerly held body. SpooledArtifact gives the model a query surface — head, tail, grep, range reads — so large outputs stay out of both process memory and the context window until a specific slice is actually needed. See Artifacts.
Boundaries and integration
Bring Your Own Everything
The architectural contract. Bring your own model provider, API client, persistence layer, vector index, queue, auth, telemetry, prompt format, tool-calling protocol, and deployment environment. ADK supplies the boundaries so those choices stay explicit instead of buried inside an adapter. See What ADK is.
Battery
An opt-in prebuilt integration — an LLM adapter, a storage spool, a tool collection — not a default behavior. Batteries save wiring when they fit; ADK will not secretly load one just because your app would be nicer if it did. Importing one (and its peer dependency) is always your explicit choice. See Assembly.
Gate
ADK's cooperative suspension point for safety, authorization, and human oversight: open a TurnGate with ctx.waitFor(gate) and the pipeline pauses until something external settles it. It pauses exactly the scope where you open it — which is why placing it in the wrong pipeline is not a small mistake. Every human-in-the-loop and approval flow attaches here. See Gates.
Standing instruction
A persistent operational rule loaded into every future turn — developer-, operator-, or model-updated. It has a far larger blast radius than ordinary memory: a wrong memory costs a few ignored tokens, a wrong standing instruction becomes policy forever. That asymmetry is why writing one is gated and writing a memory is not. See Persistence.
Functional bus
The event interface for things that are part of product behavior: streamed messages, thoughts, tool calls. The test is simple — if removing the listener changes what the agent does or shows, it belongs here. See Events.
Observability bus
The event interface for instrumentation: turn/dispatch/iteration lifecycle, gate and tool execution events, errors-as-telemetry. If an observer decides product behavior, you have wired a feature to your telemetry by mistake. See Events.