Создание агента LangGraph с вызовом инструментов, ограничением шагов и проверкой человеком
Практический подход к оценке агента LangGraph с вызовом инструментов: явное ограничение числа шагов, одобрение рискованных действий человеком и повторяемые тестовые сценарии.
Кратко · TL;DR
Ограничьте выполнение агента числом шагов графа, приостанавливайте рискованные вызовы инструментов с помощью HumanInTheLoopMiddleware и проверяйте поведение на небольшом фиксированном наборе тестов: одобрение, отклонение и достижение лимита. Считайте примеры отправной точкой: поведение модели и инструментов нужно проверять в собственной среде.
Главное
- Лимит рекурсии графа задаёт чёткую границу выполнения агента, но не гарантирует, что он завершит задачу.
- Проверка человеком может приостановить выполнение инструмента и возобновить его позже, если у графа есть checkpointer и thread ID.
- Чтобы оценки можно было повторять, фиксируйте тестовые входные данные, ожидаемые результаты, заглушки инструментов и лимит выполнения.
- Проверяйте отклонённые действия и исчерпание лимита отдельно: ни то ни другое не означает успешного восстановления.
В этой статье (6)
Для агента с вызовом инструментов недостаточно хорошего промпта: ему нужны граница выполнения, план обработки рискованных действий и тесты, позволяющие воспроизводить его поведение. В LangGraph можно сочетать лимит рекурсии графа с проверкой человеком (HITL) для выбранных инструментов. Затем оценивайте рабочий процесс на фиксированных сценариях, а не по нескольким удачным запускам.
Пример ниже носит иллюстративный характер и не является проверенной конфигурацией. Предполагается, что у вас есть среда Python с совместимыми пакетами LangChain и LangGraph, чат-модель с поддержкой вызова инструментов и реализованный вами инструмент. Проверьте версии и параметры поставщика модели в собственной среде.
Сначала задайте границу выполнения, затем добавляйте инструменты
Лимит рекурсии ограничивает число шагов выполнения графа. Это граница безопасности, а не гарантия завершения задачи агентом и не точный лимит числа вызовов инструментов: подсчёт шагов зависит от структуры графа. Если выполнение достигнет лимита, ожидайте ошибку рекурсии графа и обрабатывайте такой запуск как незавершённый. Не считайте его ответ успешным.
Во время оценки начните с небольшого лимита и повышайте его только тогда, когда тестовый сценарий показывает, что рабочему процессу нужны дополнительные шаги. Также ограничивайте область действия операций инструментов. Лимит на уровне графа не отменит побочный эффект, который инструмент уже произвёл.
Настройте вызов инструмента с возможностью приостановки для проверки
В этом примере используется create_agent с HITL middleware. Инструмент write_file приостанавливается до одобрения или отклонения, а read_data — нет. Реализации инструментов и имя модели приведены как заполнители. Убедитесь, что выбранная модель и endpoint поддерживают нужные агенту параметры и поведение при вызове инструментов.
from langchain.agents import create_agent
from langchain.agents.middleware import HumanInTheLoopMiddleware
from langgraph.checkpoint.memory import InMemorySaver
# Replace these placeholders with your own tool implementations.
tools = [write_file, read_data]
agent = create_agent(
model="your-tool-capable-chat-model",
tools=tools,
middleware=[
HumanInTheLoopMiddleware(
interrupt_on={
"write_file": {"allowed_decisions": ["approve", "reject"]},
"read_data": False,
}
)
],
checkpointer=InMemorySaver(),
)
config = {
"configurable": {"thread_id": "evaluation-case-001"},
"recursion_limit": 8,
}
result = agent.invoke(
{"messages": [{"role": "user", "content": "Save the approved summary."}]},
config=config,
version="v2",
)
InMemorySaver подходит для прототипа или теста, выполняющегося в одном процессе; данные не сохраняются после перезапуска процесса. Для развёрнутого рабочего процесса используйте постоянный checkpointer. В руководстве LangChain по HITL указано, что для приостановки и возобновления выполнения нужны checkpointer и thread ID. Источник: Human-in-the-loop.
Когда запуск возвращает interrupt, покажите проверяющему запрошенное действие и его аргументы. Возобновите тот же thread, передав решение. Порядок решений должен соответствовать порядку действий в interrupt. Если вы запрещаете действие, отклоните его: respond предназначен для передачи ответа человека в качестве результата инструмента, а не для запрета побочного эффекта.
from langgraph.types import Command
# Use the same config, including the same thread ID, to resume.
result = agent.invoke(
Command(resume={"decisions": [{"type": "reject", "message": "Outside the approved scope."}]}),
config=config,
version="v2",
)
Сделайте оценку воспроизводимой
Храните небольшой набор тестов в системе контроля версий. Для каждого сценария укажите запрос пользователя, ожидаемое поведение инструмента, необходимость проверки человеком и ожидаемый итоговый статус. Для тестов используйте безопасные фикстуры или имитации инструментов; не позволяйте тестовым сценариям записывать данные в реальные файлы или изменять рабочие данные.
| Сценарий | Настройка | Ожидаемый результат |
|---|---|---|
| Безопасное чтение | Запросить данные через read_data | Прерывания HITL нет; возвращается результат инструмента |
| Запись с проверкой | Запросить разрешённую запись | До выполнения записи появляется interrupt; одобрение разрешает выполнение |
| Отклонённая запись | Запросить запись, затем отклонить её | Инструмент записи не запускается; агент получает обратную связь об отклонении |
| Граница лимита шагов | Использовать фикстуру, из-за которой рабочий процесс не завершается | Запуск останавливается на заданной границе и отмечается как незавершённый |
Для каждого запуска записывайте ID сценария, заданный лимит, вызовы инструментов, решения по interrupt, статус завершения и возможные ошибки. Сравнивайте эти данные с ожидаемыми результатами. Не оценивайте запуск только по итоговому ответу на естественном языке: агент может выдать правдоподобный ответ после неправильного действия.
Обработка сбоев: приостановить, отклонить или остановить
HITL — это контролируемая приостановка, а не универсальный механизм повторных попыток. В зависимости от настроенной политики проверяющий может одобрить действие, отредактировать его, отклонить или ответить. При отклонении запрошенный вызов инструмента пропускается, а агент получает обратную связь об отклонении. Продолжит ли агент работу, запросит ли другое действие или завершится с ошибкой — зависит от его дальнейшего поведения, поэтому протестируйте этот путь.
Если граф достигнет лимита рекурсии, отметьте запуск как сбой по лимиту и изучите его состояние и историю вызовов инструментов. Не запускайте его автоматически повторно, если он мог уже произвести побочные эффекты. По возможности делайте инструменты идемпотентными или перед повторением операции требуйте отдельной проверки. В приведённой документации описаны приостановка и возобновление с контрольной точкой, но не автоматическое восстановление после произвольных сбоев инструмента или модели.
Список для устранения неполадок
- Interrupt не появляется: Проверьте, совпадает ли имя инструмента с записью в
interrupt_onи разрешает ли его политика проверку. - При возобновлении не удаётся найти приостановленный запуск: Убедитесь, что используются тот же checkpointer и тот же thread ID.
- Запуск останавливается раньше времени: Проверьте заданный лимит рекурсии и путь в графе; повышайте лимит только при наличии обоснования в тестовом сценарии.
- Кажется, что отклонённое действие всё же выполнено: Убедитесь, что инструмент не был вызван до проверки и что проверяющий выбрал
reject, а неrespond. - Результаты тестов различаются между запусками: Зафиксируйте фикстуры инструментов и входные данные тестов, а также контролируйте или подменяйте ответы модели, если это возможно в вашей конфигурации. Одни лишь фиксированные входные данные не делают вывод модели детерминированным.
Практическое правило
Используйте лимит рекурсии, чтобы ограничить работу графа, HITL — чтобы контролировать значимые вызовы инструментов, а небольшой явный набор тестов — чтобы проверять как штатный путь, так и сценарии сбоев. Считайте приостановленные, отклонённые и остановленные из-за лимита запуски разными исходами. Это упрощает оценку агента и делает его безопаснее при изменениях.
Вопросы
Ограничивает ли лимит рекурсии LangGraph число вызовов инструментов?
Не совсем. Он ограничивает число шагов выполнения графа, а количество вызовов инструментов, которое в них укладывается, зависит от структуры графа. Считайте исчерпание лимита незавершённым запуском и тестируйте эту границу.
Что нужно для возобновления вызова инструмента после проверки человеком?
Настройте checkpointer, передайте thread ID и возобновите выполнение в том же thread и с тем же контекстом сохранения состояния. Проверяющий принимает решение по каждому прерванному действию.
Выполняет ли HITL автоматическую повторную попытку после сбоя вызова инструмента?
Нет. В документированном сценарии HITL выполнение приостанавливается для решения человека, после чего проверяемое действие либо выполняется, либо пропускается. Автоматические повторы после произвольных сбоев инструмента или модели не описаны.
Как проверить отклонённый вызов инструмента?
Используйте безопасный инструмент или его имитацию, вызовите interrupt, отклоните действие и убедитесь, что инструмент не запускался, а в данных о запуске есть обратная связь об отклонении.
Похожие статьи
Guides
Как создать LangGraph-агента с учетом приватности, проверкой вызовов инструментов и восстановлением
Практическое руководство по проверке действий с участием человека, контрольным точкам, ограничению запусков и безопасной работе с учетными данными в агенте LangGraph, обрабатывающем конфиденциальные данные.
Guides
Вызов инструментов в LangGraph: ограниченное выполнение и восстановление после сбоев
Создайте агент для производственных операций на LangGraph с вызовом инструментов, лимитами повторных попыток, подтверждением человеком и явными сценариями восстановления вместо неограниченного выполнения.
Guides
Создание ограниченного агента LangGraph для диагностики инцидентов API
Создайте агент LangGraph для диагностики инцидентов: используйте инструменты только для чтения, ограничьте выполнение, показывайте ошибки и требуйте подтверждения перед рискованными действиями.
Guides
Создание агента поддержки клиентов на LangGraph: вызов инструментов, одобрение человеком и ограничения выполнения
Практический шаблон LangGraph для маршрутизации обращений в поддержку: классификация запросов, вызов инструментов поиска, приостановка возвратов для одобрения человеком и ограничение выполнения графа.