Libraries как Agentic Executables
Представьте, что библиотеки можно устанавливать / настраивать и удалять (на любом языке и в любом фреймворке) так же легко, как любое приложение или игру на телефоне или компьютере?
Эта статья о том, как мы можем это сделать.
Или другими словами, framework Agentic Executables (далее - "AE") рассматрив��ют библиотеки как исполняемые программы со структурированными, понятными для AI агента инструкциями. Вместо того чтобы полагаться на документацию написанную для людей, AI-агенты следуют стандартизированным .md файлам для автономной установки, настройки, интеграции, обновления и удаления библиотек.
Я решил разделить статью на несколько частей:
Если вы хотите перейти к архитектуре реализации, нажмите здесь.
Если вы хотите использовать это сегодня, нажмите здесь.
Начнем с части "Почему (Проблема)".
Почему (Проблема)
В настоящее время, на момент написания этой статьи, для любого проекта разработки (т.е. программного проекта) мы обычно используем библиотеки или пакеты для эффективного повторного исполь��ования кода.
Некоторые библиотеки, особенно настраиваемые, часто имеют большую документацию и примеры не только по установке, но и по настройке, использованию, тестированию и удалению.
Обычный флоу установки, настройки и использования может выглядеть так:
мы используем CLI или менеджер пакетов для установки/поиска библиотеки
читаем документацию, чтобы понять, что нужно сделать для ее использования.
анализируем свою кодовую базу, чтобы понять, как ее можно интегрировать.
пытаемся применить код из библиотеки к нашей кодовой базе и нашему решению (с точки зрения структуры/архитектуры кодовой базы)
при необходимости настраиваем библиотеку (ключи, конфигурации, etc)
пытаемся протестировать (визуально или с помощью тестов), чтобы убедиться, что все работает.
вносим исправления в код.
добавляем тесты или конфигурацию при необходимости.
Что еще более важно - все инструкции / документация изначально написаны для людей.
И обычно большинство этих шагов мы, как люди, стараемся выполнять шаг за шагом.
Однако, с развитием AI-агентов - что, если мы будем рассматривать библиотеки и пакеты не как абстрактные повторно используемые части кода, а как исполняемые программы? Программы с такой же способностью устанавливаться, настраиваться, использоваться и удаляться, как обычные приложения или игры на телефоне?
Если вы это представили - давайте назовем это "Agentic Executables" (далее - "AE") и погрузимся в то, как мы можем их создавать / поддерживать :)
Как (Решение)
Прежде всего, давайте установим мета-правила для создания и изменения файлов AE:
AE Domain Knowledge - термины, концепции, принципы того, что такое AE, чтобы дать достаточно контекста для AI-агента. Этот файл поможет нам поддерживать файлы.
Создание установки с тремя логическими шагами:
Установка (с использованием CLI или менеджера пакетов)
Настройка
Интеграция
Создание использования.
Создание удаления.
Учитывая все это, давайте определим принципы работы с AE.
Принципы работы:
Основные принципы
Agentic First - Документация AE написана для AI, а не для людей. Поэтому AI-агенты могут работать автономно без или с минимальным вмешательством человека.
Modularity - Четкие, многократно используемые шаги и примеры.
Domain Knowledge - Собираение и настройка промптов конкретно для библиотеки, специально разработанные для AI-агента и готовые к использованию в конечном проекте.
Reversibility - Способность удаления библиотеки.
Validation - Или как проверить что все работает как запланировано.
Language / Framework Agnostic - Работает во всех frameworks и языках.
Основная идея
Основная идея заключается в передаче мета-правил AI-агенту, чтобы дать ему возможность:
поддерживать исполняемые файлы библиотеки (в основном - мета-инструкции) 1.1 Основные термины и Domain Knowledge (что такое AE и как он работает) -
ae_context.mdЦЕЛЬ: Поддерживать файлыae_bootstrapиae_usageПОЛЬЗОВАТЕЛЬ: Автор библиотеки или контрибьютор 1.2 Файл для поддержки исполняемых файлов библиотеки -ae_bootstrap.md. ЦЕЛЬ: Создать структуру файлов AE и поддерживать ее. ПОЛЬЗОВАТЕЛЬ: Автор библиотеки или контрибьютор 1.3 Файл для использования файлов AE в библиотеке -ae_usage.mdЦЕЛЬ: Использовать файлы AE этой библиотеки. ПОЛЬЗОВАТЕЛЬ: Конечный пользователь (другими словами - разработчик, использующий эту библиотеку)возможность устанавливать / удалять / обновлять (в основном, одноразовые правила использования) создаются с помощью файла
ae_bootstrap.md. 2.1 Файлы установки, настройки, интеграции -ae_install.mdЦЕЛЬ: Установить, настроить и интегрировать библиотеку. ПОЛЬЗОВАТЕЛЬ: Конечный пользователь 2.2 Файл удаления -ae_uninstall.mdЦЕЛЬ: Удалить библиотеку. ПОЛЬЗОВАТЕЛЬ: Конечный пользователь 2.3 Файл обновления -ae_update.mdЦЕЛЬ: Обновить библиотеку со старой вер��ии на новую. ПОЛЬЗОВАТЕЛЬ: Конечный пользовательвозможность частого использования библиотеки / или в зависимости от необходимости. Создается с помощью файла
ae_use.md. 3.1 Файл использования - правило, адаптированное к названию библиотеки. Например, для библиотеки с названиемgo_routerи использования Cursor AI это может быть правило в путиgo_router_usage.mdc. Во время установки в кодовую базу пользователя AI-агент должен спросить пользователя, какой AI-агент следует использовать, и разместить / назвать его соответствующим образом. Например, если пользователь хочет использовать Cursor AI, AI-агент должен разместить это правило по пути.cursor/rules/go_router_usage.mdc. ЦЕЛЬ: Частое использование библиотеки / или в зависимости от необходимости. ПОЛЬЗОВАТЕЛЬ: Конечный пользователь
Структура файлов AE:
root/
├── ae/
│ ├── ae_context.md
│ ├── ae_bootstrap.md
│ ├── ae_use.md
Файлы AE библиотеки будут находиться в папке root/ai_use.
В итоге структура файлов AE библиотеки будет следующей:
root/
├── ai_use/
│ ├── ae_install.md
│ ├── ae_uninstall.md
│ ├── ae_update.md
│ ├── ae_use.md
Архитектура имплементации
Для имплементации этого решения я создал реестр (registry) файлов AE, чтобы централизовать их и сделать легкодоступными для разработчиков.
Вот как это работает на высоком уровне:
Workflow Overview
Автор библиотеки Registry Разработчик
│ │ │
├─► Создать файлы AE │ │
├─► Отправить в Registry ─────►│ │
│ │◄─── Получить файлы AE ────┤
│ │ │
│ │ AI-агент выполняет
│ │ установку
Чтобы упростить использование, я разработал MCP-сервер, который дает возможность AI-агентам получать инструкции и поддерживать экосистему AE как для разработчиков, так и для авторов библиотек.
Начнем с примера для конечных разработчиков: как они могут использовать файлы AE.
С MCP-сервером рабочий процесс довольно прост:
Пример рабочего процесса установки:
┌─────────────────────────────────────────────────────┐
│ Developer: Install library 'requests' │
└──────────────────────┬──────────────────────────────┘
│
▼
┌──────────────────���──────────────────────────────────┐
│ AI agent calls MCP │
└──────────────────────┬──────────────────────────────┘
│
▼
╔═════════════════════════════════════════════════════╗
║ manage_ae_registry ║
║ library_id: python_requests ║
║ action: install ║
╚══════════════════════┬══════════════════════════════╝
│
▼
┌─────────────────────────────────────────────────────┐
│ MCP returns ae_install.md │
└──────────────────────┬──────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────┐
│ AI agent analyzes instructions │
└──────────────────────┬──────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────┐
│ AI agent presents execution plan │
└──────────────────────┬──────────────────────────────┘
│
▼
╱───────────────╲
╱ Developer ╲
│ Approves? │
╲ ╱
╲───┬───────┬───╱
│ │
Yes │ │ No
│ └──────────────────┐
│ │
▼ ▼
┌─────────────────────────────────┐ ┌──────────────────┐
│ AI agent executes installation │ │ Correct plan │
└──────────────┬──────────────────┘ └────────┬─────────┘
│ │
│ │
│ ┌───────────────┘
│ │
│ └──────────────────────┐
│ │
▼ │
╔═════════════════════════════════╗ │
║ verify_ae_implementation ║ │
╚══════════════┬══════════════════╝ │
│ │
▼ │
╔═════════════════════════════════╗ │
║ ✅ Library installed ║ │
║ and verified ║ │
╚═════════════════════════════════╝ │
│
┌───────────────────────────────────┘
│
└──► (loops back to "AI agent presents execution plan")
Тот же рабочий процесс применяется и для других действий, таких как использование, удаление, обновление.
Как видите, каждое действие выполняется AI-агентом, и с MCP-сервером его легко реализовать и поддерживать.
Рабочий процесс автора библиотеки:
Почти такой же рабочий процесс работает и для авторов библиотек - они могут просто попросить AI-агента создать или обновить файлы AE, и AI-агент сделает все остальное.
Единственное исключение - для отправки файлов AE в реестр нам все еще нужно отправить PR в репозиторий регистра.
(думаю, это можно автоматизировать в будущем).
┌─────────────────────────────────────────────────────┐
│ Library Author: Publish 'axios' in AE │
└──────────────────────┬──────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────┐
│ AI agent calls MCP │
└──────────────────────┬──────────────────────────────┘
│
▼
╔═════════════════════════════════════════════════════╗
║ get_ae_instructions ║
║ context: library ║
║ action: bootstrap ║
╚══════════════════════┬══��═══════════════════════════╝
│
▼
┌─────────────────────────────────────────────────────┐
│ MCP returns ae_bootstrap.md │
│ + ae_context.md │
└──────────────────────┬──────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────┐
│ AI agent analyzes codebase │
└──────────────────────┬──────────────────────────────┘
│
▼
╔═════════════════════════════════════════════════════╗
║ AI agent creates AE files ║
║ - ae_install.md ║
║ - ae_uninstall.md ║
║ - ae_update.md ║
║ - ae_use.md ║
╚══════════════════════┬══════════════════════════════╝
│
▼
┌─────────────────────────────────────────────────────┐
│ evaluate_ae_compliance │
└──────────────────────┬──────────────────────────────┘
│
▼
╱───────────────╲
╱ Evaluation ╲
│ Passed? │
╲ ╱
╲───┬───────┬───╱
│ │
Yes│ │No
│ │
│ └──────────────────┐
│ │
│ ▼
│ ┌─────────────────────┐
│ │ Optimize files │
│ └──────────┬──────────┘
│ │
│ ┌────────────┘
│ │
│ └─────► (loops back to "AI agent creates AE files")
│
▼
╔═════════════════════════════════════════════════════╗
║ manage_ae_registry ║
║ operation: submit_to_registry ║
╚══════════════════════┬══════════════════════════════╝
│
▼
┌─────────────────────────────────────────────────────┐
│ MCP returns PR instructions │
└──────────────────────┬──────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────┐
│ Submit PR to registry │
└──────────────────────┬──────────────────────────────┘
│
▼
╔═════════════════════════════════════════════════════╗
║ ✅ Library published in registry ║
╚═════════════════════════════════════════════════════╝
Вот и все :)
На момент написания этой статьи я начал тестировать регистр и MCP-сервер на личных проектах, и, несмотря на некоторые ошибки (конечно), установка / удаление / настройка уже работают.
Как использовать это сегодня?
Вы разработчик:
Сначала нужно установить MCP-сервер.
Для этого, пожалуйста, перетащите файл https://github.com/fluent-meaning-symbiotic/agentic_executables/blob/main/agentic_executables_mcp/ae_install.md в своего AI-агента или установите его вручную.Затем используйте:
для установки библиотеки (убедитесь, что она есть в регистре), напишите своему AI-агенту:
create a plan to install "название_библиотеки" as aeдля удаления -
create a plan to uninstall "название_библиотеки" as aeдля обновления -
create a plan to update "название_библиотеки" as aeдля использования -
create rules for {AI-агента} to use "название_библиотеки" as ae
Вот и все :)
Вы автор | контрибьютор библиотеки:
для создания / обновления -
create a plan to bootstrap / update "название_библиотеки" as aeдля отправки в регистр -
create a plan to submit "название_библиотеки" to registry as ae
Вот и все :)
Заключение
Пожалуйста, поделитесь своими мыслями в комментариях (это будет для меня большой поддержкой и мотивацией)! :-)
Спасибо за ваше время и хорошего дня!
Антон
