RemoteGraph는 배포와 로컬 graph처럼 상호작용할 수 있게 해주는 클라이언트 측 인터페이스입니다. CompiledGraph와 API 동등성을 제공하므로, 개발 환경과 프로덕션 환경에서 동일한 메서드(invoke(), stream(), get_state() 등)를 사용할 수 있습니다. 이 페이지에서는 RemoteGraph를 초기화하고 상호작용하는 방법을 설명합니다. RemoteGraph는 다음과 같은 경우에 유용합니다:
  • 개발과 배포의 분리: CompiledGraph로 로컬에서 graph를 빌드하고 테스트한 후 LangSmith에 배포하고, 동일한 API 인터페이스로 작업하면서 프로덕션에서 RemoteGraph를 사용하여 호출합니다.
  • Thread 레벨 지속성: Thread ID를 사용하여 호출 간에 대화의 상태를 유지하고 가져옵니다.
  • Subgraph 임베딩: 다른 graph 내에서 RemoteGraph를 subgraph로 임베드하여 멀티 에이전트 워크플로우를 위한 모듈식 graph를 구성합니다.
  • 재사용 가능한 워크플로우: 배포된 graph를 node 또는 tool로 사용하여 복잡한 로직을 재사용하고 노출할 수 있습니다.
중요: 동일한 배포 호출 방지RemoteGraph는 다른 배포의 graph를 호출하도록 설계되었습니다. RemoteGraph를 사용하여 자기 자신이나 동일한 배포의 다른 graph를 호출하지 마세요. 이는 교착 상태와 리소스 고갈로 이어질 수 있습니다. 대신 동일한 배포 내의 graph에는 로컬 graph 구성 또는 subgraph를 사용하세요.

​
사전 요구 사항

RemoteGraph를 시작하기 전에 다음이 필요합니다:
  • Graph가 개발되고 관리되는 LangSmith에 대한 액세스
  • 원격 상호작용을 위해 배포된 graph를 호스팅하는 실행 중인 LangGraph Server

​
Graph 초기화

RemoteGraph를 초기화할 때 항상 다음을 지정해야 합니다:
  • name: 상호작용하려는 graph의 이름 또는 assistant ID. Graph 이름을 지정하면 기본 assistant가 사용됩니다. Assistant ID를 지정하면 해당 특정 assistant가 사용됩니다. Graph 이름은 배포의 langgraph.json 구성 파일에서 사용하는 것과 동일한 이름입니다.
  • api_key: 유효한 LangSmith API key. 환경 변수(LANGSMITH_API_KEY)로 설정하거나 api_key 인수에 직접 전달할 수 있습니다. LangGraphClient / SyncLangGraphClient가 api_key 인수로 초기화된 경우 client / sync_client 인수에서도 API key를 제공할 수 있습니다.
또한 다음 중 하나를 제공해야 합니다:
  • url: 상호작용하려는 배포의 URL. url 인수를 전달하면 제공된 URL, header(제공된 경우) 및 기본 구성 값(예: timeout)을 사용하여 동기 및 비동기 client가 모두 생성됩니다.
  • client: 배포와 비동기적으로 상호작용하기 위한 LangGraphClient 인스턴스(예: .astream(), .ainvoke(), .aget_state(), .aupdate_state() 사용).
  • sync_client: 배포와 동기적으로 상호작용하기 위한 SyncLangGraphClient 인스턴스(예: .stream(), .invoke(), .get_state(), .update_state() 사용).
client 또는 sync_client와 url 인수를 모두 전달하면 url 인수보다 우선합니다. client / sync_client / url 인수가 모두 제공되지 않으면 RemoteGraph는 런타임에 ValueError를 발생시킵니다.

​
URL 사용

from langgraph.pregel.remote import RemoteGraph

url = "<DEPLOYMENT_URL>"

# Using graph name (uses default assistant)
graph_name = "agent"
remote_graph = RemoteGraph(graph_name, url=url)

# Using assistant ID
assistant_id = "<ASSISTANT_ID>"
remote_graph = RemoteGraph(assistant_id, url=url)

​
Client 사용

from langgraph_sdk import get_client, get_sync_client
from langgraph.pregel.remote import RemoteGraph

url = "<DEPLOYMENT_URL>"
client = get_client(url=url)
sync_client = get_sync_client(url=url)

