Как добавить безопасный tool в LangChain-агента для проверки статуса заказа

1. Определите узкую read-only функцию для статуса, которая получает order_id и проверяет его по серверной таблице разрешённых ID.
2. Оформите сигнатуру с type hints и кратким docstring, чтобы модель понимала инструмент.
3. Передайте функцию через tools в create_agent; system_prompt запретит додумывать статус без результата инструмента.
4. Запустите положительный тест по своему заказу и отрицательный по неизвестному ID.
5. Проверьте, что backend не отдаёт статусы других пользователей даже при ручной подмене аргумента.

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

Готовый шаблон на Python

from langchain.agents import create_agent
from langchain.tools import tool

# Демонстрационные данные, замените защищённым серверным источником.
ALLOWED = {"AB-417": "Передан в доставку"}

@tool
def get_order_status(order_id: str) -> str:
    """Получить статус разрешённого заказа по его ID."""
    return ALLOWED.get(order_id, "Недоступен или не найден")

agent = create_agent(model="openai:gpt-5.5", tools=[get_order_status],
    system_prompt="Не выдумывай статусы. Используй tool для номера заказа.")
result = agent.invoke({"messages": [{"role": "user", "content":
    "Где мой заказ AB-417?"}]})
print(result["messages"][-1].content)

Конкретные входные и ожидаемые данные

Вход: «Где мой заказ AB-417?» и локальная таблица с AB-417 → «Передан в доставку». Ожидается подтверждённый статус; запрос для XX-999 должен закончиться «Недоступен или не найден», без придуманного местонахождения. В production принадлежность AB-417 определяется из проверенной серверной сессии, а не из значения, которое модель вставила в функцию.

Оценивать стоит не красоту формулировки, а проверяемое выполнение задачи. Сохраните исходный текст, ID пользователя или теста и ожидаемое значение отдельно от ответа модели. Если пример выдаёт неверный факт, разберите данные на входе и состояние инструмента до изменения промпта: иначе можно замаскировать ошибку инфраструктуры удачной перефразировкой.

Диагностика и границы решения

Это критическая граница доверия: LLM не может быть арбитром полномочий. Она выбирает, когда вызвать get_order_status и какой ID передать; функция на сервере обязана отвергнуть доступ к чужому заказу независимо от текста запроса. В демонстрационном словаре доступен всего один ID, но в реальной CRM нужно проверять связь пользователя и заказа каждый раз, а не один раз при создании агента. Docstring направляет модель, но не служит security policy. Для инструментов записи — отмена заказа, изменение адреса, возврат — требуется отдельный поток подтверждения; не расширяйте read-only инструмент параметром action без анализа побочных эффектов. Ограничивайте размер и формат аргументов до обращения к БД, задавайте таймаут и журналируйте идентификатор операции без сырых секретов. Проверьте попытку prompt injection внутри названия товара: сторонний текст не должен позволить модели вызвать инструмент с чужим ID. Сравнивайте ответ агента с реальным ToolMessage и проверяйте, что никакая фантазия модели не подменяет «Недоступен». Если сервис упал, отображайте явную ошибку, а не статус «Отменён», которого система не видела.

Контрольный эксперимент

Для тестирования создайте четыре ситуации: разрешённый ID, запрещённый ID, malformed ID и временная ошибка базы. Положительный тест доказывает только функциональность; остальные определяют безопасность и честность ответа. Сохраняйте трассу с именем вызванного tool, аргументом, временем и результатом после редакции персональных данных. Если один вопрос содержит два заказа, проверяйте каждый доступ независимо. Для публичного чат-бота применяйте rate limiting на уровне API инструмента, поскольку пользователь может многократно просить модель вызывать дорогой сервис. Нельзя доверять ответу модели «я проверил заказ», если в журнале вызов get_order_status отсутствует. Наконец, выбирайте возвращаемую строку так, чтобы инструмент не раскрывал, существует ли чужой заказ: одинаковое «Недоступен или не найден» уменьшает утечку.

Дополнительный проверочный сценарий