GuidesOneMux

Как создать LangGraph-агента с учетом приватности, проверкой вызовов инструментов и восстановлением

Практическое руководство по проверке действий с участием человека, контрольным точкам, ограничению запусков и безопасной работе с учетными данными в агенте LangGraph, обрабатывающем конфиденциальные данные.

AI

Кратко · TL;DR

Используйте middleware LangGraph с участием человека в цикле, чтобы приостанавливать чувствительные вызовы инструментов, проверять или отклонять их, а затем возобновлять работу с контрольной точки. Дополните этот процесс строгими ограничениями для инструментов, изоляцией учетных данных и лимитом выполнения.

Главное

  • Храните учетные данные внутри реализаций инструментов; передавайте модели только минимально необходимые аргументы.
  • Требуйте проверки человеком для чувствительных запросов и операций записи, а безопасные операции чтения разрешайте без нее.
  • Используйте постоянное хранилище контрольных точек и стабильный ID потока, чтобы возобновлять прерванную работу.
  • Ограничивайте выполнение графа и делайте инструменты идемпотентными либо безопасными для повторного запуска независимо от контекста.
  • Считайте состояние в контрольных точках и данные прерывания конфиденциальными.
В этой статье (5)

Агент с учетом приватности не должен полагаться на модель в вопросе, безопасен ли вызов инструмента. Храните учетные данные отдельно от диалога, ограничивайте возможности каждого инструмента и приостанавливайте чувствительные действия для проверки человеком. Middleware LangGraph с участием человека в цикле позволяет приостанавливать и возобновлять выполнение; при этом приложение должно самостоятельно определять правила обработки данных, авторизации и ограничения выполнения.

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

1. Отделите контекст модели от учетных данных

Не добавляйте пароли, API-ключи, файлы cookie сеансов или учетные данные базы данных с неограниченными правами в промпты или аргументы инструментов. Вместо этого предоставьте инструментам узкий набор операций и получайте учетные данные из механизма управления секретами приложения непосредственно во время выполнения. Модель должна видеть только те данные, которые нужны ей для выбора действия.

Например, лучше использовать инструмент find_customer_record(customer_id), чем универсальный инструмент, принимающий произвольные SQL-запросы и данные для подключения. Проверяйте авторизацию непосредственно в инструменте: запрос пользователя сам по себе не доказывает, что ему разрешен доступ к запрошенной записи.

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

2. Настройте проверку чувствительных действий

В предоставленной документации LangChain по участию человека в цикле описано middleware, которое проверяет вызовы инструментов по заданной политике. При совпадении с условиями вызов может прервать выполнение; checkpointer сохраняет состояние графа, чтобы позднее продолжить запуск. В документации перечислены такие решения: одобрить вызов, изменить аргументы, отклонить его с обратной связью или ответить инструменту, который задает вопрос пользователю.

Ниже приведена примерная конфигурация. Замените инструменты-заглушки реализациями, которые соблюдают правила доступа и проверяют входные данные в вашем приложении.

from langchain.agents import create_agent
from langchain.agents.middleware import HumanInTheLoopMiddleware
from langgraph.checkpoint.memory import InMemorySaver

agent = create_agent(
    model="YOUR_CONFIGURED_MODEL",
    tools=[read_customer_record, update_customer_record],
    middleware=[
        HumanInTheLoopMiddleware(
            interrupt_on={
                "read_customer_record": False,
                "update_customer_record": {
                    "allowed_decisions": ["approve", "edit", "reject"]
                },
            },
            description_prefix="Review requested customer-data change",
        ),
    ],
    # For production, use a persistent checkpointer appropriate to your stack.
    checkpointer=InMemorySaver(),
)

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

Если проверять нужно только некоторые вызовы, документация также поддерживает предикат when для условных прерываний (требуется langchain>=1.3.3). Например, можно приостанавливать запись за пределами одобренной рабочей области или запрос, не предназначенный только для чтения. Не считайте проверку префикса строки полноценной политикой безопасности SQL: безопасные операции должны дополнительно обеспечиваться на уровне базы данных и инструментов.

