GoogleAI · ADK 2.0 · Migration checklist

ADK 2.0 Migration Checklist: Upgrade Agents Without Breaking Sessions, Callbacks, or Retries

ADK 2.0 changes the mental model from “an agent runs tools” to “a workflow graph coordinates nodes.” That is powerful, but it also creates migration traps. This guide explains what to check before upgrading Google ADK agents, especially event schemas, custom session storage, callbacks, retry behavior, human approval pauses, and Go module paths.

AFD

AI Feature Drop Editorial
Practical AI product research, developer workflow testing, and source-based feature analysis for aifeaturedrop.com.

Jump to: Quick answerWhy this topicWhat changedPreflight checklistSessionsCallbacksRetries and HITLPython and GoMigration planFAQ

Quick Answer: What Should You Check Before Migrating to ADK 2.0?

Before migrating to ADK 2.0, check your event schema, custom session storage, callback hooks, direct event appends, retry handling, human-in-the-loop interruptions, and language-specific upgrade paths. ADK 2.0 introduces a workflow runtime where agents, tools, and functions run as nodes in a graph. That shift improves control and reliability, but it can break code that assumed an older agent executor model.

The riskiest upgrade path is not a simple demo agent. It is a production-ish agent with custom SQL or NoSQL session storage, strict JSON validators, custom telemetry injected through old execution overrides, manual session event mutation, broad exception handling inside tools, or Go imports pinned to the earlier major module path. Those systems may keep compiling while silently losing observability, retries, or routing guarantees.

Best first move: do not upgrade every agent at once. Create one isolated ADK 2.0 workflow that mirrors a real production path, run it against copied session data, inspect emitted events, validate retries and human approval pauses, then migrate one service boundary at a time.

This cluster article supports our broader pillar, Google ADK Workflows Guide. The pillar explains why ADK workflows matter and how graph, dynamic, and collaborative workflows fit production AI agents. This guide is narrower: it is the practical migration checklist for teams who already have ADK agents and need to upgrade without breaking state, callbacks, or reliability behavior.

Why This Is a Strong Search-Gap Topic for AI Feature Drop

AIFeatureDrop’s latest analytics show that practical developer workflow explainers are the site’s strongest pattern. During the last complete 28-day window ending July 17, GA4 reported 378 active users, 492 sessions, 757 page views, and Organic Search as the leading acquisition channel by sessions. The top pages were not generic AI news posts. They were practical explainers around Codex usage limits, OpenAI Codex pricing, Google Flow and Veo credits, GitHub Copilot AI Credits, and coding-agent setup issues.

That matters for topic selection. A broad post called “What is ADK 2.0?” would compete with official docs and duplicate the site’s existing pillar. A checklist article matches the site’s proven intent pattern: developers arrive with a specific risk, limit, setup problem, or workflow decision. Search Console data is still sparse for the new property, but the available impressions lean toward narrow, implementation-style queries such as permissions, setup, and coding-agent workflows. The opportunity is to publish a source-grounded answer before the SERP fills with generic summaries.

Feature research also supports the angle. Google’s official ADK 2.0 material highlights a structured workflow runtime, graph-based workflows, dynamic workflows, collaborative workflows, Python general availability, Go general availability, event schema changes, BaseAgent-to-BaseNode execution changes, callback migration, automatic retries, and human-in-the-loop pauses. That is a lot for one official page. Developers need a practical translation: what breaks, what to test, and what to migrate first.

The content gap is especially clear because official docs explain the changes, while many early writeups focus on the upside: deterministic workflows, fewer infinite loops, cleaner orchestration, and better control. Those benefits are real, but teams also need the uncomfortable checklist. If custom session storage rejects new fields, if telemetry lives in a bypassed override, or if a tool catches the wrong exception, a migration can look successful while operational behavior gets worse. That is the gap this cluster article fills.

What Actually Changed in ADK 2.0?

