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

API LLM Models для агентов: руководство по вызову функций

Агент — это цикл: модель выбирает инструмент, ваш код его выполняет, результат возвращается, и модель решает, что делать дальше. Вот рабочий вариант этого цикла, а также ограничения и расходы, которые следует учитывать.

Обновлено

Изометрический цикл: сфера проходит через блоки инструментов вокруг центрального терминала, иллюстрирующая рабочий процесс агента
01

Ключевые моменты

  • Эндпоинт поддерживает инструменты, tool_choice, потоковую передачу tool_calls и роли результатов инструментов.
  • Ограничьте цикл, проверьте аргументы инструментов и повторите запросы при ответе 429 с короткой задержкой.
  • Держите количество параллельных рабочих процессов на уровне 8 или ниже для полного ключа; потоки удерживают свой слот до завершения.
  • Запуск агента из шести шагов с растущим контекстным окном стоит около 0,5 цента.

Что нужно агенту от API

Если вы выбираете API LLM Models для агентов, чек-лист короче, чем предполагает маркетинг. Вам нужен надёжный вызов функций, контекстное окно, достаточное для хранения текущего диалога, предсказуемые лимиты запросов и цена, не наказывающая за цикл с множеством вызовов.

Это API покрывает эти возможности через стандартный интерфейс OpenAI. Оно поддерживает tools и tool_choice, возвращает tool_calls в обычных и потоковых ответах и принимает результаты инструментов как сообщения с role: "tool". JSON-режим доступен через response_format. Контекстное окно составляет 100 000 токенов для промпта и ответа модели, а идентификатор модели — uncensored.

Поскольку на стороне фреймворка используется только клиент OpenAI, большинство библиотек агентов, позволяющих задать базовый URL, будут работать. Укажите им https://api.llmmodelsapi.com/v1, предоставьте ключ и укажите имя модели. Подробности настройки — в документации, а ключ можно получить на странице ключей.

Два ограничения определяют архитектуру. Во-первых, модель работает только с текстом, поэтому обработка изображений, аудио или файлов должна происходить в ваших инструментах и возвращаться как текст. Во-вторых, на этом эндпоинте нет эмбеддингов, поэтому если ваш агент выполняет поиск, векторный поиск должен использовать другой источник.

Системный промпт для стабильности цикла

Большинство сбоев агентов вызвано неясными инструкциями, а не API. Хороший системный промпт указывает модели, кто она, какие инструменты существуют, когда остановиться и в каком формате должен быть финальный ответ. Вот вариант для помощника по исследованиям.

Вы — исследовательский ассистент. Вы можете вызывать инструменты search_notes и read_note. Вызывайте инструмент только тогда, когда вам нужна информация, которой у вас ещё нет. Используйте не более пяти вызовов инструментов. Когда у вас будет достаточно данных, ответьте кратким ответом и перечислите идентификаторы использованных заметок. Если заметки не содержат ответа, скажите об этом прямо.

Обратите внимание на то, что делает промпт. Он называет инструменты, устанавливает лимит вызовов, определяет условие остановки и даёт модели разрешение сказать, что она не знает. Последняя часть важна, потому что агент, вынужденный ответить, придумает что-то.

Установите низкую температуру для использования инструментов. Значения около 0,2–0,4 поддерживают стабильность имён инструментов и форматов аргументов. Если ваш агент также генерирует креативный текст в конце, вы можете повысить температуру только для этого финального вызова. Параметр seed передаётся как есть, что помогает воспроизвести запуск при отладке.

Для агентов, работающих с взрослой художественной литературой и ролевыми играми, тот же шаблон работает: поместите персону, правила сцены и инструменты в системное сообщение. Модель настроена на ответы без отказов по контенту для законного использования взрослыми. Сексуальный контент с участием несовершеннолетних остаётся недоступным.

Минимальный цикл агента на Python

Цикл ниже имеет один инструмент — поиск в словаре, заменяющем ваши реальные данные. Он останавливается, когда модель отвечает без вызова инструмента или после фиксированного числа шагов.

import json
from openai import OpenAI

client = OpenAI(base_url="https://api.llmmodelsapi.com/v1", api_key="YOUR_KEY")

NOTES = {
    "n1": "Invoice 114 was paid on March 3.",
    "n2": "Invoice 115 is overdue by 12 days.",
}

