Python: как собрать своего ИИ-агента с нуля без фреймворков. Пошагово
Содержание
- Что понадобится
- Если вы работаете из России
- Ограничения и риски перед стартом
- Шаг 1. Готовим проект
- Шаг 2. Учим код разговаривать с моделью
- Шаг 3. Выбираем модель
- Шаг 4. Даём агенту инструменты
- Шаг 5. Включаем агентный цикл
- Шаг 6. Подключаем MCP-серверы
- Шаг 7. Добавляем память
- Шаг 8. Собираем полный harness
- Что дальше
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, при пустом ответе возвращают пустую строку.

Шаг 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.

Шаг 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:
- Отправляем модели сообщения и схемы.
- Если в ответе нет
tool_calls, это финальный ответ, выходим. - Если есть, запускаем инструменты, добавляем результаты в сообщения и возвращаемся к пункту 1.
Агент делает один шаг или пятьдесят, сколько нужно модели. На этом цикле держится любой агент.

Повторим задачу из примера:
Перечисли все файлы в моей рабочей папке, расскажи, что в них, и создай новый файл с объединённым содержимым.
Агент вызвал list_files, прочитал оба файла и записал combined.txt.

Шаг 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. А вот сохранить содержимое в файл он не сможет: инструмента записи в этой версии нет, и модель так и скажет.

Шаг 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.

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

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

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