ADK 2.0 introduces a workflow runtime that treats agents, tools, and functions as workflow nodes. In older mental models, an agent was often the main executor: it saw instructions, selected tools, received outputs, and decided what came next. In the new workflow-first model, routing can be handled by the graph. The model still reasons where language reasoning is useful, but deterministic code can own order, branching, retries, approval gates, and outputs.

Google’s developer blog frames the reason clearly: model-only orchestration can be flexible, but business processes often require exact execution. If step B must follow step A, there is no reason to spend tokens asking a model to rediscover that route. Workflows separate execution routing from language processing. You can compose deterministic tool calls, LLM nodes, specialized agents, and human approval steps in one structure.

That architecture shift is the source of the migration risk. ADK 2.0 is not merely “new syntax.” The official ADK 2.0 docs say the runtime transitions ADK from a hierarchical agent executor to a graph-based execution engine. They also call out new event fields, BaseAgent becoming part of the BaseNode model, callback behavior changes, automatic retry behavior, human-in-the-loop pauses, and Go module import changes. If your current app is a toy, the upgrade may be straightforward. If your current app has production state, UI clients, custom storage, or observability, it needs a real migration plan.

Area	What changed	Migration risk	What to test
Event schema	Events include graph-related fields such as node_info and output.	Rigid databases or strict JSON clients may reject new payloads.	Insert, read, replay, and validate copied 2.0 events before production writes.
Execution model	Agents are evaluated as nodes inside a workflow graph.	Old execution overrides may be bypassed.	Confirm telemetry, state updates, and custom logic still fire.
Callbacks	Standard before/after callback interfaces become the safer extension point.	Custom run overrides can silently stop controlling behavior.	Move lifecycle logic into supported callbacks and assert it runs.
Event mutation	The workflow runner needs control over event emission.	Manual session event appends can break determinism.	Replace direct appends with yielded events managed by the framework.
Error handling	The framework can catch exceptions for retries, telemetry, and HITL pauses.	Broad catches inside tools may block retries or approval flows.	Test failed tools, retry paths, approval pauses, and final error states.
Go upgrade	Go 2.0 uses a new major module path and changed interfaces.	Imports and event constructors may fail or behave differently.	Upgrade a branch, fix imports, and run contract tests around events.

The ADK 2.0 Preflight Checklist

Use this checklist before touching production. It is intentionally more operational than theoretical. A migration plan should tell you where state lives, who reads events, which hooks inject behavior, which tools recover from failures, and how you will know the new graph runtime is behaving correctly.

Inventory agentsList every ADK agent, its tools, model, deployment path, owner, traffic level, and whether it touches production data.

Map sessionsIdentify every session store, event table, replay pipeline, analytics consumer, UI client, and schema validator that reads ADK events.

Find overridesSearch for custom run methods, generation overrides, monkey patches, telemetry wrappers, direct session mutation, and manual event appends.

Classify toolsMark tools that call external APIs, mutate data, require approval, perform retries, or catch exceptions broadly.

Define a canaryChoose one representative workflow with real branching, one tool failure, one LLM node, and one approval-like pause.

Set rollback rulesDecide what failure rate, schema error, missing callback, or retry mismatch triggers rollback.

The goal is not to create paperwork. The goal is to discover hidden dependencies. A production agent usually has more consumers than its main codebase. A frontend may validate event JSON. A metrics job may expect a specific event shape. A customer-support dashboard may render tool outputs. A replay script may assume events are append-only in a particular format. Those dependencies need to learn the ADK 2.0 shape before your live workflow starts writing it.

Red flag: if you cannot answer “who reads our ADK events?” then you are not ready to migrate the shared session store. Start with an isolated store or a copied dataset.

Also decide whether you are doing a compatibility upgrade or an architecture upgrade. A compatibility upgrade tries to keep existing behavior while moving to ADK 2.0. An architecture upgrade redesigns the agent as a graph or dynamic workflow. Mixing both at once is tempting, but risky. For critical apps, first prove the new runtime can preserve required behavior. Then redesign the workflow structure in a second phase.

