Содержание статьи
Всем привет! Сегодня я хочу рассказать вам про то, как я начал внедрять в процесс разработки ИИ-агентов. Поделюсь своим опытом.
Эта статья нацелена на начинающих, чтобы дать им первый толчок к использованию ИИ-агентов. Однако, если вы уже давно в этой теме, то буду рад вам в комментариях.
Что такое ИИ-агент?
Я уже рассказывал, что такое нейронная сеть. И мы знаем, что LLM тоже нейронная сеть (Transfomer точнее). Однако, что из себя представляет ИИ-агент я понял только сейчас.
ИИ-агент — это автономная программная система на базе больших языковых моделей (LLM, БЯМ), способная самостоятельно ставить цели, планировать многоступенчатые действия и использовать внешние инструменты для решения задач без постоянного участия человека.
Основными компонентами ИИ-агента являются:
1) Языковая модель (LLM), которая является мозгом агента, именно она генерирует шаги решения. Она выпускает мысли (reasoning traces) и указывает действия для выполнения.
2) Инструменты (Tools) — внешние функции или API, которые агент может вызывать для получения информации или выполнения операций.
Большинство ИИ-сред разработки (AI IDE) и ИИ-расширения для VS Code уже имеют встроенные инструменты для чтения и записи файлов, запуска команд в терминале и другие.
Инструменты регистрируются с именами и описаниями на естественном языке, чтобы модель знала, как ими пользоваться.
3) Исполнитель действий (Agent Executor) — принимает решение модели о действии, вызывает соответствующий инструмент и возвращает результат обратно модели.
4) Состояние агента (State) — накопленная история диалога и действий. Сюда входит запрос пользователя, сообщения модели (мысли/действия) и наблюдения (результаты инструментов). Состояние постоянно обновляется по мере выполнения шагов.
И важно, что это состояние передается полностью с каждым новым промтом. Таким образом, чем больше контекст, тем больше токенов тратиться с новым запросом. Чтобы минимизировать эту проблему существует механизм кэширования и сжатия контекста.
Какие AI-IDE, ИИ-расширения и модели использую я?
Сразу скажу, что я делюсь своим путём. Поэтому то, что использую я, не обязательно будет лучшим и правильным.
Для того, чтобы попробовать разные модели, а также не платить сразу 20+ долларов за подписку на ChatGPT и прочие модели, я решил пополнить баланс на $5 в OpenRouter.
Хотя подписка будет выгоднее в большинстве случаев и расширения codex, Claude code и прочие достаточно удобны.
OpenRouter — это платформа-агрегатор, которая предоставляет единый универсальный API для доступа к множеству различных моделей искусственного интеллекта через один API-ключ.
Для использования ИИ-агента я сначала решил использовать расширение Roo Code для VS Code, но с ним возникли трудности и я перешел на расширение Cline.
Первой тестовой дешевой моделью была Qwen 2.5 Coder 32B Instruct, но с ней была проблема: она не поддерживала инструменты или поддерживает их не так, как надо Cline (скорее всего из-за конфликта XML и JSON).
Наконец-то всё заработало с meta-llama/llama-3.3-70b-instruct. У неё копеечная стоимость на входной и выходной миллион токенов. Но мне она не сильно понравилась, об этом ниже. Спойлер: я сменил эту модель на Claude Haiku.
Как я организовал рабочее пространство?
Первым делом я подумал о безопасности и решил, что агент будет работать только в Docker-контейнере. А доступ ему дам к папке в контейнере через расширение Remote ssh.
Для ИИ-агента поднял следующий контейнер:
FROM python:3.12-slim RUN apt-get update && apt-get install -y openssh-server curl git docker.io docker-compose && rm -rf /var/lib/apt/lists/* RUN mkdir -p /var/run/sshd RUN echo ‘root:pxi’ | chpasswd RUN sed -i ‘s/#PermitRootLogin prohibit-password/PermitRootLogin yes/’ /etc/ssh/sshd_config COPY ./PXILUM /PXILUM WORKDIR /PXILUM EXPOSE 22 CMD [«/usr/sbin/sshd», «-D»]
Тут мы подняли ssh сервер, создали пользователя и разрешили подключаться к нему по паролю.
Однако, я хочу, чтоб он вёл разработку сам, используя контейнеризацию, поэтому я прокинул в его контейнер Unix-сокет демона Docker с хост-машины:
-v /var/run/docker.sock:/var/run/docker.sock
Благодаря этому он сможет создавать контейнеры на хосте, но это конечно небезопасно (root по сути дали), поэтому рекомендую работать с агентом на VPS.
Команда для создания образа:
docker build -t pxilum_agents .
Команда для запуска контейнера:
docker run -d -p 2222:22 -v var/run/docker.sock:/var/run/docker.sock -v «${PWD}/PXILUM:/PXILUM» —name pxilum_sandbox pxilum_agents
Проброс порта не обязателен, но он нам позволяет подключиться по localhost:2222, а не вводить каждый раз новый IP. А также подключиться к контейнеру даже с другого устройства.
После того, как мы подключились по ssh через расширение VS Code, заходим в нашу рабочую папку и нажимаем на расширение Cline, далее нужно нажать кнопку, которая установит это расширение внутрь нашего контейнера.
Вставляем наш API-ключ от OpenRouter в настройках Cline, выбираем модель и можем писать первый промпт. Режим act не забываем, для удобство ставим авто подтверждение действий агента.
Перед первым промтом я заранее создал другой моделью файлы agents.md и skills.md.
Что такое agents.md или AGENTS.md?
agents.md — это конфигурационный файл, который задает глобальный контекст, технический стек и правила игры для ИИ-агента (или группы агентов) в рамках проекта.
То есть туда можно написать абстрактно, что мы хотим, что нужно использовать (FastAPI, asyncio, Postgres). Какой роли должен придерживаться агент (архитектор, бэкенд-разработчик, тестировщик).
Можно написать условия разработки: используем контейнеры и .env, используем механизм router, обязательное тестирование перед сдачей и push в ветку dev.
Этот файл писать должны не вы, а другая модель (часто более умная, чем та, которая будет писать вам код). Вы лишь можете чуть корректировать его, если что-то модель написала не так.
Используем Git
Я упомянул, про push в ветку dev. Это на самом деле очень удобная и важная вещь.
Я добавил следующее в agents.md:
Каждая подзадача должна завершаться отдельным коммитом.
Начинать строго с номера задачи и пару слов задачи на русском языке. Шаблон: Task-[Номер задачи]: [Краткое описание изменений на русском].
После успешного тестирования задачи делать git push в GitLab репозиторий, я настроил ssh ключ. Создал для тебя ветку dev, работаешь только в ней. Для пуша: git push origin dev
Это позволяет мне откатиться на нужный коммит в случае проблем. А также отслеживать готовые задачи.
Откат с удалением изменений:
git reset —hard <хеш_коммита>
Переходим к skills.md или SKILL.md
Skills.md — это файл, который определяет как ИИ-агент должен выполнять конкретные задачи.
Каждый скилл состоит из 4 компонентов:
0) Шапка из полей name и description, выделенных 3 дефисами, именно по ним модель выбирает скилл.
1) Name / Identifier — уникальное имя или ID скилла, по которому ИИ-агент отличает этот скилл от сотен других.
2) Trigger — событие, по которому ИИ-агент должен среагировать и вызвать этот скилл.
3) Execution Pipeline — пошаговая инструкция, какие функции вызвать, куда перенаправить поток данных и в какую базу записать логи или как надо мыслить(например, триггер это написание фронтенда, при его написании пиши оригинально, не как Ии и тд).
Опять же это все не обязательно, это РЕКОМЕНДАЦИЯ, так пишут свои скиллы сами создатели Claude и GPT. Иногда хватает только шапки и названия, а дальше вольный текст. Но по хорошему это используем разметку md файла и пишем, как в примерах.
Вот часть моего skills.md:
# PXILUM Agent Execution Skills & Pipelines
## Skill: Inbound Mesh Packet Relay (Radio -> Web)
* Trigger: Коллбэк-поток обнаружил входящий бинарный пакет или LXMF-сообщение из радиоэфира.
* Execution Pipeline:
1. Перехватить сырые данные внутри синхронного коллбэка RNS.
2. Извлечь 16-байтный хэш криптографического Identity отправителя.
3. Безопасно передать payload в поток FastAPI через thread-safe queue (asyncio.Queue).
4. Асинхронно прочитать очередь фоновой задачей и записать лог в PostgreSQL.
5. Моментально сдирижировать пакет в активные WebSocket-соединения /ws для веб-пользователей.
Вот начало скилла от Anthropic:
—
name: frontend-design
description: Guidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don’t read as templated defaults.
license: Complete terms in LICENSE.txt
—
# Frontend Design
Approach this as the design lead at a design studio known for giving every client a distinct visual identity that is not mistaken for anyone else’s. This client has already rejected proposals that felt cliché or templated, and is paying for a distinctive point of view: make deliberate, opinionated choices about palette, typography, and layout that are specific to this brief, and take aesthetic risk if justified.
## Ground your designs in the subject matter
If the brief does not identify
Начало скилла от OpenAI:
—
name: figma-use
description: «**MANDATORY prerequisite** — you MUST invoke this skill BEFORE every use_figma tool call. NEVER call use_figma directly without loading this skill first. Skipping it causes common, hard-to-debug failures. Trigger whenever the user wants to perform a write action or a unique read action that requires JavaScript execution in the Figma file context — e.g. create/edit/delete nodes, set up variables or tokens, build components and variants, modify auto-layout or fills, bind variables to properties, or inspect file structure programmatically.»
—
# use_figma — Figma Plugin API Skill
Use use_figma MCP to execute JavaScript in Figma files via the Plugin API. All detailed reference docs live in references/.
Always pass skillNames: «figma-use» when calling use_figma. This is a logging parameter used to track skill usage — it does not affect execution.
If the task involves building or updating a full page, screen, or multi-section layout in Figma from code, also load [figma-generate-design](../figma-generate-design/SKILL.md). It provides the workflow for discovering design system components via search_design_system, importing them, and assembling screens incrementally. Both skills work together: this one for the API rules, that one for the screen-building workflow.
Before anything, load [plugin-api-standalone.index.md](references/plugin-api-standalone.index.md) to understand what is possible. When you are asked to write plugin API code, use this context to grep [plugin-api-standalone.d.ts](references/plugin-api-standalone.d.ts) for relevant types, methods, and properties. This is the definitive source of truth for the API surface. It is a large typings file, so do not load it all at once, grep for relevant sections as needed.
IMPORTANT: Whenever you work with design systems, start with [working-with-design-systems/wwds.md](references/working-with-design-systems/wwds.md) to understand the key concepts, processes, and guidelines for working with design systems in Figma. Then load the more specific references for components, variables, text styles, and effect styles as needed.
## 1. Critical Rules
1. Use return to send data back. The return value is JSON-serialized automatically (objects, arrays, strings, numbers). Do NOT call figma.closePlugin() or wrap code in an async IIFE — this is handled for you.
2. **Write plain JavaScript
Как вы уже поняли, необязательно писать под каждую задачу свой SKILL, скорее всего он уже кем-то написан и хорошо.
Вот пару ссылочек:
OpenAI: https://github.com/openai/skills
Anthropic: https://github.com/anthropics/skills
Google: https://github.com/google-gemini/gemini-skills
Можно выделить 3 категории скиллов: пользовательские, навыки от организаций, навыки партнёров.
Пользовательские — созданные самостоятельно для личного использования.
Навыки от организаций — когда у сотрудников компании есть корпоративные аккаунты и организация может предоставить им свои скиллы.
Навыки партнёров — скиллы в связке с MCP от крупных компаний, например, от Notion, Figma, Atlassian.
Ещё можно выделить точечные скиллы, которые применяются и пишутся для одного проекта.
А также универсальные, которые хранятся в специальной директории ИИ-агента для скиллов и применяются ко всем проектам, с которыми работает агент.
Нужно ли явно указывать агенту на эти файлы?
Всё зависит от того, какую модель и расширение/приложение вы используете. В моём случае я в самом первом промпте пишу, что нужно посмотреть эти два файла обязательно.
Загрузка...
