Assistants

1 什么是 Assistants 及其核心价值

Assistant 是 LangGraph Platform 提供的一个概念：它将"图（Graph）"与"配置（Configuration）"绑定在一起，持久化存储到 PostgreSQL，并分配一个唯一的 assistant_id。

一句话理解：同一张图 + 不同 config = 不同的 Assistant。

• 不需要为每种业务场景部署一个新图，只需创建不同的 Assistant 实例
• 每个 Assistant 独立版本化——修改配置会产生新版本，旧版本可回溯
• 不同 Assistant 持有各自的线程（Thread）和记忆（Store），数据天然隔离

2 前提：图的 Configuration 设计

Assistants 依赖图内部定义的 configurable 字段。task_mAIstro 图在 configuration.py 中声明了三个可配置字段，并在节点内读取它们：

# configuration.py（简化）
from dataclasses import dataclass, field
from langgraph.config import get_configurable

@dataclass
class Configuration:
    user_id: str = "default_user"
    todo_category: str = "general"      # "personal" | "work" | ...
    task_maistro_role: str = ""          # 系统提示词中的角色说明

# 在图节点内读取
config = Configuration(**get_configurable())

3 创建 Assistant（create）

使用 client.assistants.create() 创建一个 Assistant，传入图名称和初始配置。

from langgraph_sdk import get_client

client = get_client(url="http://localhost:8123")

# 创建 personal 助手（version 1）
personal_assistant = await client.assistants.create(
    "task_maistro",   # 已部署的图名称
    config={"configurable": {"todo_category": "personal"}}
)
print(personal_assistant["assistant_id"])   # uuid
print(personal_assistant["version"])         # 1

create() 返回的对象包含 assistant_id、version、config 等字段，并持久化到 PostgreSQL。

4 版本化更新 Assistant（update）

使用 client.assistants.update() 为已有 Assistant 添加新配置，每次调用都会生成一个新版本，旧版本自动保留。

task_maistro_role = """You are a friendly and organized personal task assistant.

- When providing a 'todo summary':
  1. List tasks grouped by deadline (overdue, today, this week, future)
  2. Highlight tasks missing deadlines
- Proactively ask for deadlines when new tasks lack them
- Tone: encouraging and supportive"""

configurations = {
    "todo_category": "personal",
    "user_id": "lance",
    "task_maistro_role": task_maistro_role,
}

personal_assistant = await client.assistants.update(
    personal_assistant["assistant_id"],   # 传入已有 ID
    config={"configurable": configurations}
)
print(personal_assistant["version"])  # 2

5 实战：Personal 与 Work 两个助手

task_mAIstro 的典型用例：用两个 Assistant 分别管理个人任务和工作任务，相互隔离。

Work Assistant 示例：强制要求截止日期

user_input = "Create another ToDo: Finalize set of report generation tutorials."
thread = await client.threads.create()

async for chunk in client.runs.stream(
    thread["thread_id"],
    work_assistant_id,   # 使用 work assistant 的 ID
    input={"messages": [HumanMessage(content=user_input)]},
    stream_mode="values"
):
    if chunk.event == 'values':
        convert_to_messages(chunk.data["messages"])[-1].pretty_print()

# 用户在同一线程回复截止日期
user_input = "OK, for this task let's get it done by next Tuesday."
async for chunk in client.runs.stream(
    thread["thread_id"],   # 复用同一线程，保持上下文
    work_assistant_id,
    input={"messages": [HumanMessage(content=user_input)]},
    stream_mode="values"
):
    if chunk.event == 'values':
        convert_to_messages(chunk.data["messages"])[-1].pretty_print()

Personal Assistant 示例：鼓励式 ToDo 汇总

user_input = "Give me a todo summary."
thread = await client.threads.create()
async for chunk in client.runs.stream(
    thread["thread_id"],
    personal_assistant_id,   # 切换到 personal assistant
    input={"messages": [HumanMessage(content=user_input)]},
    stream_mode="values"
):
    if chunk.event == 'values':
        convert_to_messages(chunk.data["messages"])[-1].pretty_print()

6 搜索与管理 Assistants

所有 Assistant 持久化在 PostgreSQL 中，可以随时通过 SDK 查询和删除。

搜索所有 Assistants

assistants = await client.assistants.search()
for assistant in assistants:
    print({
        'assistant_id': assistant['assistant_id'],
        'version': assistant['version'],
        'config': assistant['config']
    })

删除 Assistant

# 先创建一个临时 assistant
temp_assistant = await client.assistants.create(
    "task_maistro",
    config={"configurable": configurations}
)

# 删除它
await client.assistants.delete(temp_assistant["assistant_id"])

# 确认已删除
assistants = await client.assistants.search()
print(len(assistants))  # 回到删除前的数量

通过 search 获取 assistant_id

# 按返回顺序分配（通常按创建时间倒序）
work_assistant_id     = assistants[0]['assistant_id']
personal_assistant_id = assistants[1]['assistant_id']

在生产环境中，建议将 assistant_id 持久化到应用数据库，而不是每次从 search() 推断索引——多人协作时顺序可能不稳定。

7 架构总结与适用场景