Call a deployed LangGraph graph (LangSmith Deployment or Agent Server) as if it were a local CompiledStateGraph — same invoke/stream/get_state surface, works as a subgraph node, supports interrupt/resume and state inspection.
Verified against langgraph==1.2.22 / langgraph-sdk==0.4.14 (module: langgraph.pregel.remote).
RemoteGraph calls a graph running in the LangGraph Agent Server (a LangSmith Deployment, a self-hosted server, or langgraph dev) over HTTP. It exposes the same invoke, stream, get_state, update_state, get_state_history surface as a local graph.
It is close to a drop-in replacement, with one difference to plan for: results come back as JSON. Messages in invoke and stream output are plain dicts ({"type": "ai", "content": ...}), not AIMessage objects, and __interrupt__ entries in streamed chunks are dicts too. get_state() does rebuild Interrupt objects. When a RemoteGraph runs as a node inside a local graph, the parent’s reducers (such as add_messages) turn the dicts back into message objects.
RemoteGraph is also a valid LangGraph node: you can add it to a parent StateGraph with add_node(remote_graph), enabling local-remote hybrid architectures.
result = remote.invoke({"messages":[("user","Hello")]}, cfg)
print(result["messages"][-1]["content"])# a dict, not an AIMessage
Checked against a local langgraph dev server. The thread is created on first use (if_not_exists="create"); without a thread_id the call runs statelessly.
Requires langgraph-sdk — installed automatically with langgraph:
assistant_id: str, # graph_id or assistant UUID on the server
/,
*,
url: str | None = None,
api_key: str | None = None,
headers: dict[str, str] | None = None,
client: LangGraphClient | None = None,
sync_client: SyncLangGraphClient | None = None,
config: RunnableConfig | None = None,
name: str | None = None,
distributed_tracing: bool = False,
)
Parameter
Description
assistant_id
The graph name or UUID registered on the server. Positional-only.
url
HTTP base URL of the deployment. Reads LANGGRAPH_API_KEY / LANGSMITH_API_KEY / LANGCHAIN_API_KEY from the environment if api_key is not passed.
api_key
Overrides the environment variable API key.
headers
Extra HTTP headers forwarded on every request.
client
Pre-built async LangGraphClient (from langgraph_sdk). Use when you need full control over connection pooling.
sync_client
Pre-built sync SyncLangGraphClient.
config
A RunnableConfig merged into every call. Useful for attaching a persistent thread_id or tags at construction time.
name
Human-readable name shown in diagrams and traces. Defaults to assistant_id.
distributed_tracing
Forward LangSmith tracing headers so server-side spans appear under the local trace.
Provide url, or the client for the methods you call (sync_client for invoke/stream, client for ainvoke/astream). The constructor accepts neither; the first call then raises ValueError: Sync client is not initialized: please provide url or sync_client ....
With a list of modes, a local graph yields (mode, data) tuples, but RemoteGraph (with the default version="v1") yields the SDK’s StreamPart named tuples, which have three fields (event, data, id), so for mode, data in ... fails with ValueError: too many values to unpack. Use version="v2" for the same typed dicts a local graph gives you:
# Multiple modes, async, typed parts:
asyncfor part in remote.astream(
{"messages":[("user","hi")]},
{"configurable":{"thread_id":"t-1"}},
stream_mode=["updates","messages"],
version="v2",
):
if part["type"]=="messages":
msg, meta = part["data"]
print(msg["content"],end="",flush=True)# msg is a dict
The pattern is identical to a local graph — interrupt() on the server pauses execution and the Interrupt surfaces in StateSnapshot.interrupts and the __interrupt__ key of stream_mode="updates".
from langgraph.types import Command, interrupt
cfg ={"configurable":{"thread_id":"t-human"}}
# First call — triggers an interrupt on the server
for chunk in remote.stream({"query":"Analyse financials"}, cfg):
if"__interrupt__"in chunk:
question = chunk["__interrupt__"][0]["value"]# dicts over the wire
print("Server asks:", question)
# get_state() returns Interrupt objects
print(remote.get_state(cfg).interrupts[0].value)
# Resume with the human's answer
result = remote.invoke(Command(resume="Approve"), cfg)
builder.add_node("summariser", summariser)# RemoteGraph as node
builder.add_edge(START,"prepare")
builder.add_edge("prepare","summariser")
builder.add_edge("summariser", END)
graph = builder.compile()
result = graph.invoke({"messages":[("user","Summarise: ...")]})
When used as a node, RemoteGraph forwards the parent’s config, and the parent’s thread_id becomes the remote thread’s ID (created if missing). Without a thread_id the remote run is stateless. The remote output goes through the parent’s reducers, so add_messages turns the message dicts back into AIMessage objects.
Set distributed_tracing=True to propagate the LangSmith trace from your local process into the remote deployment, so all spans appear under a single trace:
remote = RemoteGraph(
"my_agent",
url="https://my-deployment.langsmith.com",
distributed_tracing=True,
)
Under the hood, RemoteGraph merges the current LangSmith run tree’s tracing headers into each request when one is active.
url is required for auto-created clients. If you pass neither url nor an explicit client / sync_client, the constructor succeeds but every method call raises ValueError.
Outputs are JSON. Read result["messages"][-1]["content"], not .content, unless the RemoteGraph runs as a node under add_messages.
Multi-mode stream yields StreamPart(event, data, id) tuples in v1. Pass version="v2" and read part["type"] / part["data"].
assistant_id is positional-only. You cannot write RemoteGraph(assistant_id="x", url=...) — the first arg has no keyword form.
Thread-ID must come from the caller. The server has its own checkpointer and keeps state per thread. Without a thread_id each call is stateless.
Subgraph threads. As a node, the RemoteGraph uses the parent’s thread_id as the remote thread ID, so two parents that share a thread ID also share the remote thread.
name defaults to assistant_id. Always pass name= when adding as a node; the Mermaid diagram shows assistant_id otherwise, which is usually a UUID.
astream_events only supports version="v3". With "v1"/"v2" it raises NotImplementedError; use astream with the appropriate stream_mode.
distributed_tracing=True needs an active LangSmith run. Without one there are no tracing headers to send; no error is raised.
params= are passed as HTTP query parameters. Useful for server-side feature flags or route selection, but their interpretation is deployment-specific.
subgraphs=True on stream exposes inner namespace paths. The namespace tuples include the server-side task IDs, which change on each run. Filter by node name prefix, not the full tuple.