def search_notes(query):
    return [{"id": k, "text": v} for k, v in NOTES.items() if query.lower() in v.lower()]

TOOLS = [{
    "type": "function",
    "function": {
        "name": "search_notes",
        "description": "Search internal notes by keyword",
        "parameters": {
            "type": "object",
            "properties": {"query": {"type": "string"}},
            "required": ["query"],
        },
    },
}]

SYSTEM = "You are a research assistant. Use search_notes when needed, at most five calls. Then answer briefly."

def run(question, max_steps=6):
    messages = [
        {"role": "system", "content": SYSTEM},
        {"role": "user", "content": question},
    ]
    for step in range(max_steps):
        resp = client.chat.completions.create(
            model="uncensored",
            messages=messages,
            tools=TOOLS,
            temperature=0.3,
            max_tokens=500,
        )
        msg = resp.choices[0].message
        messages.append(msg)
        if not msg.tool_calls:
            return msg.content
        for call in msg.tool_calls:
            try:
                args = json.loads(call.function.arguments)
                result = search_notes(args["query"])
            except Exception as exc:
                result = {"error": str(exc)}
            messages.append({
                "role": "tool",
                "tool_call_id": call.id,
                "content": json.dumps(result),
            })
    return "Stopped: step limit reached."

print(run("Which invoice is overdue?"))

Три момента заслуживают внимания. Лимит шагов не даёт запутавшейся модели зацикливаться, пока не закончится ваш баланс. Блок try превращает некорректную строку аргументов в сообщение об ошибке, которое модель может прочитать и исправить. И каждый результат инструмента отправляется обратно с соответствующим tool_call_id, что позволяет модели узнать, к какому вызову относится каждый ответ.

Обработка ответов 429 и параллелизм

Агенты работают скачками. Планировщик может запустить пять подзадач одновременно, и каждая из них запускает свой цикл. Именно здесь проявляются лимиты запросов.

Полный ключ позволяет 8 параллельных запросов и 300 запросов в минуту. Пробный ключ позволяет 2 и 60. При превышении лимита API отвечает кодом HTTP 429. Код ошибки указывает, какой именно лимит вы исчерпали: rate_limited для запросов в минуту, concurrency для одновременных запросов. При временной перегрузке вы также получите 429 с заголовком Retry-After: 5.

Считайте все эти случаи повторяемыми. Подождите количество секунд из заголовка или пару секунд, если его нет, и отправьте запрос снова. Неудачные запросы не оплачиваются, поэтому повторные запросы ничего не стоят. Небольшая обёртка решает эту задачу.

import time
from openai import OpenAI, RateLimitError

client = OpenAI(base_url="https://api.llmmodelsapi.com/v1", api_key="YOUR_KEY", max_retries=0)

def chat_with_retry(**kwargs):
    for attempt in range(5):
        try:
            return client.chat.completions.create(model="uncensored", **kwargs)
        except RateLimitError as err:
            wait = 5
            if err.response is not None:
                wait = int(err.response.headers.get("retry-after", 5))
            time.sleep(wait)
    raise RuntimeError("Still rate limited after 5 attempts")

Чтобы избежать 429, ограничьте размер пула воркеров. Семафор на 8 соответствует полному ключу. Если вы потоково передаёте ответы в пользовательский интерфейс, помните, что поток занимает слот параллельности до получения последнего токена, поэтому медленный клиент, читающий длинный ответ, занимает слот всё время. Чтение заголовков X-RateLimit-Limit-Requests и X-RateLimit-Limit-Concurrency позволяет коду адаптироваться к используемому ключу.

Контекст, память и стоимость запуска

Каждый шаг цикла повторно отправляет полный транскрипт. Так работают чат-API, и это означает, что входные токены растут с каждым вызовом инструмента. Возьмём шестиступенчатый запуск, где промпт начинается с 2000 токенов и растёт на 1000 за шаг, с 300 выходными токенами за шаг.

  • Входные токены: 2 000 + 3 000 + 4 000 + 5 000 + 6 000 + 7 000 = 27 000
  • Выходные токены: 6 x 300 = 1 800
  • Стоимость входа: 27 000 x 0,15 / 1 000 000 = $0,00405
  • Стоимость выхода: 1 800 x 0,50 / 1 000 000 = $0,0009
  • Итого: $0,00495 за запуск

