Google ADK Architecture Reference

TL;DR

• Google ADK (Agent Development Kit) is a reference architecture for production agents where agents, tools, sessions, memory, evaluation, deployment, and integrations are treated as first-class system components.
• ADK is an open-source framework (Python, TypeScript, Go, Java, Kotlin) for building reliable AI agents at enterprise scale, from simple assistants to mission-critical multi-agent workflows.
• Core ADK concepts: Agent (reasoning unit with instructions and model), Tool (typed capability), Session (active thread and event history), State (mutable, current-thread data), Memory (searchable, persistent knowledge).
• Use ADK as a checklist even outside Google’s stack: define agent contracts, tools, session service, memory service, evals, tracing, logging, security gates, identity integration, data retention, and policy enforcement.
• ADK is most valuable as an architecture reference model; choose whether to deploy on ADK based on whether its runtime, languages, integrations, and operational model match your system.

Core Concepts

Google ADK and Enterprise Agent Architecture

Google ADK is a reference framework for agent development at enterprise scale. It treats core components (agents, tools, sessions, memory, evaluation, deployment) as first-class concepts, not afterthoughts. The framework encodes patterns from years of production agent usage: how to design agents (with clear contracts and instructions), how to structure tool integration (typed, validated, logged), how to manage conversation state and long-term memory (separate concerns), how to evaluate agent performance (offline and online), how to deploy safely (versioning, rollback, canary), and how to observe and debug (comprehensive tracing). Using ADK or not, the architecture concepts are applicable.

Agent as a Reasoning Unit

In ADK, an Agent is the core reasoning unit: it has instructions (system prompt, task strategy), a model (which model to use, parameters, temperature), available tools, and behavior policies (how to retry, when to escalate). An agent is not just a model; it is a model plus its configuration and context. Agents are versioned (agent-v1, agent-v2); a new agent version can have different instructions, different tools, or different behavior without changing the underlying model. This separation enables updating agent behavior without model retraining.

Tools as Typed, Integrated Capabilities

In ADK, a Tool is a typed, validated capability that an agent can invoke. Tools are not arbitrary bash commands or broad APIs; they are narrow, named functions with typed inputs and outputs. A tool includes: a name (“query_support_tickets”), a description (what does it do?), input schema (what arguments does it accept, and what are their types?), and output schema (what does it return?). The agent learns about tools from their descriptions and decides when to invoke them. Tools are executed by the harness (not the model), validated, and logged. ADK provides tool registration mechanisms; tools can be built-in (part of the framework) or custom (specific to the application).

Session as Active Conversation Thread

In ADK, a Session is the active conversation thread: the user’s messages, the agent’s responses, the interaction history. A session has an ID (for lookup and replay), a creation timestamp, participants (user, agent, any observers), and event history (messages, tool calls, decisions). Sessions are persisted in a session store (database, cloud storage) and are queryable (retrieve session by ID, by user, by date range). Sessions enable conversation continuity (the agent can look back at prior messages in the same session) and audit (what happened in this conversation?).

State as Mutable, Current-Thread Data

In ADK, State is mutable, current-thread data: variables set during the conversation (“the user’s account ID is 12345”), flags (“the user has verified identity”), or intermediate results (“the last query returned X”). State is distinct from session history; it is not meant to be immutable or audited in the same way. State is ephemeral (cleared at the end of the session, or cleared explicitly). State is useful for loops where the agent needs to remember something within the conversation (a decision point, a retrieved value) without storing it long-term.

Memory as Persistent, Searchable Knowledge

In ADK, Memory is persistent, searchable knowledge beyond the immediate conversation: user preferences (from prior conversations), learned facts about the user (they prefer email over SMS), external knowledge (company policies, documentation). Memory is distinct from session state; it persists across sessions. Memory is searchable (retrieve memories related to this query), not just sequential (this conversation from start to end). Memory can have a retention policy (delete old memories after 90 days) and can be user-scoped (memories about this user) or organization-scoped (shared knowledge).

Tool Integration and Lifecycle

ADK provides abstractions for tool registration, invocation, and error handling. Tools are registered with the agent at configuration time or dynamically. When an agent decides to call a tool, the harness invokes the tool, validates the arguments, executes the tool (with the tool’s own credentials/permissions), and returns the result or error. The harness handles timeouts (if a tool takes too long), retries (if transient error), and circuit breaking (if the tool is down, stop calling it). Errors from tools are structured (error code, message) so the agent can understand what went wrong and potentially retry or escalate.

Evaluation Framework

ADK includes patterns for evaluation: defining golden tasks (ideal inputs and outputs), running agents against golden tasks, measuring success (did the agent produce the right output?), and tracking metrics over time. Evaluation is offline (before deploying a new agent or tool) and online (monitoring production agents). Metrics include success rate (what % of tasks were completed correctly), latency (how long did each task take), cost (how many tokens, how many tool calls), and user satisfaction (ratings, feedback).

Deployment and Versioning

ADK treats deployment as a core concern. Agents, prompts, tools, and models are all versioned. A deployment pins versions: use agent-v3, system-prompt-v5, with tools: { query_db-v2, send_email-v1 }, model: claude-opus-4-20250704. Deploying a new version is explicit (not implicit, not automatic). Rollback is supported: if a deployment causes problems, revert to the prior version. Canary deployments are possible: route some traffic to the new version, monitor for problems, then switch all traffic.

Tracing and Observability

ADK includes comprehensive tracing: every message, every model call, every tool invocation, every decision is logged with timestamp, actor (which agent?), action (what happened?), and result. Traces are structured (not free-form prose) and queryable. Observability dashboards show: success rate over time, latency distribution, cost per agent, tool error rates, and user sentiment. Tracing is essential for debugging (why did this agent make this decision?) and for compliance (audit trail).

Identity and Multi-Tenancy

ADK assumes enterprise multi-tenancy: multiple users or organizations, each with isolated sessions, state, memory, and tool access. Identity is federated (SAML, OIDC, corporate directory) and is not managed by ADK directly; instead, ADK assumes identity is provided by the platform (Vertex AI, custom deployment). Permissions are expressed per tool and per user (user A can call tool X, user B cannot). Data isolation is enforced: user A’s memory and session data are not visible to user B.

ADK Component Architecture

Mapping ADK to Non-Google Implementations

Common Pitfalls

• Pitfall: Treating a model response as a system boundary. Why: the model can be manipulated via prompt injection, jailbreaks, or simple misunderstanding; it is not an access-control layer. Fix: enforce policies at the tool boundary and harness level; do not rely on the model to decide what tools to call or respect boundaries.
• Pitfall: Shipping an agent without replayable traces and eval baselines. Why: without traces, it is impossible to debug failures or investigate unexpected behavior; without baselines, it is impossible to detect regression. Fix: log every step, version all components, maintain eval suite with golden tasks, measure before and after each change.
• Pitfall: Letting retrieved content act like trusted instructions. Why: retrieved documents can be stale, misleading, or contradict policy; the model might over-weight them. Fix: mark retrieved content as information, include explicit system instruction that policy takes precedence, audit retrieved content for policy conflicts.
• Pitfall: Giving tools broad credentials because the prototype worked. Why: a prototype might work in a lab; production requires narrow scopes, validation, and audit logs. Fix: give tools only minimum credentials needed, require server-side argument validation, log all tool calls, require human approval for high-impact actions.
• Pitfall: Confusing agent versioning with model versioning. Why: they are independent; a new agent version might use the same model with different instructions; a new model might be used by the same agent with the same instructions. Fix: version agents and models separately; test agent changes and model changes independently before combining them.