Как создать ИИ-агента: рабочий агент на Python за 57 строк и что нужно ему дальше

Я каждый день работаю с несколькими ИИ-агентами. Один живёт на Маке и отвечает мне в Telegram, другие пишут код, ищут информацию и ведут задачи на доске. Почти все они собраны из готовых частей. Ниже покажу, из чего состоит любой агент, соберу простого ИИ-агента своими руками и расскажу, что пришлось добавлять, когда агенты начали делать реальную работу.

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

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

У любого агента три части:

• Модель. Claude, GPT, Gemini или локальная нейросеть. Она читает задачу и решает, что делать.
• Инструменты. Функции, которые модель может вызвать: прочитать файл, выполнить команду, отправить сообщение. Модель сама ничего не делает, она только просит программу вызвать инструмент с нужными аргументами.
• Цикл. Программа отправляет модели задачу, выполняет инструмент, который та попросила, возвращает результат и снова спрашивает модель. Так до тех пор, пока модель не ответит без вызова инструмента.

Всё остальное (память, навыки, права, несколько агентов в команде) надстраивается поверх этих трёх частей.

Три способа создать ИИ-агента

Создание ИИ-агента можно начать с одного из трёх путей. Выбор зависит от задачи и от того, готовы ли вы писать код.

Без кода. Конструкторы вроде n8n или встроенные агенты в ChatGPT и Claude. Собираешь схему из блоков или пишешь инструкцию и подключаешь сервисы. Подходит, если задача простая и укладывается в готовые интеграции. Для нестандартных задач в них тоже можно дописать свой код или запросы к API, но тогда это уже наполовину программирование.

Готовый агент, который настраиваешь под себя. Hermes Agent, OpenClaw, Claude Code, Codex. Цикл, инструменты, память и права там уже есть, и основная работа по настройке ИИ-агента состоит в том, чтобы добавить свои навыки, правила и доступы. Так я делаю почти всё: мой основной агент работает на Hermes Agent, в нём 204 навыка, и большую часть я написал под свои задачи.

С нуля через SDK или API. Этот путь нужен, если агент работает внутри своего продукта и вы сами отвечаете за его разработку. У OpenAI для этого есть Agents SDK, у Anthropic есть Agent SDK, в котором тот же цикл и инструменты, что в Claude Code. Можно обойтись и без SDK, напрямую через API модели. Ниже как раз такой вариант, чтобы было видно, что внутри.

Как создать ИИ-агента на Python: пошагово

Соберу агента, который отвечает на вопросы о файлах на компьютере. Модель локальная: нейросеть работает на самом компьютере через Ollama, а код обращается к её API на localhost, поэтому ни ключей, ни оплаты не нужно. Я запускал на MacBook с M1 Pro и 16 ГБ памяти, модель Qwen2.5 7B.

Шаг 1. Поставить Ollama и скачать модель. Скачать Ollama можно с официального сайта. После установки запустите её и загрузите модель одной командой:

ollama pull qwen2.5:7b-instruct-q4_K_M

Модель весит 4,7 ГБ. Нужна та, что умеет вызывать инструменты: у Qwen2.5 и Qwen3 в Ollama это есть.

Шаг 2. Написать инструмент. Обычная функция на Python, которая возвращает список файлов в папке и их размеры.

Шаг 3. Описать инструмент для модели. Модель не видит код функции. Ей нужны имя, описание и список аргументов, которые принимает инструмент. Это JSON-схема, которую мы передаём вместе с запросом.

Шаг 4. Написать цикл. Отправить модели задачу, посмотреть, просит ли она инструмент, выполнить его, вернуть результат и спросить снова.

Весь агент целиком, только стандартная библиотека Python:

import json, os, urllib.request

MODEL = "qwen2.5:7b-instruct-q4_K_M"

def list_files(path):
    """Инструмент: список файлов в папке с размерами."""
    out = []
    for name in sorted(os.listdir(path)):
        full = os.path.join(path, name)
        if os.path.isfile(full):
            out.append({"name": name, "kb": round(os.path.getsize(full) / 1024, 1)})
    return out

TOOLS = [{
    "type": "function",
    "function": {
        "name": "list_files",
        "description": "Список файлов в папке и их размеры в КБ",
        "parameters": {
            "type": "object",
            "properties": {"path": {"type": "string", "description": "путь к папке"}},
            "required": ["path"],
        },
    },
}]

def chat(messages):
    body = json.dumps({"model": MODEL, "messages": messages,
                       "tools": TOOLS, "stream": False}).encode()
    req = urllib.request.Request("http://localhost:11434/api/chat", body,
                                 {"Content-Type": "application/json"})
    return json.load(urllib.request.urlopen(req, timeout=120))["message"]

