Автономный ИИ-агент с нуля: минимальный рабочий пример

Из чего на самом деле состоит агент

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

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

import requests

API_KEY = "fetch_ваш_ключ"
URL = "https://api.zukko.pro/v1/messages"

tools = [{
    "name": "run_shell",
    "description": "Выполнить команду в shell и вернуть stdout",
    "input_schema": {
        "type": "object",
        "properties": {"command": {"type": "string"}},
        "required": ["command"],
    },
}]

Этого достаточно для рабочего цикла: модель просит выполнить команду, получает stdout, решает, хватит ли данных для ответа, и либо запрашивает ещё одну команду, либо отвечает текстом.

Выбор модели для цикла агента

Для агентных циклов с инструментами лучше подходят модели с большим контекстом, потому что история сообщений растёт с каждым шагом — у Claude и GPT в каталоге 1 000 000 токенов (у GLM — 128K), так что цикл из полусотни шагов с объёмными выводами команд не упрётся в потолок раньше времени. Для многошаговых цепочек с несколькими инструментами подряд попробуйте gpt-5.6-sol и claude-opus-5-5, а claude-sonnet-5 — если шагов немного и важна скорость ответа на каждом; какая модель увереннее держит цепочку именно у вас, проверьте на своих задачах. Учтите и цену длинной истории: каждый шаг заново оплачивает весь накопленный контекст. У вендоров чтение из кэша промптов стоит ~10% цены входа, а в Zukko кэшированные токены идут по обычной цене — для агентов с большим повторяющимся контекстом реальная разница в цене меньше, чем при сравнении прайсов «в лоб».

Идемпотентность внутри цикла

Если агент запускает инструмент с побочным эффектом — например, отправляет запрос во внешний API — и в процессе рвётся соединение с шлюзом, велик риск повторить один и тот же шаг агента дважды и заплатить за него дважды. Добавляйте Idempotency-Key на основе номера шага и хэша сообщений в запросе к модели — повтор с тем же ключом и тем же телом за 24 часа вернёт тот же ответ без нового списания.

Ограничение числа шагов

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

MAX_STEPS = 20
step = 0
while step < MAX_STEPS:
    step += 1
    ...
    if not tool_calls:
        break
else:
    print("Достигнут лимит шагов, отдаю то, что есть")

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

Оценка стоимости цикла заранее

Перед тем как запускать агента на реальной задаче без присмотра, полезно прикинуть верхнюю границу стоимости: посчитать токены типичного шага через POST /v1/messages/count_tokens (запрос бесплатный) и умножить на MAX_STEPS. Это не точная цифра — конкретный диалог может завершиться раньше, — но она задаёт разумный дневной лимит на ключе в кабинете, чтобы не гадать постфактум, сколько мог стоить худший сценарий.

Обработка ошибок посреди цикла

Долгий агентный прогон обязательно наткнётся на что-то из типового набора: 429 с key_daily_limit_reached, если у ключа в кабинете задан дневной лимит расхода и агент его исчерпал на середине задачи; 503 provider_unavailable, если модель временно недоступна — тогда стоит на этом шаге откатиться на другую модель из каталога, а не ронять весь цикл; обрыв ответа на середине — это почти всегда таймаут HTTP-клиента, а не то, что модели не хватило max_tokens, так что для длинных ответов с инструментами таймаут стоит ставить с запасом.

Логирование истории для отладки

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

Стоимость по шагам

Каждый обычный (не потоковый, как в примере выше) ответ несёт X-Zukko-Cost-Micros — стоимость именно этого шага в микродолларах — и X-Fetch-Balance-Cents с остатком (несмотря на название, тоже в микродолларах: 1 000 000 = $1). Если агент работает со stream: true, этих заголовков не будет — расход смотрите в /v1/usage или /v1/balance. В цикле агента полезно логировать оба значения на каждой итерации: если агент зацикливается и повторяет один и тот же вызов инструмента без прогресса, это видно по бюджету раньше, чем по логике, — расход растёт, а X-Fetch-Balance-Cents падает быстрее, чем должен на задаче такого размера. Для агентов, которые запускаются без присмотра, разумно сразу поставить дневной лимит на ключе в кабинете на странице ключа — это дешевле, чем ловить зациклившийся агент постфактум по счёту.