Тысяча таких запусков стоит $4,95. Это достаточно дёшево, чтобы позволить агенту думать в несколько шагов, но рост токенов стоит отслеживать. При 100 000 токенов места долгосрочный агент в конечном итоге заполнит контекстное окно, и промпт такого размера будет стоить 100 000 x 0,15 / 1 000 000 = $0,015 за ввод на каждом шаге.

Три привычки удерживают это под контролем. Обрезайте большие результаты инструментов перед добавлением в историю диалога, например первые 2000 символов веб-страницы. Сводите старые шаги в одно короткое сообщение, когда история превышает порог. И храните долговечные факты в собственной базе данных, а не полагайтесь на разговор как на память.

Заголовок X-Balance-USD в каждом ответе показывает оставшийся баланс, поэтому координатор агента может остановить выполнение, когда баланс упадёт ниже установленного порога. Баланс предоплачен от $20 и не сгорает. Подробнее о бонусах за пополнение см. на странице с ценами.

Честные ограничения для планирования

Агентам, построенным на любой модели, нужны ограничивающие механизмы, и эта не исключение. Будьте готовы к следующему.

  • Некорректные аргументы. Модель может генерировать аргументы инструментов, которые не являются валидным JSON или не содержат обязательное поле. Парсите с защитой и возвращайте ошибку как результат инструмента.
  • Неправильный выбор инструмента. Пишите короткие, различные описания инструментов. Если два инструмента звучат похоже, модель их перепутает. Используйте tool_choice, чтобы принудительно вызвать конкретный инструмент, когда поток этого требует.
  • Только текст. Нет ввода или вывода изображений, нет аудио, нет эмбеддингов, нет дообучения. Выполняйте эти части в другом месте и передавайте результат как текст.
  • Одна модель. За эндпоинтом стоит одна модель с открытыми весами, а не маршрутизатор между поставщиками. Вы не можете выбрать меньшую модель для простых шагов.
  • Разрушительные инструменты. Не давайте агенту инструмент удаления или оплаты без шага подтверждения в вашем коде.

Планирующие агенты также выигрывают от второго прохода. После того как цикл вернёт ответ, вы можете сделать ещё один дешёвый вызов, который попросит модель проверить ответ на основе результатов инструментов, используя JSON-режим для возврата вердикта и списка неподдерживаемых утверждений. Это добавляет несколько сотен токенов и выявляет наиболее частую ошибку — уверенный ответ, игнорирующий результаты инструментов.

Наконец, логируйте каждый шаг. Сохраняйте сообщения, аргументы инструментов и заголовок X-Request-Id из каждого ответа. Когда запуск завершается ошибкой, идентификатор запроса позволяет указать на точный вызов, а записанный транскрипт показывает, какой результат инструмента ввёл модель в заблуждение. Агентов легче улучшать, когда можно воспроизвести неудачный запуск и изменить одну вещь за раз.

Протестируйте агента с пробным балансом, прежде чем принимать решение. Новые пользователи могут получить $0,50 кредита, которого при шестиступенчатом запуске выше хватит примерно на 101 полный запуск (0,50 / 0,00495). Учитывайте лимит в 2 одновременных запроса для пробного ключа и запускайте по одному агенту за раз. Для более широкого обзора сервиса прочитайте обзор оплаты за токен. Промпты не используются для обучения.

02

Вопросы и ответы

Поддерживает ли API вызов функций для агентов?

Да. Он принимает инструменты и tool_choice, возвращает tool_calls (в том числе при потоковой передаче) и принимает результаты как сообщения с role tool.

Сколько параллельных запросов может выполнять агент?

Полный ключ позволяет 8 одновременных запросов и 300 в минуту. Пробный ключ позволяет 2 одновременных и 60 в минуту.

Что должен делать агент при получении 429?

Дождитесь значения Retry-After или несколько секунд, если его нет, и повторите запрос. Отклонённые запросы не оплачиваются.

Может ли агент обрабатывать изображения или аудио?

Нет. Модель работает только с текстом, поэтому любые другие медиа необходимо обрабатывать вашими собственными инструментами и передавать в виде текста.

Ваш ключ — всего в одной форме

Создайте аккаунт, скопируйте ключ, измените базовый URL. Вот и вся настройка.

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