Migrate from ADK
Move a Google ADK project into Connic. The connic migrate CLI handles the initial conversion, then you clean up the parts that need manual attention.
Concept mapping
ADK defines agents in Python. Connic separates them into YAML configuration and Python tool code. The table below shows how the main ADK concepts translate.
| ADK | Connic | Notes |
|---|---|---|
Agent / LlmAgent | YAML file in agents/ with type: llm | Migrated automatically |
SequentialAgent | YAML file with type: sequential | Migrated automatically |
ParallelAgent / LoopAgent | Migrated as sequential; needs manual review | No direct Connic equivalent |
instruction | system_prompt | Extracted from Python or YAML |
model | model with provider prefix | gemini-2.5-flash becomes gemini/gemini-2.5-flash |
Python tools / FunctionTool | Python functions in tools/ | FunctionTool wrappers are unwrapped |
google_search | web_search predefined tool | Mapped automatically |
| Callbacks | Middleware in middleware/ | Requires manual conversion |
| Sessions / state | Connic sessions or knowledge base | Requires manual redesign |
MCPToolset | mcp_servers in agent YAML | Requires manual configuration |
Complex ADK projects
If your ADK project relies heavily on custom agent subclasses, dynamic registration, planners, or callback-driven workflows, connic migrate may not find all agents automatically. In that case you can use a coding agent (Cursor, Windsurf, Claude Code, Codex, etc.) to handle the full migration. Run connic migrate first for the scaffold, then let the coding agent finish the cleanup using the Connic docs as context.
Example prompt for a coding agent
You are migrating a Google ADK Python project to Connic.
1. Inspect the existing ADK project at ./my-adk-project and explain how agents, tools, callbacks, sessions, and deployment are structured.
2. Run `connic migrate --source ./my-adk-project --dest ./my-connic-project`.
3. Review the generated Connic project and fix any issues listed in MIGRATION_REPORT.md.
4. Run `connic lint` inside the migrated project and resolve any errors.
5. Summarize what migrated cleanly and what still needs manual work.
Prefer Connic conventions: YAML agents in agents/, Python tools in tools/, middleware/ for hooks, schemas/ for structured output.
Use the Connic docs at https://connic.co/docs/v1 as a reference.Run the migration
Install the SDK and run connic migrate. It will prompt you for the path to your existing ADK project and a destination for the new Connic project.
pip install connic-composer-sdk
connic migrateYou can also pass both paths directly:
connic migrate --source ./my-adk-project --dest ./my-connic-projectThe migrator scans your source project for Agent, LlmAgent, SequentialAgent, ParallelAgent, and LoopAgent definitions in Python, as well as YAML-based agent configs (including root_agent.yaml). It extracts tools, resolves instructions and model names, generates the Connic project, and runs connic lint on the result.
Review the generated project
The migrator creates the following structure. Start by reading MIGRATION_REPORT.md, which lists every agent that was migrated, what tools were resolved, and any items that need manual work.
my-connic-project/
├── agents/
│ ├── support-agent.yaml
│ └── review-pipeline.yaml
├── tools/
│ └── tools.py # Extracted tool functions
├── middleware/
├── schemas/
├── requirements.txt
├── README.md
└── MIGRATION_REPORT.md # Review this firstUnderstand the output
Below are examples of how typical ADK definitions translate to Connic.
LLM agent
ADK (before)
from google.adk.agents import LlmAgent
from google.adk.tools import FunctionTool
from tools import search_docs, summarize
support_agent = LlmAgent(
name="support-agent",
model="gemini-2.5-flash",
instruction="""You are a technical support agent.
Help users resolve issues by searching documentation
and summarizing the results.""",
tools=[search_docs, summarize],
)Connic (after)
version: "1.0"
name: support-agent
type: llm
model: gemini/gemini-2.5-flash
description: "You are a technical support agent."
system_prompt: |
You are a technical support agent.
Help users resolve issues by searching documentation
and summarizing the results.
tools:
- tools.search_docs
- tools.summarizeSequential agent
ADK (before)
from google.adk.agents import SequentialAgent
pipeline = SequentialAgent(
name="review-pipeline",
sub_agents=[draft_agent, review_agent, publish_agent],
)Connic (after)
version: "1.0"
name: review-pipeline
type: sequential
description: "Runs draft, review, and publish agents in order."
agents:
- draft-agent
- review-agent
- publish-agentClean up
Migrates automatically
Explicit Agent, LlmAgent, and SequentialAgent definitions
Plain Python tool functions and FunctionTool wrappers
Static instruction text (string literals and variables)
Model names (auto-prefixed with the provider, e.g. gemini/)
YAML-based ADK agent definitions
google_search mapped to web_search
Needs manual work
ParallelAgent and LoopAgent (migrated as sequential placeholders)
Custom agent subclasses and wrapper factories
Dynamic agent registration patterns
Callbacks (convert to Connic middleware where applicable)
Session state and persistent memory
AgentTool and MCPToolset wrappers
Dynamically constructed instructions or tool lists
Custom guardrails
Checklist after migration
- Read
MIGRATION_REPORT.mdand address every follow-up item. - Open each agent YAML in
agents/and verify the system prompt and tool list. - Check that tool modules in
tools/still import everything they need (relative imports from the original project may break). - Convert ADK callbacks to Connic middleware if they implement before/after request logic.
- Redesign session or state patterns using Connic sessions, the knowledge base, or the database.
- Run
connic lintafter each cleanup pass. - Run
connic testto verify agents work end-to-end.