Как LangGraph Studio помогает при визуальной отладке агентских воркфлоу?

Что такое LangGraph Studio

LangGraph Studio — desktop-приложение (macOS) и облачный UI в LangSmith, которое подключается к локально запущенному LangGraph API-серверу. Оно визуализирует структуру графа, показывает пошаговое выполнение, текущий State и историю checkpoint-ов, позволяет вмешиваться в выполнение.

Как подключить Studio к проекту

Нужен конфигурационный файл langgraph.json в корне проекта и запущенный dev-сервер:

{
  "dependencies": ["."],
  "graphs": {
    "agent": "./my_agent/graph.py:graph"
  },
  "env": ".env"
}

# Запуск dev-сервера (порт 8123)
langgraph dev --port 8123

# Studio подключается автоматически по localhost:8123
# или через облачный URL в LangSmith

Основные возможности отладки

• Graph View — интерактивная схема узлов и рёбер; активный узел подсвечивается в реальном времени.
• State Inspector — JSON-просмотр полного State после каждого узла; можно сравнить «до» и «после».
• Thread History — список всех checkpoint-ов по thread_id; можно кликнуть на любой и посмотреть состояние в тот момент.
• Time Travel — откат к произвольному checkpoint-у через graph.update_state и запуск с изменённым State.
• Human-in-the-Loop — граф останавливается на interrupt_before узлах; Studio показывает pending action и позволяет одобрить/отклонить.

Пример: добавить interrupt и отладить через Studio

from langgraph.graph import StateGraph, START, END
from langgraph.checkpoint.memory import MemorySaver
from typing_extensions import TypedDict

class State(TypedDict):
    query: str
    result: str

def search_node(state: State) -> dict:
    # Studio остановится ПЕРЕД этим узлом для проверки
    return {"result": f"found: {state['query']}"}

def format_node(state: State) -> dict:
    return {"result": state["result"].upper()}

builder = StateGraph(State)
builder.add_node("search", search_node)
builder.add_node("format", format_node)
builder.add_edge(START, "search")
builder.add_edge("search", "format")
builder.add_edge("format", END)

# interrupt_before — граф паузируется перед search
graph = builder.compile(
    checkpointer=MemorySaver(),
    interrupt_before=["search"]
)

config = {"configurable": {"thread_id": "debug-session-1"}}

# Первый invoke: остановится на interrupt
graph.invoke({"query": "LangGraph Studio", "result": ""}, config=config)

# В Studio можно изменить state["query"] и продолжить:
graph.update_state(config, {"query": "MODIFIED QUERY"})
graph.invoke(None, config=config)  # продолжение с изменённым state

Интеграция с LangSmith для трейсинга

# .env — переменные для автоматического трейсинга
LANGSMITH_API_KEY=lsv2_...
LANGSMITH_TRACING_V2=true
LANGSMITH_PROJECT=my-agent-debug

После этого каждый запуск отображается в LangSmith UI: дерево вызовов, latency каждого узла, токены LLM, tool call inputs/outputs и ошибки.

Подводные камни

• Studio работает только с компилированным графом, у которого есть checkpointer; без него history и time travel недоступны.
• langgraph dev поднимает сервер с hot-reload, но изменения схемы State требуют перезапуска — Studio не видит новые поля автоматически.
• interrupt_before/interrupt_after работают только при передаче конфига с thread_id; без него граф выполняется насквозь.
• В Studio macOS-версии нельзя подключиться к удалённому серверу напрямую без туннеля (ngrok / cloudflare tunnel).
• MemorySaver теряет state при перезапуске сервера; для стабильной отладки между сессиями используйте SqliteSaver с файлом на диске.
• Большие State (тысячи сообщений) замедляют рендер JSON в Studio — обрезайте историю редьюсером или используйте messages[-20:].
• LangGraph API-сервер слушает на 8123, но не защищён аутентификацией в dev-режиме — не запускайте с открытым портом на prod-машине.
• Версии langgraph и langgraph-cli должны совпадать; рассинхронизация даёт 422 Unprocessable Entity при запуске графа из Studio.

• Объяснять langgraph studio только синтаксисом без shape, dtype, состояния или режима выполнения.
• Игнорировать leakage, воспроизводимость, пустые входы и скрытые копии данных.
• Не проверять production-симптомы: latency, память, ретраи, дрейф качества и несовпадение версий.

• Может ли связать langgraph studio с реальным контрактом входов и выходов.
• Упоминает ли тесты, метрики, reproducibility и диагностику ошибок.
• Видит ли различие между demo-кодом в ноутбуке и production-пайплайном.