Установка ИИ-агента: пошаговое руководство

Сам по себе агент не содержит искусственного интеллекта: его «мозг» — внешняя языковая модель, а harness — оболочка, которая связывает модель с инструментами: файловой системой, терминалом и git. Модель решает, что сделать, harness — как это сделать в реальном проекте.

Что умеет типовой coding agent

1. Читать и редактировать файлы проекта.
2. Выполнять команды в терминале.
3. Работать с git: коммитить, смотреть diff, откатывать изменения.
4. Запускать тесты и проверять результат.
5. Изучать кодовую базу и отвечать на вопросы о ней.
6. Выполнять многошаговые задачи с промежуточными проверками.

Важно сразу разделить понятия: модель, harness, агент и среда — разные вещи. Подробная терминология будет в отдельном уроке, но базовая схема нужна уже сейчас, чтобы корректно установить и настроить инструмент.

CLI-агенты

Работают прямо в терминале. Лёгкие, быстрые, запускаются из любой папки и не зависят от редактора кода. Основной формат курса — именно терминальный агент: он даёт полный контроль над происходящим и лучше всего показывает механику сессий, контекста и разрешений, о которых пойдёт речь дальше.

Расширения для IDE

Встраиваются в редактор кода: рядом с файлами появляется панель чата, а изменения подсвечиваются прямо в тексте. Удобны для визуальной работы и быстрых правок, но плотнее связаны с конкретным редактором и его версией.

Десктоп-приложения

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

Перед установкой убедитесь, что окружение готово. Большинство агентов требуют наличия git, а CLI-версии часто работают на Node.js или Python. Проверьте версии — это займёт минуту и избавит от сюрпризов.

git --version
node --version
npm --version

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

Современные агенты устанавливаются одним из трёх способов. Выбор зависит от агента и вашей операционной системы, но структура всегда одинакова: скачать, установить, проверить.

Установка через менеджер пакетов

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

npm install -g имя-пакета

Официальный установщик

Многие агенты распространяются как установочный скрипт или программа-инсталлятор. Скрипт запускается одной командой, но адрес нужно брать только с официального сайта проекта.

curl -fsSL адрес-установщика | bash

Проверка установки

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

имя-агента --version

Появление номера версии — первый критерий приёмки. Если команда не найдена, причина почти всегда одна: каталог, куда установился агент, не добавлен в переменную окружения PATH. Перезапустите терминал или добавьте путь вручную, как указано в документации.

Способ подключения напрямую зависит от того, что вы выбрали в уроке про планы и модели: подписку или оплату за использование.

1. Логин в аккаунте — агент сам отправляет запросы через ваш аккаунт провайдера. Проще всего, работает по подписке.
2. API-ключ — вы получаете ключ у провайдера и указываете его агенту. Подходит для оплаты за использование.
3. Локальная модель — модель запущена на вашей машине. Максимальная приватность, но нужна мощная техника.

Ключ обычно передаётся через переменную окружения или конфигурационный файл. Пример с переменной окружения:

export AGENT_API_KEY=ваш-ключ

Чтобы ключ применялся автоматически в каждой новой сессии, добавьте эту строку в файл настроек вашей оболочки — .zshrc, .bashrc или аналогичный. Никогда не вставляйте ключ прямо в команды, которые попадают в историю терминала.

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

Вы: Опиши структуру этого проекта и что делает файл main.js.
Агент: В проекте два каталога: src и tests. Файл src/main.js выводит
в консоль приветственное сообщение. Тестов пока нет.

Критерий приёмки первой проверки: агент отвечает по делу, видит реальные файлы и не выдумывает несуществующие. Если ответ совпадает с тем, что вы знаете о проекте, — подключение выполнено верно. Подробнее о том, как читать ответы агента и доверять им, — в уроках про галлюцинации и проверку результата.

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

{
  "model": "default",
  "theme": "dark",
  "permissions": "ask"
}

Сейчас достаточно минимума: модель по умолчанию и режим разрешений. Остальные параметры — разрешения, начальный контекст, статусная строка — разберём по мере прохождения курса, когда появятся соответствующие темы. Не настраивайте всё сразу: лишние изменения в конфиге сложнее отлаживать.

1. Скачивайте агентов только с официальных сайтов и проверенных менеджеров пакетов.
2. Читайте установочные скрипты перед запуском, особенно из неизвестных источников.
3. Не храните API-ключи в файлах проекта и в истории терминала.
4. На время обучения работайте только в учебном репозитории.
5. Обновляйте агента отдельно от рабочих задач — обновление может изменить поведение.
6. Регулярно коммитьте изменения, чтобы любой эксперимент можно было откатить.

Безопасность — это не параноидальные ограничения, а условие спокойной работы. Когда вы уверены, что агент не навредит проекту, вы смелее экспериментируете и быстрее учитесь.

1. Установка с непроверенных источников «по совету из чата».
2. Пропуск проверки окружения — установка падает на непонятной ошибке.
3. Не проверенная после установки версия — агент «не найден» в терминале.
4. Ключ, закоммиченный в репозиторий вместе с проектом.
5. Установка нескольких агентов сразу и путаница в командах.
6. Настройка всего конфига «на глаз» без проверки каждого пункта.

Мы установили и настроили coding agent: выбрали тип, проверили окружение, выполнили установку, подключили модель и убедились, что агент видит учебный проект и отвечает на запросы. Теперь у вас есть рабочий инструмент и понимание, как безопасно им пользоваться.

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

1. Coding agent — программа, выполняющая задачи в коде по команде на естественном языке.
2. Harness — оболочка, связывающая языковую модель с инструментами разработки.
3. LLM — большая языковая модель, «мозг» агента.
4. CLI — интерфейс командной строки, работа в терминале.
5. IDE — среда разработки, редактор кода.
6. Десктоп-приложение — программа с графическим интерфейсом.
7. API-ключ — секретный идентификатор доступа к модели.
8. Переменная окружения — настройка, доступная программам в системе.
9. PATH — список каталогов, где система ищет исполняемые файлы.
10. Конфигурационный файл — файл с настройками программы.
11. Промпт — запрос пользователя к агенту или модели.
12. Менеджер пакетов — инструмент установки и обновления программ.
13. Установщик — программа или скрипт, устанавливающий приложение.
14. Критерий приёмки — условие, по которому задача считается выполненной.
15. Version — номер версии программы, выводимый флагом —version.
16. Локальная модель — модель, запущенная на собственной машине пользователя.