Migrate from LangChain
Move a LangChain or LangGraph project into Connic. The connic migrate CLI handles the initial conversion. After that, you clean up the LangGraph-specific patterns that need manual attention.
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 |
If your 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. 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 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.Run the migration
Install the SDK and run connic migrate. It will prompt you for the path to your existing LangChain project and a destination for the generated Connic project.
pip install connic-composer-sdk
connic migrateYou can also pass both paths directly:
connic migrate --source ./my-langchain-project --dest ./my-connic-projectThe 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.
Understand the output
Below are examples of how typical LangChain definitions translate to Connic.
Agent definition
LangChain source
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
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_weatherTool function
LangChain source
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}").textConnic output
import requests
def fetch_weather(city: str) -> str:
"""Return the current weather for a city."""
return requests.get(f"https://api.weather.example/{city}").textConnic 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.
Clean up
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()
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
- 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). - 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 lintafter each cleanup pass. - Run
connic devto open a cloud development environment with hot reload and verify your agents end-to-end.