# Using graph name (uses default assistant)
graph_name = "agent"
remote_graph = RemoteGraph(graph_name, client=client, sync_client=sync_client)

# Using assistant ID
assistant_id = "<ASSISTANT_ID>"
remote_graph = RemoteGraph(assistant_id, client=client, sync_client=sync_client)

​
Graph 호출

RemoteGraph는 CompiledGraph와 동일한 Runnable 인터페이스를 구현하므로 compiled graph와 동일한 방식으로 사용할 수 있습니다. .invoke(), .stream(), .get_state(), .update_state() 및 비동기 변형을 포함한 전체 표준 메서드 세트를 지원합니다.

​
비동기적으로

Graph를 비동기적으로 사용하려면 RemoteGraph를 초기화할 때 url 또는 client를 제공해야 합니다.
# invoke the graph
result = await remote_graph.ainvoke({
    "messages": [{"role": "user", "content": "what's the weather in sf"}]
})

# stream outputs from the graph
async for chunk in remote_graph.astream({
    "messages": [{"role": "user", "content": "what's the weather in la"}]
}):
    print(chunk)

​
동기적으로

Graph를 동기적으로 사용하려면 RemoteGraph를 초기화할 때 url 또는 sync_client를 제공해야 합니다.
# invoke the graph
result = remote_graph.invoke({
    "messages": [{"role": "user", "content": "what's the weather in sf"}]
})

# stream outputs from the graph
for chunk in remote_graph.stream({
    "messages": [{"role": "user", "content": "what's the weather in la"}]
}):
    print(chunk)

​
Thread 레벨에서 상태 유지

기본적으로 graph 실행(예: .invoke() 또는 .stream()으로 수행된 호출)은 상태 비저장이므로 중간 checkpoint와 최종 상태가 실행 후 유지되지 않습니다. 실행의 출력을 보존하려면(예: human-in-the-loop 워크플로우를 지원하기 위해) thread를 생성하고 config 인수를 통해 해당 ID를 전달할 수 있습니다. 이는 일반 compiled graph와 동일한 방식으로 작동합니다: 
from langgraph_sdk import get_sync_client

url = "<DEPLOYMENT_URL>"
graph_name = "agent"
sync_client = get_sync_client(url=url)
remote_graph = RemoteGraph(graph_name, url=url)

# create a thread (or use an existing thread instead)
thread = sync_client.threads.create()

# invoke the graph with the thread config
config = {"configurable": {"thread_id": thread["thread_id"]}}
result = remote_graph.invoke({
    "messages": [{"role": "user", "content": "what's the weather in sf"}]
}, config=config)

# verify that the state was persisted to the thread
thread_state = remote_graph.get_state(config)
print(thread_state)

​
Subgraph로 사용

RemoteGraph subgraph node가 있는 graph와 함께 checkpointer를 사용해야 하는 경우 thread ID로 UUID를 사용해야 합니다.
Graph는 여러 RemoteGraph 인스턴스를 subgraph node로 호출할 수도 있습니다. 이를 통해 서로 다른 책임이 별도의 graph로 분할되는 모듈식의 확장 가능한 워크플로우를 구현할 수 있습니다. RemoteGraph는 일반 CompiledGraph와 동일한 인터페이스를 노출하므로 다른 graph 내에서 subgraph로 직접 사용할 수 있습니다. 예를 들어: 
from langgraph_sdk import get_sync_client
from langgraph.graph import StateGraph, MessagesState, START
from typing import TypedDict

url = "<DEPLOYMENT_URL>"
graph_name = "agent"
remote_graph = RemoteGraph(graph_name, url=url)

# define parent graph
builder = StateGraph(MessagesState)
# add remote graph directly as a node
builder.add_node("child", remote_graph)
builder.add_edge(START, "child")
graph = builder.compile()

# invoke the parent graph
result = graph.invoke({
    "messages": [{"role": "user", "content": "what's the weather in sf"}]
})
print(result)

# stream outputs from both the parent graph and subgraph
for chunk in graph.stream({
    "messages": [{"role": "user", "content": "what's the weather in sf"}]
}, subgraphs=True):
    print(chunk)
Edit the source of this page on GitHub.
Connect these docs programmatically to Claude, VSCode, and more via MCP for real-time answers.
⌘I