Документация по Agentic AI в LangChain: инструменты и JSON-режим
Большая часть документации по Agentic AI в LangChain предполагает использование класса модели от конкретного поставщика, но любой OpenAI-совместимый эндпоинт работает с ChatOpenAI после установки base URL. Это руководство подключает LangChain к этому API и пошагово создает агента с вызовом функций.
Обновлено
Ключевые моменты
- Используйте ChatOpenAI с base_url, указывающим на этот API, и моделью
uncensored. - Поддерживаются вызовы функций и JSON-режим, поэтому bind_tools и response_format работают так, как описано в документации.
- Ограничьте циклы агентов, проверяйте аргументы инструментов и поддерживайте max_concurrency на уровне 8 или ниже для полного ключа.
- Потоковая передача по SSE возвращает использование токенов в конце, что помогает отслеживать стоимость каждого запуска агента.

Что вам нужно перед началом
Если вы читаете документацию по Agentic AI в LangChain и задаетесь вопросом, что меняется, когда модель не от поставщика из примеров, ответ — почти ничего. Агент в LangChain — это цикл: модель читает диалог, решает, нужно ли вызывать инструмент, ваш код запускает инструмент, и результат возвращается модели, пока она не выдаст окончательный ответ. Эндпоинту модели нужно только поддерживать chat completions с вызовом функций, и это API это делает.
Вам понадобятся три вещи: API-ключ со страницы ключей, Python 3.10 или новее и указанные ниже пакеты. Базовый URL — https://api.unlimitedaiapi.com/v1, а идентификатор модели — uncensored. Это модель с открытыми весами от независимого провайдера, поэтому выбирать из списка моделей не нужно; GET /v1/models возвращает его для обнаружения клиентами.
pip install -U langchain langchain-openai
export UNLIMITED_API_KEY="your-key-here"Шаг 1: подключение ChatOpenAI к эндпоинту
Класс ChatOpenAI LangChain принимает пользовательский base_url. Всё остальное остаётся прежним, включая invoke, stream, batch и асинхронные варианты.
import os
from langchain_openai import ChatOpenAI
llm = ChatOpenAI(
model="uncensored",
base_url="https://api.unlimitedaiapi.com/v1",
api_key=os.environ["UNLIMITED_API_KEY"],
temperature=0.2,
)
print(llm.invoke("Reply with one short sentence.").content)
Если выводится предложение, аутентификация, маршрутизация и имя модели указаны верно. Аутентификация использует стандартный заголовок Authorization: Bearer, который класс добавляет за вас. Распространенная ошибка — пропуск /v1 в базовом URL, что обычно приводит к ошибке первого вызова.
Шаг 2: определение инструментов и их привязка
Инструменты — это обычные функции Python со строкой документации. Строка документации и аннотации типов становятся схемой, которую видит модель, поэтому пишите их так, будто объясняете функцию новому коллеге.
import os
from langchain_core.tools import tool
from langchain_openai import ChatOpenAI
@tool
def get_order_status(order_id: str) -> str:
'''Look up the status of an order by its ID, for example A100.'''
return {"A100": "shipped", "A101": "processing"}.get(order_id, "not found")
llm = ChatOpenAI(
model="uncensored",
base_url="https://api.unlimitedaiapi.com/v1",
api_key=os.environ["UNLIMITED_API_KEY"],
temperature=0,
)
llm_with_tools = llm.bind_tools([get_order_status])
ai = llm_with_tools.invoke("Where is order A100?")
print(ai.tool_calls)
Выведенный список содержит вызов с именем get_order_status и аргументами, такими как {"order_id": "A100"}. На уровне реализации LangChain отправляет вашу функцию как элемент в массиве tools запроса chat completions, а API поддерживает tools, tool_choice и потоковые tool_calls. Чтобы принудительно вызвать инструмент, передайте tool_choice в bind_tools.
Почему температура низкая
Агенты объединяют несколько вызовов модели, поэтому один некорректный аргумент может сорвать запуск. Температура от 0 до 0,2 делает выбор инструмента более повторяемым. Повышайте её только на этапе финального ответа, если хотите более разнообразный текст.
Шаг 3: запуск цикла агента
Написание цикла вручную занимает пятнадцать строк и показывает, что происходит на каждом шаге, что помогает, когда что-то идёт не так. Результаты инструментов возвращаются модели в виде объектов ToolMessage, которые становятся сообщениями role: "tool" в сетевом запросе.
import os
from langchain_core.messages import HumanMessage, ToolMessage
from langchain_core.tools import tool
from langchain_openai import ChatOpenAI
@tool
def get_order_status(order_id: str) -> str:
'''Look up the status of an order by its ID, for example A100.'''
return {"A100": "shipped", "A101": "processing"}.get(order_id, "not found")
llm = ChatOpenAI(
model="uncensored",
base_url="https://api.unlimitedaiapi.com/v1",
api_key=os.environ["UNLIMITED_API_KEY"],
temperature=0,
)
tools = {"get_order_status": get_order_status}
llm_with_tools = llm.bind_tools(list(tools.values()))
messages = [HumanMessage("Where is order A100, and what about A101?")]
for _ in range(5): # hard cap on loop length
ai = llm_with_tools.invoke(messages)
messages.append(ai)
if not ai.tool_calls:
break
for call in ai.tool_calls:
result = tools[call["name"]].invoke(call["args"])
messages.append(ToolMessage(content=str(result), tool_call_id=call["id"]))
print(ai.content)
Обратите внимание на range(5). Агент без ограничения шагов может бесконечно зацикливаться на непонятном результате инструмента, и каждый проход обходится входными токенами за весь накопленный диалог. Пять — разумный предел для простых задач; увеличивайте его осознанно.
Использование встроенного помощника агента
В последних версиях LangChain есть помощник, который запускает этот цикл за вас. Имя и путь импорта менялись между релизами, поэтому сверяйте их с документацией установленной версии. В текущей ветке 1.x это выглядит так:
import os
from langchain.agents import create_agent
from langchain_core.tools import tool
from langchain_openai import ChatOpenAI
@tool
def get_order_status(order_id: str) -> str:
'''Look up the status of an order by its ID, for example A100.'''
return {"A100": "shipped", "A101": "processing"}.get(order_id, "not found")
llm = ChatOpenAI(
model="uncensored",
base_url="https://api.unlimitedaiapi.com/v1",
api_key=os.environ["UNLIMITED_API_KEY"],
temperature=0,
)
agent = create_agent(llm, tools=[get_order_status], system_prompt="You are a concise support assistant.")
result = agent.invoke({"messages": [{"role": "user", "content": "Where is order A100?"}]})
print(result["messages"][-1].content)
Используйте помощника, когда нужен стандартный шаблон, и цикл, написанный вручную, когда требуются пользовательские правила остановки, логирование каждого шага или результаты инструментов, которые вы хотите отфильтровать до того, как они попадут модели.
Структурированный вывод с JSON-режимом
Агентам часто нужно передавать данные другому коду, например плану, классификации или списку извлечённых полей. JSON-режим заставляет ответ быть корректным объектом JSON. В LangChain вы можете передать его через bind:
import json
import os
from langchain_openai import ChatOpenAI
llm = ChatOpenAI(
model="uncensored",
base_url="https://api.unlimitedaiapi.com/v1",
api_key=os.environ["UNLIMITED_API_KEY"],
temperature=0,
)
json_llm = llm.bind(response_format={"type": "json_object"})
msg = json_llm.invoke(
"Extract the city and country from: 'I moved to Lyon, France last spring.' "
"Answer as JSON with the keys city and country."
)
print(json.loads(msg.content))
Упомяните слово JSON в промпте и опишите ожидаемые ключи, как в примере. JSON-режим гарантирует синтаксис, но не вашу схему, поэтому все равно проверяйте распарсенный объект (например, с помощью Pydantic) и обрабатывайте отсутствие ключа.
Ограничения, потоковая передача и стоимость запусков агента
Агенты делают много вызовов за короткое время, поэтому ограничения аккаунта важнее, чем для простого чат-бота. Полный ключ позволяет 8 параллельных запросов и 300 запросов в минуту. Пробный ключ позволяет 2 и 60. Если вы запускаете параллельные вызовы через batch или запускаете несколько агентов одновременно, ограничьте параллелизм в конфиге:
import os
from langchain_openai import ChatOpenAI
llm = ChatOpenAI(
model="uncensored",
base_url="https://api.unlimitedaiapi.com/v1",
api_key=os.environ["UNLIMITED_API_KEY"],
)
prompts = ["Name one prime number.", "Name one even number.", "Name one square number."]
answers = llm.batch(prompts, config={"max_concurrency": 8})
for a in answers:
print(a.content)
Используйте 2 вместо 8 на пробном ключе. Для интерактивных агентов llm.stream(...) возвращает токены по SSE по мере их генерации, а данные об использовании поступают в конце потока.
Стоимость легко оценить. Запуск из 5 шагов, в среднем использующий 4 000 входных и 300 выходных токенов на шаг, в общей сложности использует 20 000 входных и 1 500 выходных токенов, что составляет $0,003 + $0,00075 = $0,00375 за запуск при цене $0,15 и $0,50 за 1 млн токенов. На странице цен указаны тарифы, а в документации перечислены параметры запроса и заголовки, включая X-Request-Id для отслеживания отдельного неудачного вызова.
Проектирование инструментов для использования моделью
Большинство сбоев агентов восходят к инструментам, а не к циклу. Несколько правил помогают с любой моделью:
- Держите каждый инструмент узким. Инструмент с именем
get_order_statusработает лучше, чем один с именемdatabase_query, принимающий свободный текст. - Используйте простые типы аргументов: строки, целые числа и короткие перечисления. Глубоко вложенные объекты дают модели больше способов ошибиться в поле.
- Возвращайте короткие, простые результаты. Инструмент, который выгружает 50 000 символов в диалог, заполняет контекстное окно и увеличивает стоимость каждого последующего шага.
- Возвращайте ошибки текстом, например «order_id должен выглядеть как A100», вместо выброса исключений, завершающих запуск.
Протестируйте агента на нескольких реальных промптах с пробным балансом $0,50 перед масштабированием. Новые пользователи получают его в один клик на странице ключей, и он действителен в течение 7 дней.
Распространенные ошибки для проверки в первую очередь
- Вызов инструмента никогда не появляется. Сделайте docstring более конкретным, снизьте температуру или принудительно вызовите инструмент с помощью
tool_choice. - Некорректные аргументы. Проверяйте внутри инструмента и возвращайте понятную строку ошибки, чтобы модель могла исправить себя на следующем шаге.
- Рост контекста. Окно составляет 100 000 токенов, включая ответ. Обрезайте старые результаты инструментов, прежде чем они заполнят окно.
Дополнительные руководства
Вопросы и ответы
Какой класс LangChain работает с этим API?
ChatOpenAI из langchain-openai. Установите base_url на https://api.unlimitedaiapi.com/v1, модель — uncensored и передайте ключ как api_key.
Поддерживает ли API вызов функций для агентов?
Да. Он принимает параметры tools и tool_choice, возвращает tool_calls (в том числе при потоковой передаче) и принимает результаты обратно как сообщения с role tool.
Может ли LangChain парсить структурированный вывод через это API?
Да, через JSON-режим: установите response_format в тип json_object. Это гарантирует корректный синтаксис JSON, поэтому проверяйте поля самостоятельно.
Сколько агентов я могу запустить параллельно?
Полный ключ позволяет 8 параллельных запросов и 300 в минуту. Пробный ключ позволяет 2 параллельных и 60 в минуту.
Ваш ключ — всего в одной форме
Создайте аккаунт, скопируйте ключ, измените базовый URL. Это вся настройка.