Getting Started

Migrate from ADK

Move a Google ADK project into Connic. The connic migrate CLI handles the initial conversion. After that, you clean up the parts that need manual attention.

Last updated May 4, 2026

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 (built-in or custom)	`gemini-2.5-flash` becomes `gemini/gemini-2.5-flash`
Python tools / `FunctionTool`	Python functions in `tools/`	`FunctionTool` wrappers are unwrapped
`AgentTool` / LLM `sub_agents`	`trigger_agent` predefined tool	Mapped automatically; review prompts and target agent names
`google_search`	`web_search` predefined tool	Mapped automatically
Callbacks	Middleware in `middleware/` and tool hooks in `hooks/`	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

prompt.txt

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.

terminal

pip install connic-composer-sdk

connic migrate

You can also pass both paths directly:

terminal

connic migrate --source ./my-adk-project --dest ./my-connic-project

The 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.

Project structure

my-connic-project/

agents/

support-agent.yaml

review-pipeline.yaml

tools/

tools.pyExtracted tool functions

middleware/

schemas/

requirements.txt

README.md

MIGRATION_REPORT.mdReview this first

Understand the output

Below are examples of how typical ADK definitions translate to Connic.

LLM agent

ADK (before)

agent.py

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)

agents/support-agent.yaml

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.summarize

Sequential agent

ADK (before)

agent.py

from google.adk.agents import SequentialAgent

pipeline = SequentialAgent(
    name="review-pipeline",
    sub_agents=[draft_agent, review_agent, publish_agent],
)

Connic (after)

agents/review-pipeline.yaml

version: "1.0"
name: review-pipeline
type: sequential
description: "Runs draft, review, and publish agents in order."
agents:
  - draft-agent
  - review-agent
  - publish-agent

Clean up

Migrates automatically

Explicit Agent, LlmAgent, and SequentialAgent definitions

Plain Python tool functions and FunctionTool wrappers

AgentTool wrappers mapped to trigger_agent

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

MCPToolset wrappers

Dynamically constructed instructions or tool lists

Custom guardrails

Checklist after migration

Read MIGRATION_REPORT.md and 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 agent-level callbacks to Connic middleware, and tool-level callbacks (before_tool_callback / after_tool_callback) to tool hooks.
Redesign session or state patterns using Connic sessions, the knowledge base, or the database.
Run connic lint after each cleanup pass.
Run connic dev to spin up a hot-reload runner and verify your agents work end-to-end.

Quick Start

Set up a fresh Connic project from scratch

Agent Configuration

Full reference for all YAML fields

Write Tools

Adjust migrated Python tools to Connic conventions

Middleware

Convert ADK agent callbacks into before/after middleware

Tool Hooks

Convert ADK tool callbacks into before/after tool hooks

Dev Server

Iterate on migrated agents with connic dev and hot-reload