在本指南中，我们将展示如何创建、查看和检查线程。

​
创建线程

要运行图并持久化状态，您必须首先创建线程。

​
空线程

要创建新线程，请使用 LangGraph SDK create 方法。有关更多信息，请参阅 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)
输出： 
{
"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": {}
}

​
复制线程

如果应用中已经存在需要复用状态的线程，可以调用 copy 方法。该方法会基于当前历史创建一个全新的独立线程。有关更多背景，请参阅 Python 与 JS SDK 参考文档。
  • Python
  • Javascript
  • CURL
copied_thread = await client.threads.copy(<THREAD_ID>)

​
预填状态

还可以在 create 方法中传入 supersteps 列表，直接创建带有预设状态的线程。supersteps 用来描述一系列状态更新步骤，例如：
  • 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)
输出： 
{
"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
}
]
}
}

​
列出线程

​
LangGraph SDK

要列出线程，可调用 LangGraph SDK 的 search 方法。它会返回满足过滤条件的线程列表。更多细节请参考 Python 与 JS 文档。

​
按线程状态过滤

使用 status 字段即可按状态筛选线程。支持的状态包括 idle、busy、interrupted 与 error，可在此处查看状态含义。以下示例筛选 idle 线程：
  • Python
  • Javascript
  • CURL
print(await client.threads.search(status="idle",limit=1))
输出： 
[
{
'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': {}}
}
]

​
按元数据过滤

search 也支持基于元数据的过滤：
  • Python
  • Javascript
  • CURL
print((await client.threads.search(metadata={"graph_id":"agent"},limit=1)))
输出： 
[
{
'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': {}}
}
]

​
排序

通过 sort_by 与 sort_order 参数，可以按照 thread_id、status、created_at、updated_at 等字段排序。

​
LangSmith UI

也可以在 LangSmith UI 中查看部署里的线程。 进入部署后选择 “Threads” 标签页，即可看到该部署的线程列表。顶部可按状态筛选，点击列头上的箭头即可按支持的属性排序。

​
检查线程

​
LangGraph SDK

​
获取线程

若已知 thread_id，可以通过 get 方法查看具体线程：
  • Python
  • Javascript
  • CURL
print((await client.threads.get(<THREAD_ID>)))
输出： 
{
'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': {}}
}

​
查看线程状态

使用 get_state 方法可读取线程的当前状态：
  • Python
  • Javascript
  • CURL
print((await client.threads.get_state(<THREAD_ID>)))
输出： 
{
"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 ID（或完整 checkpoint 对象）：
  • Python
  • Javascript
  • CURL
thread_state = await client.threads.get_state(
  thread_id=<THREAD_ID>
  checkpoint_id=<CHECKPOINT_ID>
)

​
查看完整历史

若要调取线程经历过的全部状态，可使用 get_history 方法。更多说明见 Python 与 JS 参考文档。

​
LangSmith UI

同样可以在 LangSmith UI 中查看部署内的线程。 进入部署后点击 “Threads” 标签页，会加载一个包含全部线程的表格。 选择任意线程即可查看其当前状态；若想调试或回放完整历史，可在 Studio 中打开该线程。
Edit the source of this page on GitHub.
Connect these docs programmatically to Claude, VSCode, and more via MCP for real-time answers.