Session Storage and Event Schema: The Most Common Migration Trap

The official ADK 2.0 docs call out new event fields such as node_info and output. That sounds small until you remember how many systems treat event payloads as contracts. If your session storage keeps JSON blobs, the migration may be easier. If your storage maps every event field into rigid SQL columns, or if downstream clients reject additional properties, ADK 2.0 events can fail at insertion, deserialization, or frontend validation.

Start by copying a representative session dataset into a staging environment. Then run a new ADK 2.0 workflow and compare old and new events. Do not only check that the agent produced a final answer. Check whether events can be stored, loaded, listed, streamed, filtered, replayed, and displayed. If your UI shows a timeline, make sure graph node data does not break rendering. If your analytics pipeline counts tool calls, make sure it can still identify tool nodes. If your audit system extracts outputs, decide whether it should use the new output field directly.

Questions to ask your storage layer

• Does the event table allow extra fields, or does every field need a migration?
• Do ORM models reject unknown properties?
• Do mobile clients or web clients use strict JSON schema validation?
• Do replay tools assume events came from a hierarchical executor rather than a workflow graph?
• Do compliance logs need to capture node_info for auditability?
• Are events shared across 1.x and 2.0 services during the transition?

If you use shared storage, avoid writing ADK 2.0 events until all readers can tolerate the new shape. One safe pattern is dual-read readiness: update readers first so they accept both old and new fields, then start writing 2.0 events from one canary workflow. Another pattern is store isolation: run ADK 2.0 workflows in a new namespace or table until the migration proves stable. Which one is better depends on your product, but both are safer than writing new events into a rigid old pipeline and hoping no consumer breaks.

Callbacks and Custom Execution: Where Silent Breakage Happens

ADK 2.0 changes how agents participate in execution. The docs explain that agents are now evaluated as nodes within the workflow graph engine. That matters if your current project injected custom behavior through older execution overrides. A custom method may still exist in your codebase, but the workflow runner may not call it the way your 1.x architecture expected.

This is the kind of bug that passes superficial tests. The agent answers. The tool runs. The demo looks fine. But your telemetry did not fire, your state marker did not update, your billing meter did not record usage, or your compliance breadcrumb never appeared. Because the user-facing answer looks correct, the team may not notice until operations data is missing.

The safer migration is to move lifecycle behavior into supported callback interfaces such as before-agent and after-agent callbacks. Treat callbacks as explicit extension points, not as incidental hooks hidden in custom run logic. Then write tests that assert the callback ran. Do not only assert the final agent response. Assert the side effect: a metric was recorded, a trace attribute appeared, a state value changed, or an audit record was created.

Callback migration checklist

Old pattern to find	Why it is risky	Safer ADK 2.0 pattern
Custom agent run overrides	The graph runtime can bypass legacy execution paths.	Move lifecycle logic into standardized callbacks.
Telemetry wrapped around generation methods	Generation may no longer be the only unit of execution.	Instrument node execution and workflow-level events.
Manual state mutation inside overrides	State changes may not align with graph routing.	Use framework-managed context, callbacks, and yielded events.
Assuming one agent owns the whole task	Collaborative workflows split responsibility across nodes.	Track node-level ownership and workflow-level outputs.

Good migration tests should be annoyingly specific. “The answer contains the expected string” is not enough. Add assertions such as “before callback ran exactly once for this node,” “after callback records token estimate,” “trace includes workflow ID and node name,” “state update appears before approval pause,” and “error callback fires when the payment tool fails.” That specificity turns hidden migration risk into visible behavior.

Retries, Exceptions, and Human Approval Pauses

ADK 2.0 adds framework-level behavior around automatic retries, telemetry, and human-in-the-loop pauses. That is useful, but it can conflict with older tool code that swallowed exceptions to keep an agent alive. Many teams wrote broad try...except blocks inside tools because earlier systems did not have enough native retry support. In a workflow runtime, that defensive pattern can become harmful.

