Агент с четырьмя раундами вызова инструментов отправляет модели до пяти запросов, и каждый следующий длиннее предыдущего. Пока инструмент один и это калькулятор, цена копеечная. Когда инструмент умеет оформлять возврат денег, ошибка одного раунда стоит дороже всех токенов за месяц.
Поэтому первого агента стоит собрать вручную, без фреймворка. Каждый шаг тогда виден в одном файле, права инструментов проверяет ваш собственный код, а логи заодно дают цифры для бизнес-кейса: сколько стоит решённый запрос и стоит ли покупать платформу.
Агент опасен ровно настолько, насколько опасны его инструменты
Если модель вызывает API, отправляет письма или меняет записи, главный вопрос в том, как ограничить её действия. Ошибочный вызов не должен вредить данным, деньгам и доверию. Собственный агент на Python ценен прозрачной механикой: один процесс, известные инструменты, предел действий и журнал шагов.
Первый прототип обычно ломается на стыках, формулировки модели тут вторичны. Она выбирает несуществующий инструмент, передаёт лишнее поле, зацикливается или получает сетевую ошибку без понятного ответа. Ручной код показывает эти места в одном файле, и его легко переделать, пока контракт инструментов не устоялся.
Цена ошибки определяет автономность. Неверный результат калькулятора заметит пользователь. Инструмент возврата в платёжной системе должен требовать подтверждения человека или быть вовсе недоступен модели.
OWASP в списке Top 10 for LLM Applications 2025 называет это «excessive agency» (LLM06): модели выдали больше прав, чем нужно задаче, и она может сделать то, чего никто не планировал. Рядом стоит LLM01, prompt injection: текст из письма или веб-страницы, попавший в контекст, способен подтолкнуть модель к вызову инструмента. Агентный цикл не заменяет правила доступа, поэтому права проверяет ваш код, а не модель.
Агент нужен, только если маршрут зависит от запроса
Выбор начинается с вопроса, нужен ли агент вообще. Если последовательность шагов фиксирована, он не нужен: обычный сервис с формой, проверкой ввода и жёстко прописанной логикой надёжнее. Модель может извлекать параметры из свободного текста, но выбирать маршрут ей незачем.
Когда маршрут действительно зависит от запроса, остаются два пути. Первый: прямой OpenAI Python SDK и собственный цикл. Он хорош для узкой задачи с парой инструментов, когда нужны точный JSON, история и логи. Код ничего не прячет: видно, кто вызвал функцию и почему цикл остановился.
Второй путь: LangChain или LlamaIndex. Они экономят труд в другом месте. LangChain удобен, когда нужны готовые подключения к сервисам, трассировка и цепочки из нескольких шагов. LlamaIndex подходит, если продукт построен вокруг поиска по документам. За удобство платят лишними слоями, настройками и местами, где поведение меняется вне вашего кода. То есть платят той самой прозрачностью, ради которой ограничивали действия.
Выбор определяют наблюдаемость, изменчивость инструментов и цена неверного действия.
| Критерий | Прямой SDK | LangChain или LlamaIndex | Обычный сервис |
|---|---|---|---|
| Путь до первого результата | Быстро для 1-3 инструментов | Быстро, если нужная интеграция есть | Быстро для фиксированного сценария |
| Видимость цикла | Полная, логируете каждый вызов | Зависит от настройки трассировки | Полная, цикла модели нет |
| Изменение оркестрации | Правки в своём коде | Конфигурация и правила библиотеки | Явная бизнес-логика |
| Риск лишнего действия | Схемы и лимиты | Нужны те же ограничения | Минимален при жёстком маршруте |
| Рост числа интеграций | Реестр нужно поддерживать | Готовые адаптеры могут окупиться | Плохо для свободных запросов |
Порога по числу инструментов нет. Один обратимый вызов внутреннего API может годами жить в ручном цикле. Пять систем с разными правами, потоковой выдачей, поиском по документам и оценкой качества уже требуют столько поддержки, что разумнее взять библиотеку или отдельный оркестратор.
Цикл останавливается по двум условиям, и лимит в 4 раунда важнее
Минимальный агент отправляет модели контекст и описание функций, читает выбранные вызовы, исполняет разрешённые инструменты, добавляет результат в контекст и снова вызывает модель. Модель не запускает Python. Она возвращает имя функции и аргументы в JSON.
У цикла два независимых условия остановки. Нормальное: вызовов функций нет, а текст пользователю есть. Предохранитель: достигнут MAX_TOOL_ROUNDS, даже если модель просит ещё. Без лимита ошибка в описании инструмента может породить бесконечный разговор модели с собой.
Лимит защищает и бюджет. Пусть, для примера, системный промпт, описание инструментов и история занимают 3 000 токенов, а каждый раунд добавляет вызов и результат примерно на 500 токенов. Четыре раунда и финальный ответ дают на входе 3 000 + 3 500 + 4 000 + 4 500 + 5 000 = 20 000 токенов. Это почти в семь раз больше одиночного запроса.
При цене для примера 0,40 доллара за миллион входных токенов агент тратит 0,008 доллара на запрос. При 50 000 запросов в день выходит 400 долларов в сутки вместо 60. OWASP выделяет этот риск отдельно как LLM10, unbounded consumption: агент без лимита раундов расходует деньги так же бесконтрольно, как и действия.
Скидки провайдеров помогают, но лимит не заменяют. Повторяющийся префикс (системный промпт и описание инструментов) дешевеет при кэшировании промптов. Пакетная обработка со скидкой интерактивному агенту не подходит: пользователь ждёт ответа сейчас.
Описание функции работает как договор. additionalProperties: false запрещает неожиданные аргументы, но ваш код всё равно повторно проверяет имя функции, типы, права и допустимый диапазон. Формат вызовов и ответов описан в документации OpenAI по function calling.
Один файл, один инструмент, никакого eval
Ниже один файл agent.py. Нужны pip install openai и переменная OPENAI_API_KEY. Калькулятор ограничен арифметическим деревом ast: строка не попадает в eval, поэтому модель не получает путь к файловой системе или оболочке.
import ast
import json
import logging
import operator
import time
from openai import APIConnectionError, APIStatusError, OpenAI
logging.basicConfig(level=logging.INFO, format="%(message)s")
log = logging.getLogger("agent")
client = OpenAI(max_retries=0, timeout=30.0)
MODEL = "gpt-4.1-mini"
MAX_TOOL_ROUNDS = 4
TOOLS = [{
"type": "function", "name": "calculator",
"description": "Считает арифметическое выражение из чисел, скобок и + - * /.",
"parameters": {
"type": "object",
"properties": {"expression": {"type": "string"}},
"required": ["expression"], "additionalProperties": False
}
}]
OPS = {ast.Add: operator.add, ast.Sub: operator.sub,
ast.Mult: operator.mul, ast.Div: operator.truediv}
def calculator(expression):
if len(expression) > 100:
raise ValueError("слишком длинное выражение")
tree = ast.parse(expression, mode="eval")
def walk(node):
if isinstance(node, ast.Constant) and type(node.value) in (int, float):
return node.value
if isinstance(node, ast.UnaryOp) and isinstance(node.op, ast.USub):
return -walk(node.operand)
if isinstance(node, ast.BinOp) and type(node.op) in OPS:
return OPS[type(node.op)](walk(node.left), walk(node.right))
raise ValueError("разрешены только числа и арифметические операции")
return {"value": walk(tree.body)}
HANDLERS = {"calculator": calculator}
def trim_memory(memory, max_messages=12):
return memory[-max_messages:]
def create_response(input_items):
for attempt in range(3):
try:
return client.responses.create(
model=MODEL, input=input_items, tools=TOOLS
)
except (APIConnectionError, APIStatusError) as exc:
transient = (isinstance(exc, APIConnectionError)
or exc.status_code in (408, 409, 429)
or exc.status_code >= 500)
if not transient or attempt == 2:
raise
delay = 2 ** attempt
log.warning("model_retry=%s error=%s", attempt + 1, type(exc).__name__)
time.sleep(delay)
def run_agent(prompt, memory):
context = trim_memory(memory) + [{"role": "user", "content": prompt}]
try:
response = create_response(context)
except Exception as exc:
log.exception("model_start_failed")
return f"Не удалось получить ответ модели: {type(exc).__name__}"
for step in range(1, MAX_TOOL_ROUNDS + 2):
calls = [item for item in response.output if item.type == "function_call"]
log.info("step=%s calls=%s", step, len(calls))
if not calls:
answer = response.output_text.strip()
if not answer:
return "Модель завершила ответ без текста. Повторите запрос."
memory.extend([
{"role": "user", "content": prompt},
{"role": "assistant", "content": answer}
])
return answer
if step > MAX_TOOL_ROUNDS:
break
context.extend(response.output)
for call in calls:
try:
args = json.loads(call.arguments)
handler = HANDLERS[call.name]
result = handler(**args)
log.info("tool=%s status=ok", call.name)
except Exception as exc:
result = {"error": f"{type(exc).__name__}: {exc}"}
log.warning("tool=%s status=error", call.name)
context.append({
"type": "function_call_output", "call_id": call.call_id,
"output": json.dumps(result, ensure_ascii=False)
})
try:
response = create_response(context)
except Exception as exc:
log.exception("model_continue_failed")
return f"Инструмент выполнился, но модель не ответила: {type(exc).__name__}"
return "Лимит вызовов инструментов исчерпан. Уточните запрос."
if __name__ == "__main__":
memory = []
while True:
prompt = input("Вы: ").strip()
if prompt.lower() in {"выход", "exit", "quit"}:
break
print("Агент:", run_agent(prompt, memory))
После сохранения проверка может выглядеть так:
from agent import run_agent
print(run_agent("Посчитай (18 * 7) / 3", []))
Реестр HANDLERS не строится из ответа модели: она выбирает только ключ заранее созданного словаря. Неизвестное имя функции даёт KeyError, который превращается в сообщение об ошибке для модели, и цикл продолжается. Для HTTP-инструмента добавьте список разрешённых адресов (allowlist), таймаут, предел размера ответа и отдельные учётные данные с минимальными правами.
Память хранит выводы, трасса живёт в логах
Долгая память и техническая трасса решают разные задачи. В memory лежат пары «запрос пользователя и финальный ответ ассистента». Временный context хранит вызовы функций и их результаты только до финального ответа. Поэтому при обрезке не остаётся function_call без парного function_call_output.
max_messages=12 лишь ограничивает размер контекста. Для долгого диалога заменяйте старые сообщения краткой сводкой подтверждённых пользователем фактов: целей, ограничений, выбранных сущностей. Сырые логи, токены, пароли и полный вывод внутренних API туда не переносите.
Короткий контекст выгоден не только по цене. Liu и соавторы в работе 2023 года «Lost in the Middle» показали, что сведения из середины длинного контекста модель использует хуже, чем с его краёв. Поэтому сводку фактов ставят в начало контекста, подальше от середины.
Логи должны показывать шаг, запрошенную функцию, её ошибку и причину остановки цикла. Аргументы инструментов записывайте с маскировкой секретов. Ответ внешнего сервиса часто содержит персональные данные, поэтому для отладки достаточно идентификатора запроса, статуса и безопасного краткого сообщения.
Повторяйте запрос при сбоях сети, ответе 429 (слишком много запросов) и ошибках 5xx на стороне сервера. Повтор 400 с неверной схемой ничего не исправит. В примере задержка 2 ** attempt: первая повторная попытка ждёт 1 секунду, следующая 2 секунды. В рабочем коде добавьте к задержке случайную добавку (jitter), чтобы параллельные процессы не повторяли запрос одновременно. Тридцать параллельных процессов, получивших 429 в одну секунду, без такой добавки вернутся тоже в одну секунду и снова получат 429.
Первый релиз решает одну обратимую задачу
Внутреннему боту, к примеру, пишут: «Один заказ стоит 18 USD, заказов 7. Какая выручка?» Модель выбирает calculator с 18 * 7, получает 126 и формулирует ответ. Результат легко проверить: число вернул инструмент, модель не считала его сама. Боту не нужны платежи, поиск документов и автономные последующие действия.
Такой релиз проверяет промпт и схему. Журнал показывает, вызвала ли модель калькулятор, передала ли допустимое выражение и остановилась ли после результата. По тем же логам видны типичные поломки, и у каждой свой первый шаг:
- Модель отвечает числом, не вызвав инструмент. Значит, описание функции не объясняет, когда её звать; добавьте в
descriptionпрямое условие вроде «для любых вычислений». - В логах подряд
step=4иstep=5с вызовами. Модель зациклилась на ошибке инструмента; проверьте, понятен ли текст ошибки, который она получает. - Растёт доля ответов «Лимит вызовов инструментов исчерпан». Если таких больше 1-2% запросов, задача для агента сформулирована слишком широко, и её стоит разделить.
Если задача влияет на бюджет, до запуска оцените стоимость AI-агента для бизнеса: расходы включают токены, интеграцию, проверку ответов, поддержку и обработку сбоев.
Первый шаг команды: выписать один пользовательский запрос, один обратимый инструмент и одно ожидаемое наблюдение после вызова. Добавлять всё сразу не стоит: журнал заполнится неразличимыми переходами, и источник ошибки останется неясным.
Прототип за неделю проверяет бизнес-кейс до покупки платформы
Этот файл полезен не только разработчику. Неделя работы с ним даёт продакт-менеджеру цифры, без которых разговор с поставщиком агентной платформы идёт вслепую: сколько раундов уходит на типичный запрос, сколько токенов он съедает и какая доля запросов упирается в лимит.
Логи прототипа уже содержат всё нужное. Строка step= показывает число раундов, доля ответов «Лимит вызовов инструментов исчерпан» показывает, какая часть потока агенту не по силам, а ручная проверка сотни случайных ответов даёт долю верных. Из этих трёх чисел складывается главная цифра: стоимость решённого запроса.
Допустим, прототип показал в среднем три раунда, 15 000 входных токенов на запрос и 85% верно решённых случаев. При той же цене для примера, 0,40 доллара за миллион токенов, запрос обходится в 0,006 доллара, а решённый запрос примерно в 0,0071. Остальные 15% уходят человеку. Если ручная обработка стоит, скажем, 2 доллара, на каждые сто запросов приходится 30 долларов ручной работы и около 60 центов токенов. Цена модели в этой сумме почти не видна, всё решает доля верных ответов.
Отсюда правило для выбора между сборкой и покупкой. Если платформа обещает поднять долю верных ответов с 85 до 92%, на каждой сотне запросов это экономит 14 долларов ручной работы, и с этой цифрой можно сравнивать её лицензию. Если прототип уже решает 95% и упирается только в инфраструктуру, платить предстоит за удобство, и цена удобства должна быть меньше зарплаты человека, который поддерживал бы ручной цикл.
Когда ручной цикл пора менять на фреймворк
Сторонники фреймворков напомнят, что ручной код со временем сам превращается в плохой фреймворк. Через полгода в нём появляются свои адаптеры к трём провайдерам, своя трассировка, свои повторные попытки и своя оценка качества, и всё это поддерживает один человек. Библиотека, которую используют тысячи команд, решает те же задачи лучше и бесплатно.
Они правы, когда код повторяет инфраструктурную работу: подключает много провайдеров, строит поиск по документам, хранит трассы, запускает оценки качества и координирует несколько агентов. Практический сигнал простой: если обвязка вокруг цикла стала длиннее самого цикла и инструментов вместе взятых, пора смотреть на LangChain, LlamaIndex или отдельный оркестратор. Ограничения прав, схемы, лимит шагов и аудит при этом остаются вашей обязанностью. Владельца агента стоит назначить заранее, особенно если агент влияет на продуктовые эксперименты. Как распределять такую ответственность, разобрано в материале про организационный дизайн команд роста.
Ни ручной цикл, ни фреймворк не подходят, если нужны детерминированный результат, формальное согласование, необратимая операция или строгий аудит каждого бизнес-правила. Тогда модель извлекает данные и предлагает черновик, а действие выполняет обычный сервис с явной последовательностью проверок. Если же нужен один прозрачный маршрут через пару инструментов, собственный код на SDK проще контролировать, чем библиотеку, добавленную ради названия.