Migrate from LangGraph to Agentmatic in 5 minutes

This is the no-handwaving migration guide. I’ll assume you have a working LangGraph project and walk you through getting it on the Rust engine.

Step 1 — Install

pip install agentmatic

Prebuilt wheels for CPython 3.10–3.13, Linux / macOS / Windows, x86_64 / arm64. No cargo required.

Step 2 — Change the imports

# Before
from langgraph.graph import StateGraph, START, END
from langgraph.checkpoint.memory import MemorySaver

# After
from agentmatic import StateGraph, START, END
from agentmatic.checkpoint import MemorySaver

Rename references to langgraph throughout your file. The Annotated reducers, TypedDict state, add_node, add_edge, add_conditional_edges, compile — all work the same.

Step 3 — Run your existing tests

This is the most important step. Your test suite should pass with zero modifications.

pytest

If anything fails, file an issue. We aim for 100% LangGraph 0.2+ surface parity and add shims as people report gaps.

Step 4 — Bridge LangChain tools

from agentmatic.integrations.langchain import from_langchain_tools
from langchain_community.tools import WikipediaQueryRun, DuckDuckGoSearchRun

tools = from_langchain_tools([WikipediaQueryRun(), DuckDuckGoSearchRun()])
agent = create_react_agent(llm=llm, tools=tools)

from_langchain_tools() is the shim. It wraps a list of BaseTool instances as Agentmatic tools.

Step 5 — Keep LangSmith / LCEL / LangServe working

If you want to keep using LangSmith for traces or LCEL for composition:

from agentmatic.integrations.langchain import as_langchain_runnable

runnable = as_langchain_runnable(agent)
# Now usable in LCEL chains, LangServe deployments, LangSmith traces.

This is the bridge that lets you ship without rewriting your observability or deployment story.

Step 6 — Adopt resilience primitives (optional but free)

This is where you start getting wins LangGraph can’t give you without their paid Platform tier:

agent = (Agent.builder("production")
    .llm(OpenAI("gpt-4o"))
    .tools([search, calculator])
    .checkpoint(S3Saver(bucket="my-agents"))
    .circuit_breaker("openai", failure_threshold=5, cooldown_seconds=30)
    .retry_policy(RetryPolicy.exponential(max_attempts=3, jitter=True))
    .dead_letter_queue(DeadLetterQueue.postgres(DATABASE_URL))
    .interrupt_before(["dangerous_tool"])
    .build())

All MIT-licensed. All in the open-source core. Use what you want; skip what you don’t.

The actual gotchas

Honesty: things you might hit.

Annotated reducers

Annotated[list, operator.add] works identically. So does the more verbose form:

from typing import Annotated
from agentmatic.graph.message import add_messages

class State(TypedDict):
    messages: Annotated[list, add_messages]

add_messages is re-exported under agentmatic.graph.message with the same semantics as LangGraph’s.

Streaming events

agent.stream(...) and agent.astream(...) are 1:1. We additionally support agent.astream_events(...) for v2 LangChain-style events.

Checkpoint formats

• Memory → wire-compatible.
• SQLite → wire-compatible.
• Postgres → requires agentmatic.checkpoint.postgres.upgrade(conn) once.
• Redis → wire-compatible.
• S3 → wire-compatible.

LangSmith env vars

LANGCHAIN_TRACING_V2=true and LANGCHAIN_API_KEY still work if you wrap with as_langchain_runnable(). The Rust runtime is also instrumented with OpenTelemetry — set OTEL_EXPORTER_OTLP_ENDPOINT and traces land in any OTLP collector (Datadog, Honeycomb, Tempo).

LangGraph Platform features

If you’re on LangGraph Platform’s hosted runtime, you’re using their persistence + retry + replay layer. Migration plan:

1. Move persistence: pick a checkpoint backend (Postgres recommended).
2. Move retry: configure RetryPolicy on the agent.
3. Move replay: get_state_history() + reinvoke with checkpoint_id.
4. Move observability: OpenTelemetry pipeline.
5. Move dashboard: Agentmatic Studio (open source) + your APM.

Async + sync

Both invoke and ainvoke exist. The sync version is a thin wrapper over the async runtime; no sync-async deadlocks (we run the Tokio runtime on a dedicated thread).

Migration timing — real numbers

From the last 30 migrations we helped with:

Project shape	Migration time
Single agent, no checkpointer	5 minutes
Multi-agent supervisor, MemorySaver	30 minutes
Production: Postgres + LangSmith + CI	2 hours
Production: + cluster + custom observability	1 day

The longest single piece is usually re-wiring observability dashboards, not framework changes.

What’s next

• /benchmarks — see exactly what speed-up to expect on your workload shape.
• /resilience — circuit breakers, retry, DLQ in depth.
• /recipes — cookbook patterns to validate the new primitives.

If you hit anything weird, file a GitHub issue. We turn them around fast.