Что такое ИИ-агент: собираем runtime с контролем токенов и бюджета с нуля

Если вы слышите «ИИ-агент» и представляете что-то из фантастики, пора обновить картинку: сегодня это программа, которая сама решает, какой инструмент вызвать, проверяет результат и продолжает работу без вашего участка, и в этом руководстве мы соберём runtime для таких агентов с нуля, включая контроль расходов в токенах и рублях.

Что такое ИИ-агент и зачем ему runtime?

ИИ-агент (agent) отличается от обычного чат-бота тем, что сам выбирает следующее действие. Бот отвечает на вопрос и ждёт. Агент получает задачу, вызывает нужные инструменты, читает результат и решает, что делать дальше, пока задача не будет закрыта.

Runtime, или «обвязка» (harness), это код, который управляет этим циклом. Он принимает задачу от пользователя, передаёт модели, проверяет и выполняет вызовы инструментов, возвращает наблюдения модели и крутит цикл до завершения.

Туториал OpenHarness, на котором построено это руководство, воспроизводит все ключевые блоки агентной системы: использование инструментов, типизированные схемы, разрешения, хуки жизненного цикла (lifecycle hooks, точки, в которых вы можете вмешаться в работу агента), память, навыки, сжатие контекста, логику повторных попыток, подсчёт стоимости и координацию нескольких агентов.

Что понадобится

• Python 3.10+ (проверьте командой python --version)
• Библиотека nest_asyncio (нужна, если запускаете внутри Jupyter или другого окружения с активным event loop): pip install nest_asyncio
• Текстовый редактор или Jupyter Notebook
• API-ключ не нужен: OpenHarness работает с мок-моделью (mock-sonnet), поэтому можно экспериментировать бесплатно
• Время: 40 минут на сборку, ещё 20 на эксперименты с тарифами

Пошаговая инструкция

1. Создайте файл и импортируйте зависимости

Скопируйте блок импортов из OpenHarness. Ключевые модули: asyncio для асинхронного цикла, dataclasses для структур данных, typing для типизации схем инструментов.

from __future__ import annotations
import asyncio, dataclasses, json, time, typing
from dataclasses import dataclass, field

Функция run_async из туториала решает частую проблему: запуск асинхронного кода из синхронного контекста. Если event loop уже активен (например, в Jupyter), она пробует nest_asyncio, а если не получается, запускает код в отдельном потоке.

2. Определите структуры данных для учёта токенов

Класс Usage хранит количество входных и выходных токенов (token, минимальная единица текста для модели, примерно 4 символа на английском, на русском ближе к 2 символам на токен):

@dataclass
class Usage:
    input_tokens: int = 0
    output_tokens: int = 0
    def __add__(self, other: "Usage") -> "Usage":
        return Usage(
            self.input_tokens + other.input_tokens,
            self.output_tokens + other.output_tokens
        )

Функция count_tokens даёт грубую оценку: делит длину текста на 4. Для русского текста точнее делить на 2.

3. Настройте прайс-лист и счётчик стоимости

Класс CostMeter накапливает использование токенов и переводит их в доллары по тарифной книге PRICE_BOOK:

PRICE_BOOK = {
    "mock-sonnet":      (3.00, 15.00),
    "claude-sonnet-4":  (3.00, 15.00),
    "gpt-4.1":          (2.00, 8.00),
    "default":          (1.00, 3.00),
}

Числа в скобках означают стоимость за миллион токенов: первое число для входных, второе для выходных. Модель mock-sonnet имитирует тарифы Claude Sonnet 4: 3 доллара за миллион входных токенов, 15 за миллион выходных.

4. Добавьте российские тарифы

Здесь начинается адаптация. Допишите в PRICE_BOOK строки для моделей, доступных в РФ, и добавьте метод пересчёта в рубли:

PRICE_BOOK["yandexgpt-pro"] = (0.60, 0.60)
PRICE_BOOK["gigachat-pro"]  = (0.50, 0.50)

RUB_RATE = 95.0  # курс доллара, обновляйте вручную

class CostMeterRub(CostMeter):
    @property
    def rubles(self) -> float:
        return self.dollars * RUB_RATE
    def summary(self) -> str:
        base = super().summary()
        return f"{base} | ~{self.rubles:.2f} ₽"

Тарифы YandexGPT и GigaChat приведены ориентировочно. Актуальные цены проверяйте на официальных страницах: тарифы меняются, и фиксированные числа в коде устаревают.

5. Опишите инструменты через типизированные схемы

Функция build_json_schema превращает Python-датакласс в JSON Schema (формальное описание структуры данных, которое модель использует, чтобы понять, какие параметры принимает инструмент). Функция fld задаёт описание поля:

@dataclass
class SearchInput:
    query: str = fld("Поисковый запрос")
    max_results: int = fld("Количество результатов", default=5)

schema = build_json_schema(SearchInput)

Модель видит этот schema и знает: чтобы вызвать поиск, нужно передать query (обязательно) и max_results (необязательно, по умолчанию 5).

6. Соберите цикл агента

Главный цикл работает так:

• Пользователь отправляет задачу
• Обвязка формирует сообщение и передаёт модели вместе со списком доступных инструментов
• Модель возвращает AssistantTurn: текст и, возможно, вызовы инструментов (ToolCall)
• Обвязка проверяет разрешения, выполняет инструмент, записывает результат как наблюдение
• Цикл повторяется, пока модель не вернёт stop_reason: "end_turn" без вызовов инструментов

Каждый виток цикла прогоняется через CostMeter.add(), и вы видите, сколько токенов потрачено.

7. Подключите координацию нескольких агентов

Многоагентная координация (multi-agent coordination) означает, что несколько агентов работают над одной задачей. Один агент может передать подзадачу другому. Обвязка отслеживает, какой агент сейчас активен, и ведёт отдельный счётчик токенов для каждого.

Как выглядит результат на практике?

3 model call(s) | in=1200 out=340 tok | ~$0.00870 (mock-sonnet)

3 model call(s) | in=1200 out=340 tok | ~$0.00870 (mock-sonnet) | ~0.83 ₽

Что делать с этим прямо сейчас?

Автору Дзена. Что такое ИИ-агент в практическом смысле: программа, которой вы даёте задачу целиком (например, «собери фактуру для статьи»), а не пишете каждый промпт (prompt, текстовая инструкция для модели) руками. Пока сложно, но через полгода это станет обычным рабочим инструментом. Начните с запуска OpenHarness на мок-модели, чтобы увидеть, как агент выбирает инструменты.

Маркетологу. Счётчик стоимости в рублях решает главную боль: «сколько мы потратим на API, если запустим автоматическую обработку лидов». Встройте CostMeterRub и покажите руководству прогноз до запуска, а не постфактум.

Разработчику в РФ. Добавьте в PRICE_BOOK актуальные тарифы YandexGPT и GigaChat. Для русского текста замените count_tokens на деление длины на 2 или подключите токенизатор tiktoken с поправкой. Это даст точность оценки бюджета в пределах 15% вместо двукратной ошибки.

Контроль стоимости в токенах и рублях превращает эксперименты с агентами из «попробую и посмотрю, сколько списали» в управляемый процесс с прогнозируемым бюджетом, и именно с этого стоит начинать любой проект на API в российских реалиях.