Архитектура агента

Сначала — то, что ты уже знаешь: чат

Представь обычный чат с нейросетью. Ты пишешь вопрос — она отвечает текстом. Спросил про погоду — получил прогноз. Попросил объяснить термин — получил объяснение. Всё начинается с твоего вопроса и заканчивается её ответом.

А теперь заметь важное: за пределами окна чата ничего не происходит. Нейросеть не может открыть файл, поменять его или запустить программу. Она только говорит.

А что, если дать нейросети руки?

А теперь представь, что той же нейросети разрешили не только говорить, но и действовать. Она может открыть файл и посмотреть, что внутри. Может изменить его. Может запустить команду — например, проверку.

Вот такую «нейросеть с руками» мы и называем агентом. Мозг остался прежним — это та же модель, что в чате. Но теперь у неё есть руки и возможность работать с твоим проектом.

Из чего собран агент

Чтобы агент работал, нужны три вещи.

Мозг — LLM. Она рассуждает и пишет текст. Это та самая модель из первого уровня — документа «Как устроены LLM».

Руки — инструменты. Читать файлы, менять их, запускать команды.

Порядок — цикл. В какой последовательности мозг и руки работают.

Без мозга агент — бездумный механизм. Без рук — бесполезный собеседник. Без порядка — хаос. Вместе это и есть агент: LLM + инструменты + цикл.

Как агент работает: цикл

Порядок работы — цикл из четырёх шагов. На уровне 0 ты видел его без плана: задача → действие → проверка. Теперь разворачиваем полностью — план стал отдельным шагом. И вот что важно: агент работает текстом — каждый шаг это его мысль, которую он проговаривает. Смотри, как это выглядит на нашей задаче про старый номер телефона.

Шаг 1 — задача. Ты ставишь её словами: «найди все места со старым номером телефона на странице и замени на новый».

Шаг 2 — план. Агент разбивает задачу на шаги и проговаривает план: «Найти, где на странице старый номер → заменить → проверить».

Шаг 3 — действие. Работают руки: прочитать файл, найти нужное место, внести изменение.

Шаг 4 — проверка. Агент запускает проверки проекта и смотрит, всё ли получилось.

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

Сейчас увидишь это на живом примере — нажимай, агент пройдёт круг шаг за шагом. Пример будет другой: на странице магазина опечатка в заголовке.

Почему это важно понимать

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

Поэтому хорошая задача — это рамки: что сделать, что не трогать и как проверить результат. К этому вернёмся в разделе «Как ставить задачу» (04).

Где живёт агент: папка проекта

Агент работает не «где-то в облаке» и не «везде сразу». У него есть конкретное место — папка на твоём компьютере. В этой папке лежат файлы проекта, и именно с ними агент работает.

Эту папку называют рабочей областью агента. Запомни это слово — оно ещё встретится.

Почему именно папка, а не весь компьютер? Во-первых, агент не запутается в чужих файлах: на его «столе» только то, что нужно для проекта. Во-вторых, он не сломает лишнее: за границами папки ничего не трогает. В-третьих, тебе понятно, где искать результат — всё в одном месте.

Представь, как агент «просыпается» внутри папки — как работник, который пришёл в свой цех, а не на весь завод. Он запускается в папке через терминал (разберём в Уровне 3) и первым делом оглядывается: смотрит, что лежит вокруг.

А что лежит внутри такой папки? Заглянем.

Наш пример: проект flower-shop

Дальше в документе мы будем работать с одним и тем же проектом — flower-shop, магазин цветов. Этот магазин знаком тебе по первому уровню: там мы делали его страницу в примерах с токенами и промптами. Теперь это наш рабочий проект. Вот как выглядит его рабочая область — папка проекта:

Посмотри на дерево. index.html — витрина: агент будет трогать её чаще всего, когда задача про страницу. клиенты.csv — таблица с телефонами клиентов. фото/ — фотографии букетов. AGENTS.md — правила работы, им посвящена отдельная секция. проверка.py — программа, которую агент запускает, чтобы убедиться, что всё на месте.

В папке лежит всё, что нужно магазину, и агент работает только с этим.

А теперь присмотрись к именам файлов: у каждого есть расширение — часть имени после точки. Что оно значит?

Что внутри папки: файлы и расширения

Расширение подсказывает, что внутри файла:

.html — страница в интернете: то, что видят покупатели.

