Skip to main content
Connic
Getting Started

Migrate from Google ADK

The connic migrate CLI converts Google ADK projects to Connic. This guide covers concept mapping, automatic conversion, and the parts that need manual cleanup.

Last updated
On this page

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.

ADKConnicNotes
Agent / LlmAgentYAML file in agents/ with type: llmMigrated automatically
SequentialAgentYAML file with type: sequentialMigrated automatically
ParallelAgent / LoopAgentMigrated as sequential; needs manual reviewNo direct Connic equivalent
instructionsystem_promptExtracted from Python or YAML
modelmodel with provider prefix (built-in or custom)gemini-2.5-flash becomes gemini/gemini-2.5-flash
Python tools / FunctionToolPython functions in tools/FunctionTool wrappers are unwrapped
AgentTool / LLM sub_agentstrigger_agent predefined toolMapped automatically; review prompts and target agent names
google_searchweb_search predefined toolMapped automatically
CallbacksMiddleware in middleware/ and tool hooks in hooks/Requires manual conversion
Sessions / stateConnic sessions or retrievalRequires manual redesign
MCPToolsetmcp_servers in agent YAMLRequires manual configuration
Complex ADK projects

If the 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, 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.

  1. Run the migration

    Install the SDK and run connic migrate. It prompts for the path to the existing ADK project and a destination for the generated Connic project.

    terminal
    pip install connic-composer-sdk

connic migrate

    Both paths can also be passed directly:

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

    The migrator scans the 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.

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

  3. Understand the output

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

    LLM agent

    ADK source

    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 output

    agents/support-agent.yaml
    version: "1.0"
name: support-agent
type: llm
model: connic/gpt-5.6-terra # or gemini/gemini-2.5-flash with Gemini BYOK configured
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 source

    agent.py
    from google.adk.agents import SequentialAgent

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

    Connic output

    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

  4. 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
    1. Read MIGRATION_REPORT.md and address every follow-up item.
    2. Open each agent YAML in agents/ and verify the system prompt and tool list.
    3. Check that tool modules in tools/ still import everything they need (relative imports from the original project may break).
    4. Convert ADK agent-level callbacks to Connic middleware, and tool-level callbacks (before_tool_callback / after_tool_callback) to tool hooks.
    5. Redesign session or state patterns using Connic sessions, the retrieval, or the database.
    6. Run connic lint after each cleanup pass.
    7. Run connic dev to open a cloud development environment with hot reload and verify the migrated agents end-to-end.

Continue the migration

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