3. Приостанавливайте, проверяйте и возобновляйте тот же запуск

Используйте стабильный ID потока, чтобы приложение могло связать ожидающую проверки операцию с нужным диалогом. Защитите этот идентификатор и интерфейс проверки: наличие ID потока не должно давать право одобрять действие.

from langgraph.types import Command

config = {"configurable": {"thread_id": "conversation-123"}}

result = agent.invoke(
    {"messages": [{"role": "user", "content": "Update this customer's address"}]},
    config=config,
    version="v2",
)

if result.interrupts:
    # Present the requested action to an authenticated reviewer.
    # Resume only after recording that reviewer's decision.
    result = agent.invoke(
        Command(resume={"decisions": [{"type": "reject", "message": "Verify the request first."}]}),
        config=config,
        version="v2",
    )

Если приостановлено несколько вызовов инструментов, порядок решений должен соответствовать порядку действий в запросе на прерывание. Используйте reject, чтобы отклонить действие с побочным эффектом. В документации предупреждается, что respond передает синтетический результат инструмента; это решение предназначено для ответа на вопрос инструмента вроде «спросить пользователя», а не для отклонения записи.

4. Ограничьте выполнение и предусмотрите восстановление

Само по себе прерывание для проверки не мешает модели снова и снова запрашивать вызовы инструментов. Установите лимит рекурсии графа для вызовов и обрабатывайте соответствующую ошибку лимита как контролируемую остановку. Точное значение зависит от нагрузки: выберите его с учетом максимально полезной последовательности шагов модели и инструментов и проверьте поведение на границе лимита.

config = {
    "configurable": {"thread_id": "conversation-123"},
    "recursion_limit": 12,
}

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

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

5. Проверка приватности и обработки сбоев

Перед запуском в production убедитесь, что:

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

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

Вопросы

Сохраняет ли middleware LangGraph с участием человека в цикле состояние приостановленного агента?

Для сохранения состояния при прерывании используется механизм persistence LangGraph. Checkpointer обязателен; для production-развертываний следует выбрать постоянное хранилище и настроить соответствующие правила доступа и хранения.

Следует ли использовать решение `respond`, чтобы отклонить чувствительный вызов инструмента?

Нет. Согласно документации, `respond` передает синтетический успешный результат инструмента и предназначен, например, для ответа инструменту, который задает вопрос пользователю. Чтобы отклонить действие с побочным эффектом, используйте `reject`.

Как сохранить конфиденциальность учетных данных в агенте LangGraph?

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

Предотвращает ли одобрение человеком бесконечную работу агента?

Нет. Middleware для одобрения проверяет настроенные вызовы инструментов. Отдельно добавьте лимит выполнения, тайм-ауты инструментов, ограничения на размер результатов и безопасную обработку повторных запусков.

Похожие статьи

Guides

Создание агента LangGraph с вызовом инструментов, ограничением шагов и проверкой человеком

Практический подход к оценке агента LangGraph с вызовом инструментов: явное ограничение числа шагов, одобрение рискованных действий человеком и повторяемые тестовые сценарии.

阅读全文 →

Guides

Создание агента поддержки клиентов на LangGraph: вызов инструментов, одобрение человеком и ограничения выполнения

Практический шаблон LangGraph для маршрутизации обращений в поддержку: классификация запросов, вызов инструментов поиска, приостановка возвратов для одобрения человеком и ограничение выполнения графа.

阅读全文 →

Guides

Вызов инструментов в LangGraph: ограниченное выполнение и восстановление после сбоев

Создайте агент для производственных операций на LangGraph с вызовом инструментов, лимитами повторных попыток, подтверждением человеком и явными сценариями восстановления вместо неограниченного выполнения.

阅读全文 →

Guides

Создание ограниченного агента LangGraph для диагностики инцидентов API

Создайте агент LangGraph для диагностики инцидентов: используйте инструменты только для чтения, ограничьте выполнение, показывайте ошибки и требуйте подтверждения перед рискованными действиями.

阅读全文 →