GuidesOneMux

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

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

AI

Кратко · TL;DR

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

Главное

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

Ключевое решение: повторять автоматически или восстанавливаться по плану?

Для операций в производственных процессах самый безопасный вариант по умолчанию — не «повторять при любой ошибке», а:

  1. Повторять попытку только при ошибках, которые могут быть временными.
  2. Останавливать повторы после небольшого, явно заданного числа попыток.
  3. Переводить задачи с исчерпанным лимитом или неоднозначным результатом в состояние восстановления.
  4. Требовать подтверждения перед побочными действиями, которые могут быть дорогостоящими или необратимыми.

LangGraph подходит для этого, поскольку позволяет представить такие результаты как состояния графа, а не прятать их внутри одного большого цикла агента. Модель может предлагать вызовы инструментов, но детерминированный код решает, безопасно ли выполнить вызов, повторить его, передать на эскалацию или пропустить.

Приведённые ниже примеры иллюстрируют подходы. Это не протестированное приложение, а точные API могут различаться в зависимости от установленных версий LangGraph и LangChain.

Предварительные требования

Вам понадобятся:

  • Python и совместимые пакеты LangGraph и LangChain.
  • Чат-модель, которая поддерживает вызов инструментов через выбранную вами интеграцию.
  • Инструменты с явными схемами входных данных и предсказуемыми типами ошибок.
  • Механизм сохранения контрольных точек. InMemorySaver подходит для экспериментов; документация LangGraph рекомендует для production постоянный механизм, например AsyncPostgresSaver или MongoDBSaver.
  • Стабильный thread_id для каждого запуска рабочего процесса.

Не предоставляйте модели неограниченный доступ к учётным данным production-среды. Размещайте авторизацию, валидацию, правила идемпотентности и политику повторов внутри инструментов или middleware.

Настройте инструмент с ограниченными повторами

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

from dataclasses import dataclass
from typing import Literal

class TransientOperationError(Exception):
    pass

class PermanentOperationError(Exception):
    pass

@dataclass
class OperationResult:
    status: Literal["succeeded", "needs_recovery", "failed"]
    attempts: int
    message: str


def run_with_budget(operation, *, max_attempts: int) -> OperationResult:
    for attempt in range(1, max_attempts + 1):
        try:
            operation()
            return OperationResult("succeeded", attempt, "Operation completed")
        except PermanentOperationError as exc:
            return OperationResult("failed", attempt, str(exc))
        except TransientOperationError as exc:
            if attempt == max_attempts:
                return OperationResult(
                    "needs_recovery", attempt,
                    f"Retry budget exhausted: {exc}",
                )

    return OperationResult("needs_recovery", max_attempts, "No attempt was made")

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

Пример подходящей таблицы политик:

Класс сбояАвтоматическое действиеДействие для восстановления
Временный сетевой тайм-аутПовторить в пределах лимитаПередать на эскалацию с ID операции
Ограничение частоты запросовПовторить с учётом рекомендаций провайдераПоставить рабочий процесс в очередь или отложить его
Недопустимые аргументыНе повторятьВернуть агенту ошибку валидации
Отказ в разрешенииНе повторятьЗапросить авторизацию или остановить выполнение
Неизвестный результат после тайм-аутаНе повторять вслепуюПроверить статус по ключу идемпотентности

Добавьте вызов инструментов и подтверждение человеком

Функция LangChain create_agent использует LangGraph для выполнения под капотом. В предоставленной документации LangGraph описан HumanInTheLoopMiddleware, который может приостанавливать выбранные вызовы инструментов и возобновлять выполнение из сохранённого состояния.

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

agent = create_agent(
    model="provider:model-name",
    tools=[inspect_job, restart_job, delete_artifact],
    middleware=[
        HumanInTheLoopMiddleware(
            interrupt_on={
                "inspect_job": False,
                "restart_job": {
                    "allowed_decisions": ["approve", "reject"]
                },
                "delete_artifact": {
                    "allowed_decisions": ["approve", "edit", "reject"]
                },
            },
            interrupt_mode="per_call",
        ),
    ],
    checkpointer=InMemorySaver(),
)

В этом примере проверка выполняется без согласования, а перезапуск и удаление приостанавливаются до принятия решения. Действие approve выполняет вызов с исходными аргументами, edit изменяет аргументы перед выполнением, а reject пропускает вызов и возвращает агенту сообщение об отказе. В исходной документации также описано действие respond для работы в режиме «спросить пользователя»; его не следует использовать для запрета инструмента с побочными эффектами, поскольку оно считается успешным результатом инструмента.

