В LangChain можно собрать агента из модели и обычной Python-функции. Модель предлагает вызвать функцию с аргументами, агент выполняет её и возвращает результат модели. Покажем этот цикл на проверке остатка товара. Один инструмент читает локальный словарь, а тестовая модель возвращает заранее подготовленные сообщения.
Такой сценарий позволяет проверить передачу аргументов, выполнение функции и результат без API-ключа. Код ниже запускался с Python 3.11 и LangChain 1.5.2. Проверены три случая: товар в наличии, нулевой остаток и отсутствующий артикул. Способность реальной модели выбрать инструмент проверяется отдельно.
Установите LangChain в отдельное окружение
В новой папке создайте виртуальное окружение. На Windows его интерпретатор находится в .venv\Scripts, на Linux и macOS — в .venv/bin. Используйте его для установки пакетов и запуска примера. Это помогает избежать ситуации, когда IDE запускает другой Python и не находит уже установленную библиотеку.
python -m venv .venv
# После активации окружения
python -m pip install "langchain==1.5.2"
python -m pip show langchain
Окружение примера использует Python 3.11. В проекте, который будет запускаться на другой машине, дополнительно сохраните файл блокировки зависимостей. Указание версии LangChain закрепляет сам пакет, а версии транзитивных зависимостей могут меняться. Для учебного запуска отдельный адаптер облачной модели не требуется.
Соберите агента с одним инструментом
Сохраните файл как demo.py. Декоратор @tool превращает функцию в инструмент. Описание помогает модели понять назначение, а аннотация sku: str задаёт ожидаемый аргумент. В локальном словаре два артикула. Третий намеренно отсутствует.
from langchain.agents import create_agent
from langchain.messages import AIMessage, ToolMessage
from langchain.tools import tool
from langchain_core.language_models.fake_chat_models import GenericFakeChatModel
STOCK = {"A-17": 8, "B-02": 0}
@tool
def lookup_stock(sku: str) -> dict:
"""Look up stock by product SKU in the local demo catalog."""
normalized = sku.strip().upper()
if normalized not in STOCK:
return {"status": "not_found", "sku": normalized}
return {"status": "ok", "sku": normalized, "quantity": STOCK[normalized]}
class ScriptedModel(GenericFakeChatModel):
def bind_tools(self, tools, **kwargs):
return self
def simulate(sku: str):
model = ScriptedModel(messages=iter([
AIMessage(content="", tool_calls=[{
"name": "lookup_stock",
"args": {"sku": sku},
"id": "demo-1",
"type": "tool_call",
}]),
AIMessage(content="Учебный ответ после вызова инструмента."),
]))
agent = create_agent(
model=model,
tools=[lookup_stock],
system_prompt="Отвечай об остатках по данным инструмента.",
)
return agent.invoke(
{"messages": [{"role": "user", "content": f"Что на складе по {sku}?"}]},
config={"recursion_limit": 12},
)
if __name__ == "__main__":
for sku in ("A-17", "B-02", "X-99"):
result = simulate(sku)
for message in result["messages"]:
print(message.type, message.content)
if isinstance(message, AIMessage) and message.tool_calls:
print(" tool_calls:", message.tool_calls)
if isinstance(message, ToolMessage):
print(" tool_call_id:", message.tool_call_id)
Запустите python demo.py. Каждый вызов simulate() создаёт новый экземпляр модели с двумя ответами. Первый содержит запрос на вызов инструмента. Второй завершает цикл после получения результата. Метод bind_tools() оставляет тестовый двойник готовым к работе с переданными инструментами. У настоящего адаптера этот метод настраивает передачу схем инструментов модели. В тесте вызов задан явно, поэтому двойнику достаточно вернуть себя.
Проследите, что происходит между вопросом и ответом
- Сообщение
humanсодержит вопрос. Функцияsimulate()подаёт его в агент вместе с настройкой ограничения выполнения. - Первое сообщение
aiнесётtool_calls. Имяlookup_stockуказывает на зарегистрированный инструмент. Вargsлежит артикул, аidсвязывает запрос с результатом. - Агент выполняет Python-функцию. Сообщение
toolсодержит результат. Полеtool_call_idсовпадает с идентификатором вызова. - После этого следует итоговое
ai. Здесь это заранее написанная фраза, а рабочая модель сформировала бы ответ по содержимому предыдущих сообщений.
Для A-17 в сообщении инструмента будет quantity: 8. Для B-02 — quantity: 0. Для X-99 придёт status: not_found без количества. Это различие пригодится в реальном каталоге: нулевой остаток известного товара и неизвестный артикул требуют разных пояснений пользователю. Детали протокола разобраны в статье про вызов инструментов.
Как обработать ошибку инструмента
В примере результат not_found считается обычным исходом поиска. Для подключения к складу понадобятся и другие варианты. Если внешний сервис не ответил, удобно вернуть понятное приложению состояние, например unavailable. Тогда модель может сообщить о временной недоступности вместо того, чтобы придумывать остаток или приравнивать сбой к пустому складу.
Перехватывайте ожидаемые исключения рядом с вызовом внешнего сервиса. Неожиданные ошибки обрабатывайте на границе приложения, где можно записать безопасный диагностический идентификатор и выбрать ответ пользователю. Тело исключения может содержать адреса, фрагменты данных или секреты. В сообщении инструмента достаточно кода причины, который предусмотрен вашим контрактом.
Ограничение recursion_limit в примере задаёт предел шагов графа. Для внешнего API дополнительно задайте собственный таймаут. Например, если запрос склада завис, правило ограничения шагов само по себе не сокращает ожидание одного сетевого вызова. Также стоит проверить, как агент отвечает при повторе одного артикула и при вопросе без артикула.
Подключите модель, когда проверен сам цикл
Для рабочего варианта оставьте lookup_stock и передайте в create_agent() чат-модель с поддержкой вызовов инструментов. LangChain позволяет создать её через init_chat_model(). Установите интеграционный пакет своего провайдера и используйте идентификатор модели из его документации. Если выбран облачный провайдер, реквизиты задаются в окружении или хранилище секретов.
В вызове агенту передавайте пользовательский текст и, при необходимости, настройки выполнения. Учебный код подставляет артикул напрямую в заранее составленное сообщение модели, тогда как при реальном запуске нужно проверить, извлечёт ли модель A-17 из обычной фразы. Для этого повторите те же сценарии с разными формулировками и сохраните отдельно факт вызова, его аргументы и понятность итогового ответа.
Технический тест и оценка поведения отвечают на разные вопросы. Технический тест проверяет, что инструмент вообще вызывается и возвращает ожидаемое значение. Оценка поведения показывает, когда модель решает его вызвать и как пересказывает результат. Для второго этапа можно использовать подход из статьи про проверку ИИ-агентов.
Где проходит граница с LangGraph
create_agent() даёт готовый цикл LangChain для вызова модели и инструментов. Внутри он работает на LangGraph. Если в приложении достаточно зарегистрировать модель, инструменты и правила выполнения, этот интерфейс скрывает большую часть работы с графом.
К LangGraph напрямую имеет смысл перейти при необходимости задать собственные этапы и переходы. Например, сначала проверить заказ и разрешения, затем запросить человека о подтверждении и только потом передать команду сервису. Для учебного поиска остатков код остаётся коротким: один инструмент чтения, три проверяемых исхода и история сообщений, по которой видно, на каком шаге возникла проблема.
При первом запуске начните с одного известного артикула и сравните результат функции с сообщением агента. Добавляйте остальные сценарии по одному. Так при смене версии модели или библиотеки будет проще понять, какой этап изменился: модель выбрала другой аргумент, инструмент вернул новый формат или итоговый ответ потерял важную оговорку.
Частые вопросы
Да. ScriptedModel воспроизводит два заданных ответа локально. Python-инструмент действительно выполняется.
В AIMessage будет tool_calls с именем и аргументами, а в ToolMessage — результат с совпадающим tool_call_id.
Инструмент возвращает not_found без количества. Известный товар с нулевым остатком возвращается со статусом ok.
Нет. create_agent создаёт готовый цикл на LangGraph. Свой граф нужен, когда важно явно задать этапы и переходы.
Источники
- 1.LangChain: агентыhttps://docs.langchain.com/oss/python/langchain/agents
- 2.LangChain: тестовые моделиhttps://docs.langchain.com/oss/python/langchain/test/unit-testing
- 3.LangChain: чат-моделиhttps://docs.langchain.com/oss/python/langchain/models
- 4.LangChain 1.5.2 на PyPIhttps://pypi.org/project/langchain/1.5.2/



