1. Home
2. Build Agents
3. Get Started

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 a 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:

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:

Convert code with evaluation¶

A reliable migration is test-driven. Your coding agent can set up evaluation datasets and test suites alongside the new ADK code to verify that the migrated agent produces the same outcomes as your original implementation.

1. Set up evaluation test cases: Have your coding agent convert existing test cases or recorded conversations into evaluation cases under eval/.
2. Port tools and agent logic: Replace custom dispatch loops and tool wrappers with typed Python functions and an ADK Agent or Workflow.

# agent.py
from google.adk.agents import Agent
from google.adk.tools import ToolContext

def lookup_customer(customer_id: str) -> str:
    """Retrieve account tier and status for a customer."""
    return "Tier: Premium, Status: Active"

def calculate_discount(amount: float, rate: float = 0.1) -> float:
    """Calculate discounted total for a transaction."""
    return amount * (1.0 - rate)

root_agent = Agent(
    name="customer_support_agent",
    model="gemini-flash-latest",
    instruction="Assist customers with account inquiries and discounts using your tools.",
    tools=[lookup_customer, calculate_discount],
)

Verify and evaluate¶

Run the evaluation suite to compare the migrated agent against your baseline test cases:

agents-cli eval run

You can also test queries directly or interactively:

# Test a single prompt
agents-cli run "Look up customer cust_101 and apply a 10% discount on $100."

# Start the interactive web UI
agents-cli playground

Next steps¶

• Read the Multi-tool agent tutorial to learn more about ADK tool patterns.
• Explore Graph workflows for multi-agent routing and state coordination.
• Deploy your agent using the Deployment guide.