.csv — таблица с данными: например, клиенты с номерами телефонов.

.py — программа: например, проверка, что всё на месте.

.md — обычный текст: правила и заметки.

Папка — контейнер для файлов: например, папка фото/ с фотографиями букетов.

А ещё по расширению агент понимает, что с файлом можно делать: страницу — читать и править, таблицу — смотреть, программу — запускать, инструкции — читать. Как именно он это делает — разберём в следующей секции.

Запомни расширение .md: в таких файлах живут правила и заметки для агента — они будут встречаться дальше.

Важно: агент видит только свою папку

И вот что важно: агент работает только со своей папкой. Соседние папки на компьютере он не трогает — пока ему не дали отдельное разрешение. Об этом подробнее в разделе про права.

Для агента твоих личных документов за пределами папки проекта просто не существует: он о них не знает и не тронет. Это защита: агент не может сломать то, о чём не знает.

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

Как агент действует: вызов инструмента

Модель — это мозг: она думает и пишет текст, но сама по себе не трогает ничего. Чтобы что-то сделать, она вызывает инструмент — отдаёт команду, а выполняет её среда. Это как заказ в приложении доставки: ты нажимаешь кнопку «Заказать», а готовит и везёт уже сервис — не ты.

Инструмент — готовая кнопка с понятной надписью. У агента их несколько, и каждую он «нажимает», когда она нужна.

Помнишь начало документа: агент «читал файл index.html»? На самом деле он не читал сам — он вызвал инструмент «прочитать файл», среда выполнила, и текст файла вернулся к нему в память.

Вот как выглядит эта цепочка: модель вызывает инструмент → среда выполняет → результат возвращается модели. Теперь посмотрим, из чего состоит один инструмент.

Как выглядит инструмент

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

Смотри, как она читается. Имя — «Прочитать файл»: понятно, что делает, без подсказок. Описание — «Показывает содержимое файла»: что именно произойдёт. В строке вызова read_file("index.html") указано, какой файл открыть. В результатах написано, что получишь в ответ: текст файла. Знать эти четыре части — и инструментом можно пользоваться.

Четыре базовых инструмента

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

Проведи взглядом по карточкам. «Выполнить команду» запускает проверку — например, что все букеты на месте. «Найти текст» отыщет все места, где встречается старый номер. «Изменить файл» внесёт правку. Один агент — четыре кнопки, всё остальное — их комбинации.

Важно: результат занимает память

А теперь важная деталь. Всё, что вернул инструмент — текст файла, вывод проверки, — попадает в память модели и занимает там место. Помнишь context window из первого уровня: память не бесконечная и дорогая.

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

Проверим, как ты различаешь инструменты: угадай, какой вызовет агент в каждой ситуации.

Всё начинается с задачи

Помнишь цикл из первой секции: задача → план → действие → проверка? Он начинается с задачи. Без неё агент не знает, что делать — он просто ждёт текста.

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

Задача — это текст, который ты пишешь агенту. В первой секции мы уже так делали: «найди все места со старым номером телефона на странице и замени на новый». От того, как ты её напишешь, зависит, что агент сделает.

Что будет, если задача плохая

Представь, что ты написал просто: «Поправь страницу». Что агент сделает? Поменяет заголовок? Перекрасит кнопки? Удалит секцию? А может, просто спросит, что именно поправить.

Плохая задача — это когда нет ответов на три вопроса: что сделать (цель), что не трогать (границы), как проверить (готовность). Без ответов агент додумывает сам — и часто додумывает не то.

Формула хорошей задачи: шесть рамок

Хорошая задача отвечает на шесть вопросов. Разберём каждый на нашем примере: агенту нужно добавить на сайт секцию «О нас».

Цель — что сделать. Коротко и ясно: «Добавь на сайт секцию "О нас"».

Контекст — что важно знать. Чтобы не наделать ошибок: «Секция ставится внизу страницы, перед контактами. Текст секции уже написан в задаче».

Ограничения — что не трогать. «Не меняй оформление других секций. Не добавляй новые файлы».

Файлы — где смотреть. «Измени index.html».

Проверка — как убедиться. «Запусти проверку (проверка.py)».

Готово, когда — критерий. «Секция на странице, все проверки прошли. Перечисли, что изменено».

Хорошая задача целиком

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

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

Почему это важно

Рамки экономят время и тебе, и агенту: не нужно переделывать и уточнять. Агент не додумывает — он делает по тексту.

