Как создать ИИ-агента на Python с нуля: tool calling, цикл и бюджет

Как создать ИИ агента на Python, если не хочется сразу тащить в проект большой фреймворк? Минимальный агент — это около сотни строк: модель, несколько функций-инструментов и цикл, который их вызывает. Ниже — полный рабочий код на OpenAI SDK, разбор каждой части и два предохранителя, без которых агента нельзя оставлять без присмотра: лимит шагов и бюджет в долларах.

Что такое ИИ-агент

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

• Модель, которая умеет вызывать инструменты (tool calling).
• Инструменты — обычные функции Python с описанием в виде JSON-схемы.
• Цикл: отправили запрос → модель попросила вызвать инструмент → вызвали, вернули результат → снова запрос. И так до финального ответа или до срабатывания ограничителя.

Как создать ИИ агента на Python: полный код

Установите SDK и положите ключ в переменную окружения:

pip install openai
export ZUKKO_API_KEY=fetch_ваш_ключ

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

import ast
import json
import operator
import os
from pathlib import Path

from openai import OpenAI

client = OpenAI(
    base_url="https://api.zukko.pro/v1",
    api_key=os.environ["ZUKKO_API_KEY"],
)

MODEL = "gpt-6.1-sol"

Код требует Python 3.9 или новее (из-за Path.is_relative_to). Создайте рядом папку data, положите туда пару текстовых файлов со счетами и запустите скрипт.

Как устроен код

Инструменты

Каждый инструмент — это функция Python плюс её описание в TOOLS. Модель видит только описание: имя, текст description и схему параметров. От того, насколько понятно они написаны, зависит, вызовет ли модель инструмент вовремя. Если агент упорно не пользуется инструментом, сначала перепишите описание — подробнее в статье о том, почему агент не видит файлы↗.

Обратите внимание на защиту внутри функций. read_file не выпускает агента за пределы папки data, даже если модель попросит ../.env. calculate разбирает выражение через ast и не использует eval, поэтому выполнить произвольный код через него нельзя. Правило простое: всё, что пришло от модели, — недоверенный ввод.

Цикл

На каждом шаге агент отправляет всю историю: системный промпт, задачу, свои прошлые вызовы инструментов и их результаты. Если в ответе есть tool_calls, сначала в историю добавляется сообщение ассистента с этими вызовами, а потом по одному сообщению role: "tool" на каждый вызов с тем же tool_call_id. Если вызовов нет — это финальный ответ.

Ошибки инструментов не роняют программу, а возвращаются модели текстом. Так она может исправиться сама: например, взять правильное имя файла после «файл не найден».

Два предохранителя

• MAX_STEPS ограничивает число запросов к модели. Без него агент, который ходит по кругу, будет работать, пока не кончатся деньги.
• MAX_COST считает фактическую стоимость по полю usage каждого ответа. Для GPT шлюз учитывает чтение кэша (prompt_tokens_details.cached_tokens), поэтому кэшированная часть входа считается по своей цене. Для Claude в OpenAI-формате скидки за кэш нет, весь вход идёт по цене входа, — если переключаете агента на Claude, поставьте PRICE_CACHED равным PRICE_IN.

Третий предохранитель находится вне кода: отдельный API-ключ для агента с дневным и месячным лимитом в долларах и списком разрешённых моделей. Если код по ошибке уйдёт в бесконечный цикл, шлюз ответит 429 с кодом key_daily_limit_reached и остановит его. Как настроить — в документации по лимитам ключей↗.

Сколько стоит одна задача агента

Возьмём худший для нашего примера случай: агент использовал все 10 шагов, на каждом до 4 000 входных и 300 выходных токенов (по мере роста истории вход увеличивается, поэтому берём верхнюю оценку). Цены на 7 октября 2026, формула шаги × (вход × цена входа + выход × цена выхода) / 1 000 000, кэш не учитываем:

Бюджет MAX_COST = 0.05 с запасом покрывает такую задачу, но обрежет агента, если тот начнёт читать большие файлы или ходить по кругу. Цены — пример расчёта; актуальный список и цены — GET https://api.zukko.pro/v1/models или страница «Модели» в кабинете.

Какую модель поставить в MODEL, решают ваши задачи. Для ориентира в каталоге есть индекс силы (Intelligence Index от Artificial Analysis): Claude Opus 5.5 — 58, GPT-6.1 Sol — 52, DeepSeek V4.1 Flash — 39. Прогоните одну и ту же задачу на двух-трёх моделях и сравните, сколько шагов понадобилось, верен ли ответ и сколько списалось. Модель меняется одной строкой: шлюз принимает любую модель в OpenAI-формате.

Что добавить дальше

• Стриминг, если ответы длинные: в цикле по чанкам проверяйте if chunk.choices: перед chunk.choices[0] — последний чанк приходит с usage и пустым choices.
• Подтверждение опасных действий. Инструменты, которые что-то меняют (запись файлов, запросы к внешним API), лучше выполнять после подтверждения человеком.
• Сжатие истории. Длинная история дорожает с каждым шагом: старые результаты инструментов можно заменять кратким пересказом.
• Готовые инструменты по стандарту. Вместо самописных функций можно подключать MCP-серверы — что это такое, разобрано в статье что такое MCP-сервер↗.

Подробнее о клиенте — в справке по Python SDK↗ и документации chat/completions↗. Чтобы запустить пример, создайте в кабинете ключ для агента с небольшим дневным лимитом.

Частые вопросы

Нужен ли для агента LangChain или другой фреймворк?

Для старта — нет: цикл из примера умещается в несколько десятков строк, и вы видите каждый запрос. Фреймворки помогают, когда инструментов и агентов становится много.

Какую модель взять для агента?

Начните с gpt-6.1-sol как с середины по цене. Если задачи простые, проверьте deepseek-v4.1-flash, если сложные — claude-opus-5-5. Решайте по результату на своих задачах.

Можно ли дать агенту запускать команды в терминале?

Технически да, но это самый опасный инструмент. Если нужен, запускайте агента в изолированном окружении, ограничьте список команд и подтверждайте каждый запуск.

Почему агент отвечает текстом и не вызывает инструмент?

Чаще всего описание инструмента непонятно модели или задача сформулирована так, что инструмент кажется лишним. Уточните description, явно попросите пользоваться инструментами в системном промпте и проверьте другую модель.