def agent(task, max_steps=5):
    messages = [
        {"role": "system", "content": "Ты агент. Пользуйся инструментами, отвечай коротко."},
        {"role": "user", "content": task},
    ]
    for step in range(max_steps):
        msg = chat(messages)
        messages.append(msg)
        calls = msg.get("tool_calls") or []
        if not calls:
            return msg["content"]              # модель ответила, цикл окончен
        for call in calls:
            name, args = call["function"]["name"], call["function"]["arguments"]
            print(f"шаг {step + 1}: {name}({args})")
            if name == "list_files":
                result = list_files(**args)
            else:                                # модель выдумала инструмент
                result = {"error": f"нет инструмента {name}"}
            messages.append({"role": "tool", "tool_name": name,
                             "content": json.dumps(result, ensure_ascii=False)})
    return "Не уложился в лимит шагов"

if __name__ == "__main__":
    print(agent("Какой самый большой файл в папке /etc? Назови имя и размер в КБ."))

Запуск:

шаг 1: list_files({'path': '/etc'})
Самый большой файл в папке /etc — это файл services с размером 662.4 КБ.

Модель сама решила вызвать инструмент, сама подставила путь, получила список и нашла в нём самый большой файл. Ответ пришёл за 6–7 секунд. Я проверил командой ls: так и есть, services, 678 260 байт. Килобайт здесь считаю по 1024 байта, строго это кибибайт (КиБ).

max_steps в цикле обязателен. Без него агент, который запутался, будет вызывать инструменты бесконечно. У моего основного агента тоже есть такой лимит, только побольше. Ещё две защиты стоят одной строки каждая: таймаут у запроса к модели, чтобы агент не завис, и проверка имени инструмента, чтобы модель не запустила то, чего нет. Для настоящей работы к этому добавляется обработка ошибок сети и файловой системы.

Где агент ошибся и как я это исправил

В первой версии инструмент отдавал размер в байтах, а пересчёт в килобайты я оставил модели. Три запуска из трёх она нашла правильный файл и три раза из трёх ошиблась в пересчёте: написала 678,26 КБ. Она поделила на тысячу вместо 1024 и уверенно выдала результат.

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

Это правило я потом применяю везде. Всё, что можно посчитать или проверить кодом, должен делать инструмент. Модель решает, какой шаг сделать, и формулирует ответ. Арифметика, даты, поиск по файлам и проверки статуса остаются инструментам. Чем меньше модель считает в уме, тем меньше она галлюцинирует.

Что нужно агенту, кроме цикла

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

• Память между сессиями. Без неё агент каждый раз начинает с нуля, и ты заново объясняешь, где что лежит. У моего агента постоянная память ограничена 2200 символами, туда попадают только факты, нужные в каждой сессии. Остальное лежит в навыках и базе знаний. Как я это раскладываю, описал в статье про контекст ИИ-агента.
• Навыки. Инструкции под конкретную задачу, которые агент подгружает, когда задача подходит: как публиковать статью, как делать обложку, как проверять сервер. Это дешевле, чем держать всё в одном огромном промпте.
• Права. Агенту, который может выполнять команды, нужно запретить опасное без подтверждения. У меня удаление, оплата, публикация и всё, что нельзя откатить, идёт только после моего «ок».
• Лимит шагов и учёт расходов. Однажды агент за одну сессию сделал 60 вызовов, просто чтобы проверить, не закончилась ли задача. Контекст был большой, вышло около 21 миллиона токенов без всякого результата. После этого появилось правило: никаких циклов ожидания, только уведомление о завершении. Почему длинная сессия обходится так дорого, я разобрал в статье про контекстное окно.
• Проверка результата. Агент охотно сообщает «готово», когда сделал половину. Моих агентов проверяет вторая модель другого семейства, и отчёт без реальной проверки, теста или команды не считается выполненным.

Когда одного агента становится мало, задачи делят между несколькими, и получается мультиагентная система. Как у меня они работают вместе, рассказал отдельно в статье про несколько ИИ-агентов.

С чего начать

Если хочется понять, как работает агент, соберите пример выше. На это уйдёт полчаса вместе с установкой Ollama.

Если агент нужен для работы, начинайте с готового: Hermes Agent, Claude Code или Codex. Писать свой цикл, права и память с нуля имеет смысл только внутри собственного продукта. Для личных задач готовый агент с вашими навыками закроет больше, чем самописный, и вы не будете тратить время на то, что уже сделано.