Skip to main content

​
What stays the same

Your existing investment carries over:
  • Graph code — Your LangGraph agents work without modification.
  • SDK client calls — get_client(), client.threads, client.runs.stream() — all the same.
  • Agent Protocol frontends — Agent Chat UI, LangGraph Studio, CopilotKit — all compatible.
  • Thread state model — Threads, checkpoints, and state inspection work identically.
  • Streaming — Same SSE modes and event format.
  • Human-in-the-loop — Same interrupt/resume patterns.

​
What changes

LangSmith DeploymentsAegra
Config filelanggraph.jsonaegra.json (falls back to langgraph.json)
Client URLhttps://your-deployment.langsmith.comhttp://localhost:8000 (or your host)
DatabaseManaged by platformYour own PostgreSQL
Auth configDashboard settingsPython handler in aegra.json
TracingLangSmith (automatic)OTLP via environment variables
Deploy commandlanggraph deployaegra up or docker compose up

​
Step-by-step migration

1

Install the Aegra CLI

pip install aegra-cli
2

Copy your graph code

Copy your graph modules into a new project directory. Your LangGraph code works as-is — no changes needed.
mkdir my-project && cd my-project
cp -r /path/to/your/graphs ./graphs
3

Create aegra.json

Replace your langgraph.json with aegra.json. The structure is similar:Before (langgraph.json):
{
  "dependencies": ["."],
  "graphs": {
    "agent": "./graphs/agent.py:graph"
  }
}
After (aegra.json):
{
  "graphs": {
    "agent": "./graphs/agent.py:graph"
  }
}
The graphs section is identical. Aegra also reads langgraph.json as a fallback, so you can skip this step initially and rename later.
See the configuration reference for all available options including auth, HTTP, CORS, and store settings.
4

Set up your environment

Create a .env file with your API keys and database settings:
# LLM provider
OPENAI_API_KEY=sk-...

# Database (aegra dev manages this automatically)
POSTGRES_USER=aegra
POSTGRES_PASSWORD=aegra
POSTGRES_DB=aegra
If you already have a PostgreSQL instance, set DATABASE_URL directly:
DATABASE_URL=postgresql://user:pass@host:5432/aegra
5

Start the server

uv sync
uv run aegra dev
This starts PostgreSQL in Docker, runs migrations, and launches the server with hot reload at http://localhost:8000.
6

Update your client URL

Change the client URL in your application code:
from langgraph_sdk import get_client

# Before
# client = get_client(url="https://your-deployment.langsmith.com")

# After
client = get_client(url="http://localhost:8000")
Everything else — thread creation, runs, streaming, state inspection — works the same.

​
Migrate authentication

LangSmith Deployments configures auth through a dashboard. Aegra uses a Python handler instead. Create an auth file and reference it in aegra.json: 
from langgraph_sdk import Auth

auth = Auth()

@auth.authenticate
async def authenticate(headers: dict) -> dict:
    token = headers.get("Authorization", "").replace("Bearer ", "")
    if not token:
        raise Exception("Authentication required")

    # Replace with your JWT verification logic
    payload = verify_jwt(token)
    return {
        "identity": payload["sub"],
        "display_name": payload.get("name", ""),
        "is_authenticated": True,
    }

{
  "graphs": { "agent": "./graphs/agent.py:graph" },
  "auth": { "path": "./my_auth.py:auth" }
}
See the authentication guide for JWT, OAuth, and Firebase examples.

​
Migrate tracing

LangSmith Deployments sends traces to LangSmith automatically. With Aegra, you configure tracing via environment variables and can send to any OTLP-compatible backend. To send traces to Langfuse: 
OTEL_TARGETS="LANGFUSE"
LANGFUSE_BASE_URL=https://cloud.langfuse.com
LANGFUSE_PUBLIC_KEY=pk-lf-...
LANGFUSE_SECRET_KEY=sk-lf-...
You can fan out to multiple backends simultaneously: 
OTEL_TARGETS="LANGFUSE,PHOENIX"
See the observability guide for all supported backends and configuration options.

​
Features not yet available

A few features from LangSmith Deployments are not yet supported in Aegra. See the feature support page for the full matrix. Key gaps:
  • Cron / scheduled jobs — Coming soon.
  • RemoteGraph — Not yet planned.

​
Get help