If a tool catches every exception and returns a vague string like “something went wrong,” the workflow may not see a failure that should trigger retry logic. If a human approval pause is represented through a special exception or framework signal, a broad catch can accidentally hide it. If a tool mutates external state and then raises after the mutation, careless retry behavior can duplicate work. Migration is the moment to classify tool failures properly.

Let the workflow see

• Transient API failures that should retry.
• Rate limits that should back off or route differently.
• Human approval pauses that should interrupt cleanly.
• Validation failures that should stop the workflow.
• Tool errors that need telemetry and audit visibility.

Do not hide

• All exceptions behind a generic success-like string.
• Approval interrupts inside broad catch blocks.
• External side effects without idempotency keys.
• Payment, account, or deletion actions without confirmation gates.
• Repeated retries on non-retryable validation errors.

For every tool, define three categories: retryable failures, non-retryable failures, and approval-required pauses. Retryable failures include temporary network errors, 429 responses, or service unavailability. Non-retryable failures include invalid input, missing permission, unsupported account state, or policy denial. Approval-required pauses include refunds above a threshold, data exports, destructive edits, external sends, and any action where a human should confirm before the workflow continues.

Then test each category. Create a fake tool failure. Confirm the workflow retries when it should. Confirm it stops when it should. Confirm approval pauses are visible to the user or operator. Confirm telemetry records the reason. Confirm no external action is duplicated during retry. This is not glamorous, but it is where production reliability comes from.

Python and Go Migration Notes

ADK 2.0 is available for Python and Go, but the practical upgrade concerns differ slightly. Python teams usually need to focus on event storage, callback migration, context handling, custom session services, and tool exception behavior. Go teams need to focus on the new major module import path, interface changes, event construction changes, and session schema compatibility.

For Python, the biggest risk is assuming that old execution customization still controls the runtime. If you previously overrode internal methods to inject logic, move that logic to supported callbacks and test it. If you manually appended events to sessions, replace that with framework-managed event emission. If custom session storage uses rigid columns, add support for the new event fields before writing 2.0 sessions. If tool code has broad exception handling, narrow it so the runtime can manage retries and approval pauses.

For Go, treat the upgrade like a real major version migration. Update imports in a branch, fix changed interfaces, update event construction calls, and run contract tests around session events. Do not upgrade the module path and immediately deploy to a shared event store. First confirm that every reader of Go-generated events can tolerate the 2.0 shape. If your organization has both Python and Go agents, coordinate the event contract across both languages instead of letting each team migrate independently.

Team type	First priority	Second priority	Do not skip
Python prototype	Run a small graph workflow and inspect events.	Move obvious custom logic into callbacks.	Retry and approval-path testing.
Python production app	Session schema and reader compatibility.	Callback, telemetry, and direct event mutation audit.	Canary workflow with rollback rules.
Go service	Module path and interface updates.	Event constructor and session compatibility tests.	Shared storage readiness.
Multi-language platform	Common event contract across languages.	Shared observability and workflow IDs.	Mixed 1.x/2.0 reader strategy.

A Safe ADK 2.0 Migration Plan You Can Actually Follow

The best migration plan is boring and reversible. It should avoid heroic big-bang upgrades. It should produce evidence at each step. It should protect the systems that make agents operational: state, logs, approvals, retries, user-facing UI, and external side effects.

Phase 1: Audit and isolate

Start by listing every agent and every dependency around it. Identify which agents are safe demos, which are internal tools, and which touch real users or external systems. Pick one canary workflow that is representative but not mission critical. Create an isolated session store or copied dataset. Make sure all secrets, external writes, and destructive tools are disabled or mocked in staging.

Phase 2: Upgrade readers before writers

Update event readers, dashboards, clients, and validators so they can tolerate ADK 2.0 fields. This is a quiet but important step. If readers can accept both old and new event shapes, your rollout becomes much safer. If readers cannot, keep 2.0 events away from shared production storage until they can.