И ещё одно: разовая задача живёт в переписке. Но если правило должно действовать всегда — его записывают в файл AGENTS.md. Об этом — следующая секция.

Файл правил проекта

AGENTS.md — обычный текстовый файл с расширением .md. Он лежит в корне проекта — в дереве flower-shop он подписан «Правила работы в проекте».

Агент читает его в начале каждой задачи — до того, как что-то делать. В этом файле агент ищет ответы: что это за проект, как проверять работу, что нельзя менять и как оформлять результат.

Почему нельзя просто говорить правила словами в чате? Смотри на разницу:

Разница простая: слова в чате действуют на одну задачу, а файл — на все. Объяснил один раз — и агент следует правилам всегда.

Что будет, если правил нет

Представь: в проекте нет AGENTS.md, и агент получил задачу — обновить номер телефона на витрине.

Он поменяет номер и закончит на этом: никто не сказал, что после изменений нужно запускать проверку. Витрина сломается, а агент не заметит.

AGENTS.md — страховка от таких историй: в нём записано, как проверять работу и что нельзя трогать. Прочитал в начале задачи — и ошибка не случится.

Что обычно пишут в AGENTS.md

Обычно в файле правил собирают пять видов записей. Разберём каждый на примере flower-shop.

Что это за проект. Короткое описание, чтобы агент понимал, с чем работает: «Магазин цветов: страница-витрина, таблица клиентов, фотографии букетов».

Команды проверки. Как убедиться, что всё работает: «После каждого изменения запускай проверку (проверка.py)».

Что нельзя менять. Постоянные ограничения: «Не меняй таблицу клиентов без отдельной задачи».

Как оформлять результат. Чтобы ответы были единообразными и ты сразу видел, что агент делал: «Перечисляй изменённые файлы в итоге». В конце он напишет «изменены: index.html, проверка.py» — и всё ясно.

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

Пример: как выглядит настоящий AGENTS.md

Собери всё вместе — и получится файл правил, как в настоящем проекте:

Смотри, как он устроен. Раздел «Что это за проект» — чтобы агент понимал, с чем работает. «Проверка» — команда, которую он выполнит после каждой правки. «Что нельзя менять» — таблицу клиентов он не тронет, даже если задача позволит. «Как оформлять результат» — формат ответа. «Порядок работы» — последовательность шагов.

А теперь посмотрим, как агент пользуется файлом. Задача: «обнови номер на витрине». Агент сначала читает AGENTS.md, узнаёт правило про проверку, меняет номер — и запускает проверку, как написано. Файл прочитан один раз, а правило сработало.

Чего в правилах не должно быть

И самое важное, чего в AGENTS.md быть никогда не должно: пароли, ключи и секреты.

Почему? Файл правил могут увидеть другие люди и инструменты. Секрет, записанный в правила, — уже не секрет.

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

Как проверить, что правила работают

Проверить, что агент подхватил правила, просто: попроси его пересказать их.

Если пересказывает неверно — файл не читается: стоит проверить, что он лежит в корне проекта и называется именно AGENTS.md.

И ещё: правила — живой файл. Проект растёт, появляются новые папки и ограничения — дополняй AGENTS.md, когда что-то меняется.

А что агенту можно — решают права. Об этом следующая секция.

Проверим, как ты различаешь, что достойно места в правилах, а что нет:

Зачем нужны права

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

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

Правами управляют две ручки: песочница и подтверждения. Разберём каждую по очереди.

Первая ручка: песочница

Песочница — первая ручка. Почему такое имя? Ребёнок играет в песочнице: ему дали ограниченное место, и он не выходит за его границы. Так и агент: песочница — границы, за которые ему нельзя. В программе эта ручка называется sandbox.

Песочница решает, какие файлы и команды агенту доступны. Три режима:

read-only — только чтение. Агент может смотреть файлы, но не менять. Подходит, когда нужно разобраться: посмотреть таблицу клиентов, составить план — и ничего не трогать.

workspace-write — правки в папке проекта. Агент может менять файлы проекта: index.html, фото, таблицу клиентов — всё внутри его папки. Основной режим для работы.

danger-full-access — доступ к системе целиком. Агент может менять любые файлы компьютера и запускать любые команды. Это не «удобнее», а опаснее: одна ошибка — и пострадают файлы за пределами проекта.

