Написать в Telegram

Python: как собрать своего ИИ-агента с нуля без фреймворков. Пошагово

Содержание
  1. Что понадобится
  2. Если вы работаете из России
  3. Ограничения и риски перед стартом
  4. Шаг 1. Готовим проект
  5. Шаг 2. Учим код разговаривать с моделью
  6. Шаг 3. Выбираем модель
  7. Шаг 4. Даём агенту инструменты
  8. Шаг 5. Включаем агентный цикл
  9. Шаг 6. Подключаем MCP-серверы
  10. Шаг 7. Добавляем память
  11. Шаг 8. Собираем полный harness
  12. Что дальше

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

Внутри проще, чем кажется. Языковая модель только получает текст и возвращает текст. Всё остальное делает код вокруг неё: даёт ей инструменты, память и возможность работать в цикле. Эту обвязку называют harness. Если сравнить с машиной, модель это двигатель, а harness всё остальное.

Соберём такую обвязку на чистом Python, без LangChain и CrewAI. Пройдём пять версий агента, а потом объединим их в маленькую копию Claude Code со слэш-командами. Для примера возьмём локальную модель, облачный ключ не нужен.

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

  • Python и uv. Менеджер uv создаёт проект и виртуальное окружение. В примере Python 3.13.
  • Редактор кода. В примере VS Code, подойдёт любой.
  • Библиотеки openai, mcp и pydantic. Агента мы всё равно пишем сами: openai просто отправляет запрос модели, mcp подключает внешние инструменты, pydantic нужна для типов.
  • Модель. Облачный ключ или локальная модель через Ollama.

Код в примере вставляют готовыми модулями и разбирают построчно. Печатать всё вручную необязательно.

Если вы работаете из России

Почти всё ставится локально: Python, uv, Ollama и библиотеки с открытым кодом. Модели Qwen, на которых построен пример, открытые. После скачивания они работают на вашем компьютере без API-ключа. Облачные сервисы вроде OpenAI из России могут быть недоступны, так что локальная модель здесь основной вариант.

Код обращается к модели через интерфейс, совместимый с OpenAI. Чтобы сменить модель, меняют адрес сервера, ключ и название модели. Значит, вместо Ollama можно подключить любой совместимый сервер: свой на открытой модели или российский, если он поддерживает такой формат.

Ограничения и риски перед стартом

  • Нужно подходящее железо. Хватит даже недорогой видеокарты или чипа серии M. На совсем слабом устройстве, например на телефоне, локальные модели работают плохо, лучше взять облачный ключ.
  • Первый ответ идёт дольше. Ollama сначала загружает модель. В примере модель на 4 млрд параметров отвечала медленнее, чем ожидалось.
  • Запись файлов опасна. Агент пишет файлы по просьбе модели. В примере он работает только в папке workspace. Не давайте доступ шире, чем нужно.
  • Это учебный пример. Для боевых задач понадобится больше проверок и ограничений.
  • Ключи не держите в коде. Их кладут в переменную окружения.

Шаг 1. Готовим проект

Создайте пустую папку, откройте её в редакторе и выполните в терминале:

uv init .

Лишние main.py и README.md можно удалить. Затем ставим библиотеки:

uv add mcp openai pydantic

Виртуальное окружение создаётся само.

Шаг 2. Учим код разговаривать с моделью

Первый файл назовём v0.py. Дальше на каждом шаге будет новый файл, v1, v2 и так далее, чтобы было видно, что добавляется.

Ядро это функция chat: принимает строку, возвращает строку. Внутри один вызов client.chat.completions.create, куда передаются модель и список сообщений. Это вся история разговора, у сообщений три роли:

  • system. Общие указания, например «ты полезный личный помощник».
  • user. То, что просит пользователь.
  • assistant. То, что уже ответила модель.

Текст ответа берут из response.choices[0].message.content, при пустом ответе возвращают пустую строку.

Код v0.py: клиент с адресом локального сервера Ollama и функция chat
Код v0.py: клиент с адресом локального сервера Ollama и функция chat

Шаг 3. Выбираем модель

Облачный ключ. Создайте ключ в кабинете сервиса, впишите в api_key, удалите строку base_url и поменяйте MODEL на нужную модель.

Локальная модель. Скачайте Ollama с официального сайта и установите. Проверьте командой ollama в терминале. Список скачанных моделей покажет:

ollama list

Подходящую модель ищут на сайте Ollama, ориентируясь на видеопамять. В примере взята qwen3.5:4b, а если она слишком медленная, есть qwen3.5:2b. Скачивают так:

ollama pull qwen3.5:4b

В коде остаётся адрес http://localhost:11434/v1 и название модели. Запустите v0.py, напишите «hello» и получите ответ. Выход по Ctrl+C.

Список моделей Ollama: на компьютере уже скачаны несколько вариантов Qwen
Список моделей Ollama: на компьютере уже скачаны несколько вариантов Qwen

Шаг 4. Даём агенту инструменты

В v1.py появляются «руки». Инструмент это обычная функция Python. Для примера две:

  • list_files показывает файлы в папке workspace;
  • read_file читает файл по имени.

