Самое важное из мира AI — в канале MAX AgentLabОтдельные разборы, инструменты и практические схемы Читайте Agent Lab в Telegram Разборы, кейсы и новости о практических AI-агентах без лишней воды.
Практика LangGraph До 12 минут

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

Как защитить human-in-the-loop от устаревших подтверждений в LangGraph
Temporary fallback cover; replace in editorial pass.

Human-in-the-loop полезен там, где агенту нельзя самостоятельно выполнить рискованное действие. Но одно только наличие паузы не гарантирует безопасность: человек может ответить на старую версию вопроса, а граф уже успеет повториться, изменить план или сформировать новый запрос.

В этой статье соберём минимальный защитный слой вокруг interrupt(). Каждый запрос на подтверждение будет содержать идентификатор запроса, ревизию плана и отпечаток полезной нагрузки. При возобновлении граф сверит эти поля с текущим ожиданием и откажется принимать устаревший ответ.

Почему обычного «да» недостаточно

В LangGraph выполнение приостанавливается на interrupt(), а затем продолжается через Command(resume=...). Значение, переданное в resume, возвращается из вызова interrupt() внутри узла.

Если приложение передаёт в resume только строку вроде "approved", сама строка не говорит, к какому запросу она относится. После повтора узла или пересборки плана такое подтверждение может быть применено к другой операции.

Безопасная модель должна проверять как минимум:

Важно: эти поля не заменяют авторизацию и контроль доступа. Они решают более узкую задачу — не дать ответу из одного контекста пройти проверку в другом.

Воспроизводимый пример

Ниже приведён компактный пример для 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 до того, как проверка ответа завершилась успешно.

Безопасная последовательность выглядит так:

  1. Сформировать актуальный план и существенные параметры операции.
  2. Создать interrupt-запрос с идентичностью.
  3. Приостановить выполнение.
  4. Получить ответ человека.
  5. Сверить идентичность ответа с текущим запросом.
  6. Только после успешной проверки выполнить действие.

Если бизнес-данные могут измениться между показом запроса и ответом человека, одного хеша из исходного состояния мало. Перед фактическим действием повторно загрузите актуальные данные и убедитесь, что они всё ещё соответствуют подтверждённой операции.

Типовые ошибки

Подтверждение только по булевому флагу

Ответ {"approved": true} не содержит связи с вопросом. Добавьте идентичность запроса и проверяйте её на сервере.

Идентификатор хранится только в браузере

Клиентский интерфейс может быть закрыт, продублирован или отправить старую форму. Сервер должен извлекать ожидающий запрос из состояния графа или из доверенного хранилища, а не принимать эталонные значения от клиента.

В хеш попадает слишком мало данных

Если отпечаток включает только название действия, но не включает получателя, сумму, права или параметры, изменение этих полей не будет обнаружено. Состав payload нужно определить по риску конкретной операции.

Ожидание не привязано к thread_id

Нестабильный или повторно используемый thread_id может смешать состояния разных запусков. Выберите правило владения thread_id и проверяйте, что возобновление выполняется в правильном пользовательском или рабочем контексте.

Ограничения паттерна

Такой тест защищает от устаревшего или перемещённого между контекстами ответа, но не решает все проблемы human-in-the-loop. Он не заменяет проверку полномочий, защиту от повторной отправки, аудит, транзакционность, блокировку конкурентных изменений и валидацию бизнес-правил.

Для критичных действий добавьте одноразовость подтверждения: после успешной проверки сохраните факт использования request_id и отклоняйте повторную отправку того же ответа. Для конкурентных изменений используйте версию записи или другой механизм optimistic locking.

Проверка результата

Минимальный критерий готовности:

Главная идея проста: подтверждать нужно не абстрактное действие, а конкретный снимок запроса. Если агент изменил план, пользователь ответил на другой экран или старый callback пришёл позже нового, проверка идентичности должна остановить выполнение до побочного эффекта.

Дополнительные практические материалы: гайды Agent Lab Journal и глоссарий терминов.