Phase 3: Move lifecycle logic into callbacks

Search for execution overrides and direct event manipulation. Replace them with supported callbacks and yielded events. Add tests that verify the callbacks fire and the expected side effects appear. This is where many silent migration bugs are caught.

Phase 4: Build one workflow graph

Do not migrate ten agents at once. Build one ADK 2.0 workflow graph with a deterministic tool node, one LLM or agent node, one validation step, and one failure path. If your production app uses approval, include a human approval pause. If it uses retries, force a retry. If it writes output, inspect the output field.

Phase 5: Run contract tests

Contract tests should cover event insertion, event reading, UI rendering, callback firing, retry behavior, non-retryable failures, approval pauses, idempotency, and final output shape. If your agent mutates external systems, run tests against mocks first. Then run a narrow canary with low-risk real data.

Phase 6: Canary and observe

Route a small percentage of internal or low-risk traffic to the ADK 2.0 workflow. Watch schema errors, missing telemetry, retry counts, latency, token usage, approval pauses, and user-visible failures. Compare against the old agent path. The goal is not only “does it work?” It is “does it fail in a way we can understand and recover from?”

Phase 7: Expand gradually

After the canary is stable, migrate related workflows in small groups. Keep rollback paths until session readers, dashboards, and operators are comfortable with the new event shape. Document the new workflow design so future contributors understand which parts are deterministic and which parts rely on model reasoning.

How rigid is your session storage?JSON blob or flexible schemaSome typed fields with flexible extrasRigid SQL/ORM schema or strict validatorsHow much custom execution logic do you use?Little or noneSome callbacks or wrappersCustom run overrides, telemetry hooks, or manual event appendsHow risky are your tools?Read-only or internal toolsExternal API calls with low-risk writesPayments, account changes, deletion, sending, or approval-gated actions

Choose your setup to see the migration risk level.

Example Migration: Customer Refund Agent to ADK 2.0 Workflow

Imagine a support team already has an ADK 1.x refund agent. The agent reads a customer message, fetches purchase history, checks policy, issues a refund if eligible, drafts an email, and closes the ticket. The old implementation uses one agent with tools and a long instruction telling it to follow the steps. It also has custom telemetry inside a run override and a broad exception handler inside the refund tool.

A naive migration would upgrade the library, run the same prompt, and declare success if a test ticket closes. A safer migration splits the process. The workflow starts with a deterministic purchase-history node. An LLM node analyzes the customer message against policy. A validation node decides eligibility. A human approval node pauses if the refund is above a threshold. A payment tool issues the refund with an idempotency key. Another LLM node drafts the email. A deterministic CRM node closes the ticket.

START → fetch_purchase_history → analyze_message_agent → validate_eligibility
eligible_low_risk → issue_refund_tool → draft_email_agent → close_ticket
eligible_high_value → human_approval → issue_refund_tool → draft_email_agent → close_ticket
not_eligible → draft_explanation_agent → close_ticket
error → retry_or_escalate

The migration checklist becomes concrete. Session storage must handle node-level events. Telemetry must move from the old run override into workflow or node callbacks. The refund tool must not swallow approval interrupts or retryable API failures. The payment call needs an idempotency key so a retry cannot double-refund. The UI must show a paused approval state clearly. The final output should make it obvious whether the workflow refunded, escalated, or declined.

This example shows why ADK 2.0 is not just a feature upgrade. It changes architecture. The result can be safer and cheaper because deterministic code handles deterministic steps, while the model focuses on messy language. But you only get that benefit if the migration respects storage, callbacks, retries, and approval boundaries.

Limitations and Honest Caveats

ADK 2.0 workflows improve structure, but they do not automatically make an agent reliable. A bad graph can encode the wrong business process. A dynamic workflow can become hard to debug if every branch lives in opaque code. A collaborative workflow can add overhead if one focused agent would have been enough. Migration is not a substitute for architecture judgment.

