Как создать LangGraph-агента с учетом приватности, проверкой вызовов инструментов и восстановлением
Практическое руководство по проверке действий с участием человека, контрольным точкам, ограничению запусков и безопасной работе с учетными данными в агенте LangGraph, обрабатывающем конфиденциальные данные.
Кратко · 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 для диагностики инцидентов: используйте инструменты только для чтения, ограничьте выполнение, показывайте ошибки и требуйте подтверждения перед рискованными действиями.