ИИ‑агенты. Часть 1: Первые шаги

Всем привет! Сегодня я хочу рассказать вам про то, как я начал внедрять в процесс разработки ИИ‑агентов. Поделюсь своим опытом.

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

Что такое ИИ‑агент?

Я уже рассказывал, что такое нейронная сеть. И мы знаем, что 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.

Ещё можно выделить точечные скиллы, которые применяются и пишутся для одного проекта. 

А также универсальные, которые хранятся в специальной директории ИИ‑агента для скиллов и применяются ко всем проектам, с которыми работает агент.

Нужно ли явно указывать агенту на эти файлы?

Всё зависит от того, какую модель и расширение/приложение вы используете. В моём случае я в самом первом промпте пишу, что нужно посмотреть эти два файла обязательно.

💬 На этой ноте я бы хотел закончить. Обращу внимание, что переход на более умную модель Claude Haiku с llama-3.3–70b, написание хорошего agents.md и skills.md, а также хорошо продуманные промпты качественно улучшили разработку с ИИ‑агентом.