RU ▾
Получить API-ключ

Документация по 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 возвращает использование токенов в конце, что помогает отслеживать стоимость каждого запуска агента.
Роботизированная рука перемещает кубики через станции инструментов по замкнутому треку, представляя цикл агента LangChain

Что вам нужно перед началом

Если вы читаете документацию по 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. Это вся настройка.

Получить API-ключ