Для production замените механизм сохранения в памяти постоянной реализацией и вызывайте агента со стабильным идентификатором потока:

config = {
    "configurable": {"thread_id": "ops-workflow-1842"}
}

result = agent.invoke(
    {
        "messages": [
            {
                "role": "user",
                "content": "Inspect the failed job and restart it if safe.",
            }
        ]
    },
    config=config,
    version="v2",
)

В версии v2 приостановленный результат содержит коллекцию interrupts. Покажите каждое запрошенное действие уполномоченному рецензенту, а затем возобновите тот же поток, используя документированный формат решения Command.

Соблюдайте правильный порядок повторов и согласования

В исходной документации подчёркивается важное правило для middleware: при проверке отдельных вызовов размещайте обработчик «человек в цикле» перед middleware для повторов или обработки ошибок. Иначе повтор может привести к повторному запросу рецензенту, либо недопустимый ответ может быть повторён так, будто произошёл сбой инструмента.

Рекомендуемая последовательность:

  1. Модель предлагает вызов инструмента.
  2. Политика определяет, требуется ли проверка.
  3. Рецензент подтверждает, редактирует или отклоняет вызов.
  4. Инструмент выполняется с собственным ограничением числа повторов.
  5. При успехе результат возвращается агенту; при исчерпании лимита выполнение переходит к восстановлению.

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

Добавьте состояние восстановления вместо ещё одной попытки

Когда лимит повторов исчерпан, зарегистрируйте операционное событие с идентификатором рабочего процесса, названием инструмента, числом попыток, ключом идемпотентности и последней известной ошибкой. Затем выберите один из трёх путей:

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

Не просите модель придумывать компенсирующее действие на основе неполного сообщения об ошибке. Передавайте ей структурированные данные о статусе и ограничивайте доступные инструменты.

Общий лимит выполнения на уровне графа — ещё один рубеж безопасности. Настройте лимит, поддерживаемый установленной версией LangGraph, и рассматривайте его достижение как событие, требующее восстановления, а не как повод незаметно продолжать выполнение. Это не позволит циклу «модель — инструмент» превратиться в неограниченный производственный процесс.

Список проверок при устранении неполадок

  • Рабочий процесс начинается заново: убедитесь, что используется постоянный механизм сохранения контрольных точек и неизменный thread_id.
  • Отклонённое действие всё равно выполняется: проверьте, что при возобновлении передано решение об отказе, а не respond.
  • Рецензент получает слишком много запросов: добавьте предикаты when на основе аргументов, чтобы приостанавливать только рискованные вызовы.
  • Повтор дублирует работу: добавьте идемпотентность и инструмент для проверки статуса, прежде чем повторять попытку с неизвестным результатом.
  • Один и тот же запрос на проверку появляется снова: проверьте порядок middleware и убедитесь, что обработка повторов не оборачивает неправильно границу согласования.
  • Отредактированный вызов ведёт себя неожиданно: самостоятельно проверяйте изменённые аргументы; документированная схема ответа описывает их структуру, но не обязательно обеспечивает безопасность с точки зрения бизнес-правил.

Заключение

Надёжный операционный агент на LangGraph — это рабочий процесс с чёткими ограничениями, а не чат-бот без ограничений. Установите для каждого инструмента лимит повторов, классифицируйте сбои, сохраняйте состояние, блокируйте опасные вызовы до согласования и явно предусматривайте ветвь восстановления. Тогда подтверждение человеком станет контролируемой контрольной точкой рабочего процесса, а не экстренным обходным решением.

Источники

Вопросы

Повторяет ли LangGraph автоматически каждый неудачный вызов инструмента?

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

Зачем для подтверждения человеком нужны контрольные точки?

Прерывание приостанавливает выполнение, пока ожидается решение. Механизм сохранения контрольных точек сохраняет состояние графа, чтобы тот же поток рабочего процесса можно было возобновить после подтверждения, редактирования, отклонения или прямого ответа.

В каких случаях вызов инструмента должен требовать проверки человеком?

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

Что делать после исчерпания лимита повторов?

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

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

Guides

Agentic RAG с LangGraph: вызов инструментов, указание источников и ограничение выполнения

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

阅读全文 →

Guides

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

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

阅读全文 →

Guides

Gemini 4 Hydrogen и Carbon: сравнение для рабочих процессов в production

Что доступные данные говорят о Gemini 4 Hydrogen и Carbon при работе с кодом, вызове инструментов, структурированном выводе и восстановлении рабочих процессов в production.

阅读全文 →

Guides

Как создать в n8n процесс извлечения данных с возможностью восстановления

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

阅读全文 →