Migrate existing agents to ADK

This guide shows you how to migrate an existing agent codebase to Agent Development Kit (ADK) using Agents CLI and your coding agent. Migrating to ADK lets you standardize your agent architecture across multiple languages, use built-in evaluation tools, and deploy directly to Google Cloud.

Migrate with Agents CLI

Instead of manually rewriting state objects, node graphs, and execution loops line by line, you can use Agents CLI to plan and execute the migration with your coding agent.

Agents CLI installs ADK development skills into coding agents such as Antigravity, Claude Code, Cursor, and Codex. When you open your coding agent in an existing project, it can:

• Analyze your current agent structure, tools, state, and routing rules.
• Map existing components to native ADK classes and graph workflows.
• Propose architecture options with trade-offs.
• Convert tools, agent definitions, and session handling incrementally.
• Generate evaluation datasets to verify behavior before and after migration.

For more information on using Agents CLI, see the Agents CLI documentation.

Prerequisites

Before starting your migration, make sure you have the following installed:

• Python 3.11 or later
• The uv package manager
• A supported coding agent

Install Agents CLI and its ADK skills into your coding agent:

uvx google-agents-cli setup

To verify the installation:

agents-cli info

Migration workflow

Follow this process to migrate an existing agent to ADK:

1. Open your coding agent in the existing project
2. Brainstorm the migration plan
3. Map agent patterns to ADK
4. Convert code with evaluation
5. Verify and evaluate

Open your coding agent in the existing project

Open your terminal or IDE in the root directory of your existing agent project, and start your coding agent. Confirm that the agent detects the ADK skills installed by Agents CLI.

Brainstorm a migration plan

Ask your coding agent to inspect your current codebase and brainstorm the target ADK architecture. Since the agent has ADK Skills loaded through Agents CLI, it understands ADK state management, graph workflows, and orchestration patterns. Use a prompt in your coding agent similar to the following:

Code agent prompt

I want to migrate this existing agent codebase to Google Agent Development Kit (ADK).
Please inspect our current files, state schema, tools, and control flow.
Propose 2-3 target ADK architecture options with trade-offs, and recommend the cleanest approach.
Include an evaluation plan to verify behavior using agents-cli eval.

Your coding agent analyzes the following items:

• Execution flow: Single tool-calling loop, deterministic graph workflow, dynamic router, or multi-agent team.
• Tools: Functions, parameter signatures, docstrings, and external API calls.
• Memory and retrieval: Knowledge stores, vector search integrations, or conversational memory.
• State: Variables tracked across turns, scratchpad keys, and session storage.
• Target classes: Which ADK classes, such as Agent or Workflow, fit best.
• Evaluation strategy: How to convert existing test cases into evaluation datasets to benchmark the migrated agent.

Once you review the proposed approaches, approve the architecture that matches your requirements.

Map agent patterns to ADK

ADK replaces custom dispatch loops and state handlers with declarative classes and graph workflows. Use the following mapping as a guide during migration:

Existing pattern	ADK equivalent	Description
Custom tool schemas or wrappers	Native Python functions or FunctionTool	Plain Python functions with type hints and docstrings. ADK automatically derives tool declarations.
Custom agent loops or runners	Agent	Declarative agent definition specifying model, instructions, tools, and sub-agents.
Memory and retrieval	BaseMemoryService implementations and retrieval tools	Built-in memory services (InMemoryMemoryService, VertexAiMemoryBankService, VertexAiRagMemoryService) plus retrieval tools for session and document grounding.
State dictionaries or scratchpads