Connecting to a LangGraph Agent
This guide explains how to connect EvalStudio to a LangGraph agent. It covers the prerequisites, how to configure the connector, and what happens under the hood.
Prerequisites
You need a running LangGraph server. EvalStudio connects to it over HTTP — it does not run or manage the LangGraph process itself.
Option 1: Local Development Server
The fastest way to get started. See the LangGraph local server docs for full details.
For JavaScript/TypeScript agents:
npx @langchain/langgraph-cli dev
For Python agents:
pip install "langgraph-cli[inmem]"
langgraph dev
Both start a server at http://127.0.0.1:2024 with in-memory storage and hot reloading.
Your project needs a langgraph.json that registers your graph. A minimal JS/TS config:
{
"graphs": {
"agent": "./src/agent.ts:graph"
}
}
The value points to the file and exported CompiledStateGraph instance. See the LangGraph CLI docs for all configuration options.
Option 2: Docker (with persistence)
For a more production-like setup with PostgreSQL-backed persistence:
# JS/TS
npx @langchain/langgraph-cli up
# Python
langgraph up
This starts a server at http://localhost:8123. See the LangGraph CLI docs for configuration options.
Option 3: LangGraph Platform (Cloud)
For hosted deployments, see LangGraph deployment options. Your base URL will be provided by the platform.
Verifying the server is running
You can check that the server is reachable:
curl http://127.0.0.1:2024/info
A successful response means the server is ready. This is the same endpoint EvalStudio uses for the agent health check.
Configuring the Connector
Via the Web UI (Agents page)
- Navigate to the Agents page
- Click + New Agent
- Fill in:
- Name: A display name (e.g., "My LangGraph Agent")
- Type:
langgraph - Base URL: Your server URL (e.g.,
http://127.0.0.1:2024) - Assistant ID: The assistant to invoke (see Assistant ID below)
- Click Create
- Use the Test button to verify connectivity — it calls
GET /infoon your server
After creating the agent, you can configure optional settings in the agent's Settings tab:
- Headers: Custom HTTP headers (e.g., API keys)
- Configurable: Runtime config values passed to your agent
Via the CLI
evalstudio connector create "My LangGraph Agent" \
--type langgraph \
--url http://127.0.0.1:2024 \
--config '{"assistantId": "my-assistant"}'
Via the API
curl -X POST http://localhost:3000/api/projects/PROJECT_ID/connectors \
-H "Content-Type: application/json" \
-d '{
"name": "My LangGraph Agent",
"type": "langgraph",
"baseUrl": "http://127.0.0.1:2024",
"config": {"assistantId": "my-assistant"}
}'
Concept Mapping
EvalStudio's connector configuration maps to LangGraph concepts as follows:
| EvalStudio Field | LangGraph Concept | Notes |
|---|---|---|
baseUrl | Server URL | The root URL of the LangGraph server |
config.assistantId | Assistant | Which assistant to invoke. Defaults to "default" if not set |
config.configurable | Configurable | Runtime parameters passed as config.configurable in invoke requests |
headers | HTTP headers | Merged into every request. Use for API keys (x-api-key) or auth tokens |
Run threadId | Thread | Managed automatically — EvalStudio creates threads on first message and reuses them for multi-turn conversations |
Assistant ID
When you deploy a LangGraph graph, the platform auto-creates a default assistant for it. If you only have one graph, you can leave assistantId blank — EvalStudio defaults to "default".
If you have multiple assistants or want to target a specific one, set the assistantId in the connector config. You can find available assistants by querying your LangGraph server:
curl http://127.0.0.1:2024/assistants/search
Configurable Values
LangGraph agents can accept runtime configuration via config.configurable. Common use cases:
- Selecting a model:
{"model": "gpt-4o"} - Setting a system prompt:
{"system_message": "You are a helpful assistant"} - Feature flags:
{"use_rag": true}
Set these in the connector's Configurable field (JSON object). They're sent with every invoke request.
How EvalStudio Communicates with LangGraph
Health Check (Test)
GET {baseUrl}/info
Used by the agent status indicator and the Test button. Any 2xx response means the agent is online.
Sending Messages (Invoke)
First message (no thread yet):
POST {baseUrl}/runs/wait
Subsequent messages (thread exists):
POST {baseUrl}/threads/{threadId}/runs/wait
The request body:
{
"assistant_id": "my-assistant",
"input": {
"messages": [
{"role": "user", "content": "Hello"}
]
},
"multitask_strategy": "enqueue",
"if_not_exists": "create",
"config": {
"configurable": {"key": "value"}
}
}
Key behaviors:
- Thread auto-creation:
"if_not_exists": "create"tells LangGraph to create the thread automatically on first use - Message deduplication: On subsequent turns, EvalStudio only sends new messages (not the full history), since LangGraph already has the thread state
- Synchronous wait: Uses
/runs/waitwhich blocks until the agent completes its response - Configurable: Only included when configured on the connector