Их кладут в словарь TOOLS. Но модель о функциях ничего не знает, ей нужна схема инструмента: тип function, имя, описание и параметры. У list_files параметров нет, у read_file обязателен filename типа string. Во фреймворках схемы создаются сами, здесь их пишут вручную. Если не получается, попросите ИИ-помощника написать схему по описанию функции.

Схема инструментов: у каждого описаны тип, имя, описание и параметры
Схема инструментов: у каждого описаны тип, имя, описание и параметры

Теперь chat передаёт модели список схем и смотрит в ответе поле tool_calls. Пусто, значит, возвращаем текст. Если нет, для каждого запроса разбираем аргументы, запускаем функцию, добавляем результат в сообщения с ролью tool и просим модель ответить ещё раз.

Создайте пустую папку workspace, запустите v1.py и спросите: «Какие файлы лежат в моей рабочей папке?». Агент вызовет list_files и скажет, что папка пуста.

Но если положить в папку два файла и попросить их прочитать, ответ придёт пустым. Модель вызвала list_files и захотела вызвать ещё read_file, а код разрешает только одну итерацию.

Шаг 5. Включаем агентный цикл

В v2.py добавляем инструмент write_file и заворачиваем код в цикл while True:

  1. Отправляем модели сообщения и схемы.
  2. Если в ответе нет tool_calls, это финальный ответ, выходим.
  3. Если есть, запускаем инструменты, добавляем результаты в сообщения и возвращаемся к пункту 1.

Агент делает один шаг или пятьдесят, сколько нужно модели. На этом цикле держится любой агент.

Код v2.py: цикл while True и выход, когда модель больше не просит инструменты
Код v2.py: цикл while True и выход, когда модель больше не просит инструменты

Повторим задачу из примера:

Перечисли все файлы в моей рабочей папке, расскажи, что в них, и создай новый файл с объединённым содержимым.

Агент вызвал list_files, прочитал оба файла и записал combined.txt.

Терминал: агент последовательно вызывает list_files, read_file и write_file
Терминал: агент последовательно вызывает list_files, read_file и write_file

Шаг 6. Подключаем MCP-серверы

Пока инструменты вписаны в код. MCP (Model Context Protocol) позволяет подключать готовые инструменты снаружи. Те же серверы вы могли видеть в Claude Code или Codex.

В v3.py код становится асинхронным: ответ сервера может прийти не сразу, и программа не должна замирать. Серверы описаны как команды запуска. В примере два через uvx, и при установленном uv ничего ставить не нужно:

  • mcp-server-time отдаёт время компьютера;
  • mcp-server-fetch загружает веб-страницы.

Функция connect_mcp запускает каждый сервер, запрашивает его инструменты и добавляет их в общий список схем. Для модели локальные и MCP-инструменты выглядят одинаково, а нужный вызов выбирает функция call_tool.

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

Терминал: подключены MCP-серверы time и fetch, у агента пять инструментов
Терминал: подключены MCP-серверы time и fetch, у агента пять инструментов

Шаг 7. Добавляем память

Закрыли программу, и модель всё забыла. Чтобы агент помнил что-то между запусками, факты хранят снаружи. В v4.py это файл memory.md.

Добавляются загрузка и сохранение памяти и инструмент save_memory с параметром fact. Память подставляется в системный промт: «вот что ты помнишь о пользователе с прошлых сессий», дальше текст из файла. Там же указание: узнал новый устойчивый факт, сохрани его через save_memory.

Проверка простая. Попросите агента запомнить ваше имя и возраст, и файл memory.md обновится. Перезапустите программу и спросите, как вас зовут: ответ возьмётся из файла. Так делает большинство обвязок, только поиск по памяти у них умнее.

Системный промт с подстановкой памяти и указанием сохранять новые факты
Системный промт с подстановкой памяти и указанием сохранять новые факты

Шаг 8. Собираем полный harness

Последняя версия, harness.py, объединяет всё и добавляет три вещи.

  • Файл mcp_servers.json. Список MCP-серверов читается из отдельного файла. Новый сервер добавляют одной записью.
  • Список моделей. В конфиге две локальные Qwen и облачные от OpenAI и Anthropic. Для облачных нужны ключи в окружении, в примере их нет.
  • Слэш-команды. Строка, начинающаяся с /, считается командой: /models, /model имя, /tools, /memory, /quit.
Файл mcp_servers.json: серверы time и fetch описаны командой и аргументами
Файл mcp_servers.json: серверы time и fetch описаны командой и аргументами

Командой /model local-small переключаемся на модель поменьше, пишем «hi» и получаем ответ. Команда /tools показывает семь инструментов: четыре локальных и три из MCP.

Терминал: переключение на local-small и список инструментов командой /tools
Терминал: переключение на local-small и список инструментов командой /tools

В финале даём задачу:

Наведи порядок в рабочей папке и собери краткое содержание всех документов в один текстовый файл.

Агент перечислил файлы, прочитал их и записал documents_summary.txt. Удалить лишнее он не смог: инструмента удаления ему не дали.

Итог: агент создал documents_summary.txt в папке workspace
Итог: агент создал documents_summary.txt в папке workspace

Что дальше

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

Мы в Агентехе учим сотрудников разбираться, как устроены ИИ-агенты, и собирать их под рабочие задачи: от первого агента до связки с внутренними системами. Как устроено обучение.

Написать в Telegram