이 가이드에서는 thread를 생성하고, 조회하고, 검사하는 방법을 보여드립니다.

​
thread 생성하기

graph를 실행하고 state를 유지하려면 먼저 thread를 생성해야 합니다.

​
빈 thread

새 thread를 생성하려면 LangGraph SDK의 create method를 사용하세요. 자세한 내용은 Python 및 JS SDK 참조 문서를 확인하세요.
  • Python
  • Javascript
  • CURL
from langgraph_sdk import get_client

client = get_client(url=<DEPLOYMENT_URL>)
thread = await client.threads.create()

print(thread)
Output: 
{
"thread_id": "123e4567-e89b-12d3-a456-426614174000",
"created_at": "2025-05-12T14:04:08.268Z",
"updated_at": "2025-05-12T14:04:08.268Z",
"metadata": {},
"status": "idle",
"values": {}
}

​
thread 복사하기

또는 애플리케이션에 이미 state를 복사하고 싶은 thread가 있는 경우 copy method를 사용할 수 있습니다. 이렇게 하면 작업 시점에 원본 thread와 동일한 history를 가진 독립적인 thread가 생성됩니다. 자세한 내용은 Python 및 JS SDK 참조 문서를 확인하세요.
  • Python
  • Javascript
  • CURL
copied_thread = await client.threads.copy(<THREAD_ID>)

​
미리 채워진 State

마지막으로 create method에 supersteps 목록을 제공하여 임의로 미리 정의된 state를 가진 thread를 생성할 수 있습니다. supersteps는 state 업데이트 시퀀스의 목록을 설명합니다. 예를 들어:
  • Python
  • Javascript
  • CURL
from langgraph_sdk import get_client

client = get_client(url=<DEPLOYMENT_URL>)
thread = await client.threads.create(
  graph_id="agent",
  supersteps=[
    {
      updates: [
        {
          values: {},
          as_node: '__input__',
        },
      ],
    },
    {
      updates: [
        {
          values: {
            messages: [
              {
                type: 'human',
                content: 'hello',
              },
            ],
          },
          as_node: '__start__',
        },
      ],
    },
    {
      updates: [
        {
          values: {
            messages: [
              {
                content: 'Hello! How can I assist you today?',
                type: 'ai',
              },
            ],
          },
          as_node: 'call_model',
        },
      ],
    },
  ])

print(thread)
Output: 
{
"thread_id": "f15d70a1-27d4-4793-a897-de5609920b7d",
"created_at": "2025-05-12T15:37:08.935038+00:00",
"updated_at": "2025-05-12T15:37:08.935046+00:00",
"metadata": {"graph_id": "agent"},
"status": "idle",
"config": {},
"values": {
"messages": [
{
"content": "hello",
"additional_kwargs": {},
"response_metadata": {},
"type": "human",
"name": null,
"id": "8701f3be-959c-4b7c-852f-c2160699b4ab",
"example": false
},
{
"content": "Hello! How can I assist you today?",
"additional_kwargs": {},
"response_metadata": {},
"type": "ai",
"name": null,
"id": "4d8ea561-7ca1-409a-99f7-6b67af3e1aa3",
"example": false,
"tool_calls": [],
"invalid_tool_calls": [],
"usage_metadata": null
}
]
}
}

​
thread 목록 조회하기

​
LangGraph SDK

thread 목록을 조회하려면 LangGraph SDK의 search method를 사용하세요. 이는 제공된 필터와 일치하는 애플리케이션의 thread를 나열합니다. 자세한 내용은 Python 및 JS SDK 참조 문서를 확인하세요.

​
thread status로 필터링하기

status 필드를 사용하여 status에 따라 thread를 필터링하세요. 지원되는 값은 idle, busy, interrupted, error입니다. 각 status에 대한 정보는 여기를 참조하세요. 예를 들어 idle thread를 조회하려면:
  • Python
  • Javascript
  • CURL
print(await client.threads.search(status="idle",limit=1))
Output: 
[
{
'thread_id': 'cacf79bb-4248-4d01-aabc-938dbd60ed2c',
'created_at': '2024-08-14T17:36:38.921660+00:00',
'updated_at': '2024-08-14T17:36:38.921660+00:00',
'metadata': {'graph_id': 'agent'},
'status': 'idle',
'config': {'configurable': {}}
}
]

​
metadata로 필터링하기

search method를 사용하면 metadata로 필터링할 수 있습니다:
  • Python
  • Javascript
  • CURL