Посмотри на лестницу прав — чем выше уровень, тем больше возможностей и тем больше ответственности:

Права должны соответствовать задаче. Хочешь, чтобы агент просто посмотрел таблицу клиентов? Хватит read-only. Нужно обновить номер на витрине? Нужен workspace-write. Полный доступ — только когда понимаешь, зачем он.

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

Вторая ручка: подтверждения

Вторая ручка — подтверждения (в программе — approval). Она решает, когда агент спрашивает разрешение перед действием. Три режима:

on-request — спрашивает в сомнительных случаях. Что-то необычное? Агент остановится и спросит: «можно?». Например: «Можно удалить этот файл?» — и дождётся твоего ответа. Режим по умолчанию — самый спокойный для старта.

never — не спрашивает никогда. Действует сам, без вопросов. Удобно, но только когда среда под контролем: своя папка, понятная задача.

untrusted — повышенная осторожность. Для чужого проекта: агент переспрашивает чаще, чем обычно, и лишний раз не рискует.

А что, если прав не хватает?

Представь: у агента права read-only, а задача — обновить номер телефона на витрине.

Он прочитает файл, поймёт, что нужно менять... и остановится: «У меня только чтение — я не могу изменить файл». Ничего не сломает, но и не сделает.

Это не ошибка агента, а неправильно выбранные права. Права подбирают под задачу: посмотреть — чтение, поправить — правки в проекте, полный доступ — только когда понимаешь, зачем.

Рекомендуемый старт

Для первого знакомства с агентом подходит одна комбинация: on-request + workspace-write. Разберём, что это значит: агент работает в своей папке (workspace-write) и уточняет в сомнительных случаях (on-request). Ты видишь каждое его сомнение и можешь остановить.

Почему начинают с этого? Сначала — безопасность, потом — автономность. Пока агент спрашивает, ты видишь, как он работает, и успеваешь вмешаться. Привык — можно ослаблять: снять подтверждения, расширить доступ. Но начинать лучше с этой комбинации.

И помни: права решают, что агент может делать, а секреты — что он знает. Пароли и ключи агенту не передают — мы говорили об этом в разделе про правила.

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

Память не резиновая

Мы настроили права — агент работает в своей папке и спрашивает, когда сомневается. Теперь посмотрим, как он запоминает важное.

Память агента — его контекст, context window из первого уровня. Представь доску, которая не резиновая: каждая новая запись занимает место, и что-то старое стирается.

Пока задача короткая — всё помещается. Но чем длиннее работа, тем сильнее стирается начало: агент перестаёт помнить, что решил час назад.

Поэтому важное записывают в документы, а не держат в переписке. Какие документы нужны проекту — разберём дальше.

Документы проекта — внешняя память

Файлы .md мы уже знаем: в AGENTS.md живут правила проекта — тот самый AGENTS.md из раздела про правила. Теперь видно его полную роль: он и карта проекта, и правила.

У проекта есть целый набор документов, и каждый отвечает на свой вопрос. Имена файлов на английском — так принято в проектах, но роль у каждого своя, и она написана по-русски рядом:

Ритм: когда что обновлять

Документы живут вместе с проектом — их не пишут один раз и не забывают. У каждого свой ритм:

CHANGELOG.md — после каждой задачи. Что-то сделал — записал в журнал изменений. Это обязательное правило.

AGENTS.md — когда меняется структура проекта. Добавил папку, поменял порядок работы — обнови карту.

DEVELOPMENT.md — когда меняются правила разработки. Ввели новое правило — запиши, чтобы агент знал.

README.md — когда меняется запуск. Поменялась команда старта — обнови быстрый старт.

Журнал задачи

А для длинной задачи вдобавок ведут журнал задачи — Documentation.md. Записал план, сделал первую часть — и дописал: что готово, что решили, что дальше.

Ты вернулся через день. Агент открывает журнал и продолжает ровно с того места, где остановился. Ничего не потеряно.

Вот как выглядит запись в журнале:

Три раздела — «Сделано», «Решения», «Следующий шаг» — и работа не теряется: после любой паузы агент знает, где он и что дальше.

Почему это важно

Запомни: контекст — рабочая память, документы — внешняя. Проект без документов — как переписка, которую удалили: никто не помнит, о чём шла речь.

А если порядок работы повторяется из задачи в задачу — его не запоминают в журнале, а записывают в скилл. Об этом следующая секция.

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