Do not assume ADK 2.0 will reduce cost or latency in every case. It can reduce waste when deterministic routing replaces model-driven orchestration, but your actual result depends on model choice, prompt size, tool latency, retry behavior, context boundaries, and traffic shape. Measure your own workflows before promising savings.

Also remember that official docs can change. ADK is evolving quickly, and production migration details should always be verified against the active documentation, release notes, and your installed package version. This guide gives a practical checklist, not a replacement for reading the official migration notes before upgrading.

Final Recommendation

If your ADK agent is experimental, migrate with curiosity and inspect the new workflow events. If your ADK agent touches production data, migrate with discipline. Update readers before writers. Isolate the first workflow. Move lifecycle logic into supported callbacks. Replace direct event appends. Narrow broad exception handlers. Test retries and human approval pauses. Use idempotency for external writes. Canary one workflow before expanding.

The teams that benefit most from ADK 2.0 will not be the teams that simply upgrade fastest. They will be the teams that use the migration to separate deterministic process control from language reasoning. That is the deeper point of the workflow runtime. Agents should reason where language is messy. Code should route where the process is known. A good migration protects both.

Keep Learning on AI Feature Drop

• Google ADK Workflows Guide — the broader pillar explaining graph workflows, dynamic workflows, collaborative agents, and production reliability.
• Genkit Agents API Explained — full-stack agent state, streaming, and frontend integration.
• Genkit Human Approval Guide — practical approval patterns for risky AI actions.
• Google Antigravity Artifacts Workflow — persistent artifacts and structured agent work.
• Gemini API File Search and Multimodal RAG — retrieval and context design for AI workflows.
• GitHub Agentic Workflows Explained — compare workflow-style automation across developer ecosystems.

Sources and References

• Google Developers Blog: Why we built ADK 2.0
• ADK docs: Welcome to ADK 2.0
• ADK docs: Dynamic workflows
• ADK docs: Graph workflows
• GitHub: google/adk-python
• GitHub: google/adk-go
• Google Cloud docs: Agent Development Kit on Gemini Enterprise Agent Platform

Product behavior, APIs, and migration details can change. Always verify the official ADK documentation and package-specific release notes before upgrading production applications.

FAQ: ADK 2.0 Migration

What is the biggest ADK 2.0 migration risk?

The biggest risk is usually session and event compatibility. ADK 2.0 adds workflow graph-related event fields, so rigid custom storage, strict JSON validators, dashboards, or replay tools may need updates before they can safely read new events.

Do I need to rewrite every ADK agent as a workflow?

No. Start with workflows where the process has known steps, risky tool calls, approval needs, retries, state boundaries, or audit requirements. Simple exploratory agents may not need a full workflow redesign.

Why do callbacks matter in ADK 2.0?

Because agents are evaluated as nodes inside the workflow graph, older custom execution overrides may not fire the way you expect. Move lifecycle logic such as telemetry, state updates, and audit hooks into supported callbacks and test them explicitly.

Can broad try-except blocks break ADK 2.0 retries?

Yes. If a tool catches every exception and returns a generic message, the framework may not see retryable failures or human approval pauses. Narrow exception handling so the workflow runtime can manage retries and interruptions correctly.

Should I upgrade event readers before event writers?

For production systems, yes. Update readers, validators, dashboards, and clients so they tolerate ADK 2.0 event fields before a live workflow writes those events into shared storage.

What is a good first ADK 2.0 canary workflow?

Choose a low-risk workflow that still represents real complexity: one deterministic tool node, one LLM node, one validation step, one forced tool failure, and one approval-like pause if your production system uses approval.

Does ADK 2.0 automatically make agents cheaper?

Not automatically. It can reduce waste when deterministic routing replaces model-driven orchestration, but actual cost depends on model choice, prompt size, tool latency, retries, context boundaries, and traffic.

What should Go teams check first?

Go teams should check the new major module path, interface changes, event construction changes, and whether shared session readers can handle ADK 2.0 event fields before production writes begin.