print((await client.threads.search(metadata={"graph_id":"agent"},limit=1)))
Output: 
[
{
'thread_id': 'cacf79bb-4248-4d01-aabc-938dbd60ed2c',
'created_at': '2024-08-14T17:36:38.921660+00:00',
'updated_at': '2024-08-14T17:36:38.921660+00:00',
'metadata': {'graph_id': 'agent'},
'status': 'idle',
'config': {'configurable': {}}
}
]

​
정렬하기

SDK는 sort_by 및 sort_order 매개변수를 사용하여 thread_id, status, created_at, updated_at으로 thread를 정렬하는 것도 지원합니다.

​
LangSmith UI

LangSmith UI를 통해 deployment의 thread를 조회할 수도 있습니다. deployment 내에서 “Threads” 탭을 선택하세요. 그러면 deployment의 모든 thread 테이블이 로드됩니다. thread status로 필터링하려면 상단 바에서 status를 선택하세요. 지원되는 속성으로 정렬하려면 원하는 열의 화살표 아이콘을 클릭하세요.

​
thread 검사하기

​
LangGraph SDK

​
Thread 가져오기

thread_id가 주어진 특정 thread를 조회하려면 get method를 사용하세요:
  • Python
  • Javascript
  • CURL
print((await client.threads.get(<THREAD_ID>)))
Output: 
{
'thread_id': 'cacf79bb-4248-4d01-aabc-938dbd60ed2c',
'created_at': '2024-08-14T17:36:38.921660+00:00',
'updated_at': '2024-08-14T17:36:38.921660+00:00',
'metadata': {'graph_id': 'agent'},
'status': 'idle',
'config': {'configurable': {}}
}

​
Thread State 검사하기

주어진 thread의 현재 state를 조회하려면 get_state method를 사용하세요:
  • Python
  • Javascript
  • CURL
print((await client.threads.get_state(<THREAD_ID>)))
Output: 
{
"values": {
"messages": [
{
"content": "hello",
"additional_kwargs": {},
"response_metadata": {},
"type": "human",
"name": null,
"id": "8701f3be-959c-4b7c-852f-c2160699b4ab",
"example": false
},
{
"content": "Hello! How can I assist you today?",
"additional_kwargs": {},
"response_metadata": {},
"type": "ai",
"name": null,
"id": "4d8ea561-7ca1-409a-99f7-6b67af3e1aa3",
"example": false,
"tool_calls": [],
"invalid_tool_calls": [],
"usage_metadata": null
}
]
},
"next": [],
"tasks": [],
"metadata": {
"thread_id": "f15d70a1-27d4-4793-a897-de5609920b7d",
"checkpoint_id": "1f02f46f-7308-616c-8000-1b158a9a6955",
"graph_id": "agent_with_quite_a_long_name",
"source": "update",
"step": 1,
"writes": {
"call_model": {
"messages": [
{
"content": "Hello! How can I assist you today?",
"type": "ai"
}
]
}
},
"parents": {}
},
"created_at": "2025-05-12T15:37:09.008055+00:00",
"checkpoint": {
"checkpoint_id": "1f02f46f-733f-6b58-8001-ea90dcabb1bd",
"thread_id": "f15d70a1-27d4-4793-a897-de5609920b7d",
"checkpoint_ns": ""
},
"parent_checkpoint": {
"checkpoint_id": "1f02f46f-7308-616c-8000-1b158a9a6955",
"thread_id": "f15d70a1-27d4-4793-a897-de5609920b7d",
"checkpoint_ns": ""
},
"checkpoint_id": "1f02f46f-733f-6b58-8001-ea90dcabb1bd",
"parent_checkpoint_id": "1f02f46f-7308-616c-8000-1b158a9a6955"
}
선택적으로 주어진 checkpoint에서 thread의 state를 조회하려면 checkpoint id(또는 전체 checkpoint 객체)를 전달하면 됩니다:
  • Python
  • Javascript
  • CURL
thread_state = await client.threads.get_state(
  thread_id=<THREAD_ID>
  checkpoint_id=<CHECKPOINT_ID>
)

​
전체 Thread History 검사하기

thread의 history를 조회하려면 get_history method를 사용하세요. 이는 thread가 경험한 모든 state의 목록을 반환합니다. 자세한 내용은 Python 및 JS 참조 문서를 확인하세요.

​
LangSmith UI

LangSmith UI를 통해 deployment의 thread를 조회할 수도 있습니다. deployment 내에서 “Threads” 탭을 선택하세요. 그러면 deployment의 모든 thread 테이블이 로드됩니다. thread를 선택하여 현재 state를 검사하세요. 전체 history를 조회하고 추가 디버깅을 위해 Studio에서 thread를 여세요.
Edit the source of this page on GitHub.
Connect these docs programmatically to Claude, VSCode, and more via MCP for real-time answers.
⌘I