Getting Started

Migrate from LangChain

The connic migrate CLI converts LangChain and LangGraph projects to Connic. This guide covers concept mapping, automatic conversion, and manual cleanup of LangGraph-specific patterns.

Last updated August 20, 2026

On this page

Concept mapping

LangChain keeps agent definitions, tools, and orchestration in Python. Connic separates them into YAML configuration and standalone Python tool modules. The table below shows how the main LangChain concepts translate.

LangChain / LangGraph	Connic	Notes
`create_agent()` / `create_react_agent()`	YAML file in `agents/` with `type: llm`	Both signatures are detected
`system_prompt` / `prompt`	`system_prompt`	Extracted from keyword arguments
`ChatOpenAI`, `init_chat_model`, etc.	`model` with provider prefix (built-in or custom)	`gpt-4.1` becomes `openai/gpt-4.1`
`@tool` functions / plain callables	Python functions in `tools/`	Decorator is removed; ordinary tool bodies are kept
Simple sub-agent wrappers using `.invoke()` / `.ainvoke()`	Async tools using `trigger_agent`	Tool schema and fixed child-agent routing are preserved
`tools=[...]`	`tools:` list in agent YAML	Resolved to `module.function` references
LangGraph `StateGraph` / workflows	Sequential agents or custom tool logic	Requires manual restructuring
Checkpointers / stores	Connic sessions, retrieval, or database	Requires manual redesign
LangSmith tracing	Connic observability (built in)	No migration needed; remove LangSmith integration code
Retrieval chains / RAG	Retrieval tools or custom tools	Restructure as a Connic tool or use the built-in retrieval

Complex LangGraph projects

If the project is built primarily around LangGraph state graphs, handoffs, or heavily customized retrieval chains, connic migrate will extract the agent and tool definitions it finds, but the graph orchestration itself will need manual restructuring. A coding agent (Cursor, Windsurf, Claude Code, Codex, etc.) can 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 Python LangChain or LangGraph project to Connic.

1. Inspect the existing project at ./my-langchain-project and explain how agents, tools, prompts, retrieval, memory, and orchestration are structured.
2. Run `connic migrate --source ./my-langchain-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 LangChain 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-langchain-project --dest ./my-connic-project
```
The migrator scans every Python file for create_agent and create_react_agent calls, extracts tools, resolves model names and prompts (including across imports), 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/
agent.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 LangChain definitions translate to Connic.

Agent definition

LangChain source

agent.py

from langchain.agents import create_agent
from langchain_openai import ChatOpenAI

llm = ChatOpenAI(model="gpt-4.1")

agent = create_agent(
    llm,
    tools=[search_docs, fetch_weather],
    system_prompt="You are a helpful research assistant.",
)

Connic output

agents/agent.yaml

version: "1.0"
name: agent
type: llm
model: connic/gpt-5.6-sol # or openai/gpt-4.1 with OpenAI BYOK configured
description: "You are a helpful research assistant."
system_prompt: |
  You are a helpful research assistant.
tools:
  - tools.search_docs
  - tools.fetch_weather

Tool function

LangChain source

tools.py

from langchain_core.tools import tool

@tool
def fetch_weather(city: str) -> str:
    """Return the current weather for a city."""
    return requests.get(f"https://api.weather.example/{city}").text

Connic output

tools/tools.py

import requests

def fetch_weather(city: str) -> str:
    """Return the current weather for a city."""
    return requests.get(f"https://api.weather.example/{city}").text

Connic uses the function signature and docstring directly, so the @tool decorator is not needed. For ordinary tools, the migrator extracts the function body along with its imports and dependencies. Simple pass-through sub-agent wrappers are rewritten to call the migrated child through trigger_agent.

4
Clean up
Migrates automatically
create_agent() and create_react_agent() calls
Plain Python tools and @tool decorated functions
Static system_prompt / prompt keyword arguments
Model names from ChatOpenAI, init_chat_model, and similar
Cross-file imports (variables and functions are resolved)
Tool dependencies (helper functions and local modules)
Simple sub-agent wrappers using .invoke() or .ainvoke()
Needs manual work
LangGraph StateGraph workflows and handoffs
Dynamic prompt construction (factories, templates with runtime values)
Checkpointers and custom persistence stores
Retrieval chains and RAG pipelines
LangSmith integration code (tracing, evaluations, prompt registries)
Custom agent wrappers with additional logic or subclassed agents
Agents that are not assigned to a top-level variable
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).
Remove LangSmith, LangServe, or other LangChain platform code unused by the Connic project.
Restructure LangGraph workflows into sequential agents or custom tools.
Replace checkpointer-based persistence with Connic sessions or the retrieval.
Run connic lint after each cleanup pass.
Run connic dev to open a cloud development environment with hot reload and verify the migrated agents end-to-end.

Continue the migration

Quickstart

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

Orchestration Tools

Delegate work between migrated agents

Migrate from LangChain

Concept mapping

Run the migration

Review the generated project

Understand the output

Agent definition

Tool function

Clean up

Continue the migration