Как защитить human-in-the-loop от устаревших подтверждений в LangGraph

Human-in-the-loop полезен там, где агенту нельзя самостоятельно выполнить рискованное действие. Но одно только наличие паузы не гарантирует безопасность: человек может ответить на старую версию вопроса, а граф уже успеет повториться, изменить план или сформировать новый запрос.
В этой статье соберём минимальный защитный слой вокруг interrupt(). Каждый запрос на подтверждение будет содержать идентификатор запроса, ревизию плана и отпечаток полезной нагрузки. При возобновлении граф сверит эти поля с текущим ожиданием и откажется принимать устаревший ответ.
Почему обычного «да» недостаточно
В LangGraph выполнение приостанавливается на interrupt(), а затем продолжается через Command(resume=...). Значение, переданное в resume, возвращается из вызова interrupt() внутри узла.
Если приложение передаёт в resume только строку вроде "approved", сама строка не говорит, к какому запросу она относится. После повтора узла или пересборки плана такое подтверждение может быть применено к другой операции.
Безопасная модель должна проверять как минимум:
- request_id — уникальный идентификатор конкретного interrupt-запроса;
- plan_revision — версию плана агента, для которой был задан вопрос;
- payload_hash — отпечаток существенных данных операции.
Важно: эти поля не заменяют авторизацию и контроль доступа. Они решают более узкую задачу — не дать ответу из одного контекста пройти проверку в другом.
Воспроизводимый пример
Ниже приведён компактный пример для Python. Он использует MemorySaver только для локального теста. Для рабочего приложения нужен постоянный checkpointer и стабильный thread_id.
1. Подготовьте окружение
python -m venv .venv
. .venv/bin/activate
python -m pip install -U langgraph pytest
Команды не создают внешние ресурсы и не требуют ключей API. Если в вашем окружении уже есть проект, выполняйте их в отдельном виртуальном окружении или используйте существующие зависимости.
2. Добавьте проверку идентичности
from __future__ import annotations
import hashlib
import json
from typing import TypedDict
from langgraph.checkpoint.memory import MemorySaver
from langgraph.graph import END, START, StateGraph
from langgraph.types import Command, interrupt
class State(TypedDict):
plan_revision: str
operation: dict
result: str
class StaleApprovalError(RuntimeError):
pass
def stable_hash(value: object) -> str:
encoded = json.dumps(
value,
ensure_ascii=False,
sort_keys=True,
separators=(",", ":"),
).encode("utf-8")
return hashlib.sha256(encoded).hexdigest()
def make_request_id(
plan_revision: str,
operation: dict,
) -> str:
return stable_hash({
"plan_revision": plan_revision,
"operation": operation,
})
def approve_operation(state: State):
plan_revision = state["plan_revision"]
operation = state["operation"]
request_id = make_request_id(plan_revision, operation)
payload_hash = stable_hash(operation)
approval_request = {
"kind": "approval",
"request_id": request_id,
"plan_revision": plan_revision,
"payload_hash": payload_hash,
"operation": operation,
}
answer = interrupt(approval_request)
if not isinstance(answer, dict):
raise StaleApprovalError("Ответ должен быть объектом с идентичностью запроса")
expected = {
"request_id": request_id,
"plan_revision": plan_revision,
"payload_hash": payload_hash,
}
received = {
key: answer.get(key)
for key in expected
}
if received != expected:
raise StaleApprovalError(
"Отклонено: подтверждение относится к другой версии запроса"
)
if answer.get("approved") is not True:
return {"result": "rejected"}
return {"result": "approved"}
builder = StateGraph(State)
builder.add_node("approve_operation", approve_operation)
builder.add_edge(START, "approve_operation")
builder.add_edge("approve_operation", END)
graph = builder.compile(checkpointer=MemorySaver())
В примере идентификатор вычисляется детерминированно из ревизии плана и операции. Это удобно для демонстрации и теста: изменение любого существенного поля создаёт другой идентификатор. В реальном приложении можно использовать случайный UUID, но тогда исходный запрос и его идентичность нужно надёжно хранить вместе с состоянием ожидания.
3. Возобновите граф корректным ответом
config = {
"configurable": {
"thread_id": "demo-thread-1",
}
}
initial_state = {
"plan_revision": "plan-7",
"operation": {
"action": "send_email",
"recipient": "user@example.test",
},
"result": "",
}
paused = graph.invoke(initial_state, config)
request = paused["__interrupt__"][0].value
approved = {
"approved": True,
"request_id": request["request_id"],
"plan_revision": request["plan_revision"],
"payload_hash": request["payload_hash"],
}
completed = graph.invoke(Command(resume=approved), config)
assert completed["result"] == "approved"
Для интерфейса подтверждения лучше передавать пользователю весь объект request, а не только текстовое описание. Поля идентичности можно показывать как технические данные или хранить в скрытых полях формы, но сервер обязан проверять их сам.
Тест на устаревший ответ
Следующий тест сначала получает interrupt-запрос для старой операции, затем пытается возобновить граф ответом, который был сформирован для другой операции. Ожидаемый результат — StaleApprovalError.
import pytest
from langgraph.types import Command
from app import StaleApprovalError, graph
def test_stale_approval_is_rejected():
config = {
"configurable": {
"thread_id": "stale-approval-test",
}
}
old_state = {
"plan_revision": "plan-7",
"operation": {
"action": "send_email",
"recipient": "old@example.test",
},
"result": "",
}
paused = graph.invoke(old_state, config)
old_request = paused["__interrupt__"][0].value
stale_answer = {
"approved": True,
"request_id": old_request["request_id"],
"plan_revision": old_request["plan_revision"],
"payload_hash": old_request["payload_hash"],
}
new_state = {
"plan_revision": "plan-8",
"operation": {
"action": "send_email",
"recipient": "new@example.test",
},
"result": "",
}
graph.invoke(new_state, config)
with pytest.raises(StaleApprovalError, match="Отклонено"):
graph.invoke(Command(resume=stale_answer), config)
Запустите тест из каталога проекта:
pytest -q
Тест проверяет именно контракт идентичности. Он не доказывает, что отправка письма, транзакция или другая бизнес-операция безопасны сама по себе.
Что происходит при повторе узла
После возобновления LangGraph может повторно выполнить код узла до точки прерывания. Поэтому код до interrupt() должен быть идемпотентным: не отправляйте письмо, не списывайте деньги и не вызывайте необратимый внешний API до того, как проверка ответа завершилась успешно.
Безопасная последовательность выглядит так:
- Сформировать актуальный план и существенные параметры операции.
- Создать interrupt-запрос с идентичностью.
- Приостановить выполнение.
- Получить ответ человека.
- Сверить идентичность ответа с текущим запросом.
- Только после успешной проверки выполнить действие.
Если бизнес-данные могут измениться между показом запроса и ответом человека, одного хеша из исходного состояния мало. Перед фактическим действием повторно загрузите актуальные данные и убедитесь, что они всё ещё соответствуют подтверждённой операции.
Типовые ошибки
Подтверждение только по булевому флагу
Ответ {"approved": true} не содержит связи с вопросом. Добавьте идентичность запроса и проверяйте её на сервере.
Идентификатор хранится только в браузере
Клиентский интерфейс может быть закрыт, продублирован или отправить старую форму. Сервер должен извлекать ожидающий запрос из состояния графа или из доверенного хранилища, а не принимать эталонные значения от клиента.
В хеш попадает слишком мало данных
Если отпечаток включает только название действия, но не включает получателя, сумму, права или параметры, изменение этих полей не будет обнаружено. Состав payload нужно определить по риску конкретной операции.
Ожидание не привязано к thread_id
Нестабильный или повторно используемый thread_id может смешать состояния разных запусков. Выберите правило владения thread_id и проверяйте, что возобновление выполняется в правильном пользовательском или рабочем контексте.
Ограничения паттерна
Такой тест защищает от устаревшего или перемещённого между контекстами ответа, но не решает все проблемы human-in-the-loop. Он не заменяет проверку полномочий, защиту от повторной отправки, аудит, транзакционность, блокировку конкурентных изменений и валидацию бизнес-правил.
Для критичных действий добавьте одноразовость подтверждения: после успешной проверки сохраните факт использования request_id и отклоняйте повторную отправку того же ответа. Для конкурентных изменений используйте версию записи или другой механизм optimistic locking.
Проверка результата
Минимальный критерий готовности:
- корректный ответ для текущего запроса приводит к продолжению графа;
- ответ со старым
request_idотклоняется; - ответ с другой
plan_revisionотклоняется; - ответ с изменённым
payload_hashотклоняется; - повторное использование уже принятого ответа обрабатывается отдельно;
- после ошибки внешнее действие ещё не было выполнено.
Главная идея проста: подтверждать нужно не абстрактное действие, а конкретный снимок запроса. Если агент изменил план, пользователь ответил на другой экран или старый callback пришёл позже нового, проверка идентичности должна остановить выполнение до побочного эффекта.
Дополнительные практические материалы: гайды Agent Lab Journal и глоссарий терминов.