Урок 1.2. Chatbot, Agent и Coding Agent

Зачем это нужно

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

Теперь нужно сделать следующий шаг: понять разницу между LLM, chatbot, agent и coding agent.

Эти слова часто используют как синонимы, но для управляемой разработки это разные уровни системы. Chatbot обычно отвечает текстом. Agent может выбирать инструменты и действовать. Coding agent работает внутри репозитория: читает файлы, редактирует код, запускает команды, наблюдает ошибки и продолжает работу.

Если не различать эти уровни, легко ждать от chatbot поведения полноценного engineer assistant или, наоборот, дать coding agent слишком широкие права без контроля.

Главная цель урока - показать agent loop и объяснить, почему надежная AI-разработка строится как цикл наблюдения, действия и проверки, а не как один большой ответ модели.

Основная идея

LLM сама по себе генерирует текст. Agentic system появляется тогда, когда вокруг LLM есть runtime, который дает ей инструкции, инструменты, состояние задачи, правила, разрешения и способ наблюдать результаты действий.

Уровни можно представить так:

LLM
 ↓
Chat
 ↓
LLM + Tools
 ↓
Agent
 ↓
Coding Agent
 ↓
Agent Team

Каждый следующий уровень добавляет не "магическое понимание", а дополнительные возможности и ответственность:

chat добавляет диалог;
tools добавляют действия;
agent loop добавляет итеративное принятие решений;
coding agent добавляет работу с репозиторием;
agent team добавляет разделение ролей и координацию.

В этом курсе мы сначала строим надежный single-agent workflow. Multi-agent появится позже, когда уже есть specification, task graph, tests, Git safety и review.

Ключевые термины

Термин	Что означает
LLM	Модель, которая получает контекст и генерирует ответ.
Chatbot	Интерфейс диалога с моделью, обычно ориентированный на текстовые ответы.
Tool	Внешняя функция, которую агент может вызвать: прочитать файл, запустить тест, сделать запрос.
Agent	LLM + instructions + tools + loop принятия решений.
Coding Agent	Agent, работающий с кодовой базой, файловой системой, терминалом, diff и тестами.
Agent Loop	Цикл observe -> reason/plan -> select tool -> act -> observe result -> continue.
Runtime	Среда, которая управляет сообщениями, tools, permissions, состоянием и выполнением agent run.
Observable Result	Наблюдаемый результат действия: diff, command output, test result, file content, error log.
Handoff	Передача задачи, контекста или результата другому агенту или роли.

От LLM к Coding Agent

LLM

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

Пример:

User:
Объясни, зачем нужен rate limit для password reset.

LLM:
Rate limit снижает риск brute force и email abuse...

Это полезно для объяснения, но LLM сама не проверила проект, не изменила код и не запустила тесты.

Chatbot

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

Но chatbot все еще в основном отвечает текстом.

Типичный результат chatbot:

Вот пример endpoint на Express:
...

Это не равно изменению в вашем репозитории.

LLM + Tools

Когда модель получает tools, она может не только отвечать, но и инициировать действия. Например:

search_repository("reset token")
read_file("src/auth/service.ts")
run_tests("tests/auth")

Важно: модель не выполняет эти действия внутри себя. Она выбирает tool call, а runtime выполняет его и возвращает результат.

Agent

Agent - это система, которая может итеративно:

наблюдать состояние;
строить план;
выбирать действие;
выполнять действие через tool;
анализировать результат;
продолжать до достижения условия завершения.

Agent уже похож на исполнителя задачи, но не обязательно работает с кодом.

Он может быть research agent, support agent, data analysis agent или workflow agent.

Coding Agent

Coding agent специализируется на repository work. Он умеет:

читать файлы и искать по кодовой базе;
понимать существующие patterns;
редактировать файлы;
запускать tests, lint, typecheck, build;
читать ошибки компиляции и тестов;
анализировать diff;
соблюдать allowed scope;
возвращать evidence завершения.

Coding agent не просто "пишет код". Его ценность в том, что он может пройти маленький engineering loop.

Когда нужен agent, а когда достаточно automation

Не всякая задача с LLM должна становиться agent workflow. Иногда достаточно обычного script, rule engine, CI job или single-shot LLM call.

Agent полезен, когда workflow содержит:

несколько шагов с промежуточными наблюдениями;
необходимость выбирать tools по ситуации;
работу с неоднозначным natural language input;
чтение неструктурированных документов или кода;
exceptions и edge cases, которые трудно покрыть простыми rules;
потребность остановиться, задать вопрос или вернуть управление человеку.

Agent часто не нужен, когда:

поведение полностью детерминировано;
задача сводится к одной функции или одному shell command;
есть стабильный API и простая business rule;
все inputs структурированы;
действие рискованное, а качество нельзя проверить автоматически;
дешевле и безопаснее написать обычный script.

Примеры:

Задача	Лучше начать с
Форматировать Markdown перед commit	Hook/script
Проверить balanced code fences	Script/test
Найти архитектурный способ добавить feature	Coding agent в Plan Mode
Исправить bug по stack trace и existing tests	Coding agent
Разослать production emails	Deterministic workflow + approval gate
Обновить billing policy	Human decision + controlled tooling

Практический вопрос:

Нужна ли здесь автономная серия решений,
или достаточно deterministic automation?

Если достаточно automation, не усложняйте систему агентом. Если нужна серия решений с tool use и feedback, agent становится подходящей абстракцией.

Agent Loop

Базовый agent loop выглядит так:

Observe
 ↓
Reason / Plan
 ↓
Select Tool
 ↓
Act
 ↓
Observe Result
 ↓
Continue or Stop

В Mermaid:

flowchart TD A[Observe task and context] --> B[Reason or plan next step] B --> C{Need tool?} C -->|No| D[Respond or ask clarification] C -->|Yes| E[Select tool and arguments] E --> F[Runtime executes action] F --> G[Observe result] G --> H{Goal reached?} H -->|No| B H -->|Yes| I[Return result with evidence]

Этот loop важнее, чем один красивый ответ. Управляемость появляется не потому, что модель "стала умнее", а потому что каждое действие возвращает observable result.

Чем chatbot response отличается от agent action

Сценарий	Chatbot	Coding Agent
Нужно понять ошибку теста	Объясняет вероятную причину по вставленному логу	Запускает тест, читает stack trace, открывает связанный файл
Нужно добавить endpoint	Показывает пример кода	Находит существующий style, правит controller/service/tests
Нужно проверить результат	Говорит, какие команды запустить	Запускает команды и читает output
Нужно соблюдать architecture	Может перечислить правила	Проверяет diff на нарушение layers и imports
Нужно завершить task	Отвечает "готово"	Возвращает changed files, commands, exit codes, AC status

Chatbot хорош для объяснения, brainstorming и анализа предоставленного контекста. Coding agent нужен там, где задача требует действий в repository и внешней verification.

Что добавляет coding agent

Coding agent находится ближе к реальной разработке, потому что работает с артефактами проекта.

Типовой набор возможностей:

Repository search
    +
File read/write
    +
Terminal commands
    +
Test output
    +
Diff review
    +
Git workflow

Но каждая возможность добавляет риск.

Возможность	Польза	Риск
Читать файлы	Агент видит реальную реализацию	Может выбрать нерелевантный файл
Редактировать код	Агент выполняет задачу	Может изменить лишний scope
Запускать команды	Есть external feedback	Может неверно интерпретировать output
Использовать Git	Видно diff и checkpoints	Может смешать unrelated changes
Работать долго	Может завершить сложную задачу	Может уйти в drift или loop

Поэтому coding agent требует не меньше дисциплины, чем human developer. Просто дисциплина выражается в specification, allowed scope, tests, review и permissions.

Observable result

Каждый шаг coding agent должен по возможности приводить к наблюдаемому результату.

Плохо:

Я проверил код, выглядит нормально.

Лучше:

Прочитал:
- src/auth/reset-token.service.ts
- tests/auth/reset-token.test.ts

Нашел:
- токен помечается consumed только после успешной смены пароля

Следующий шаг:
- добавить regression test для повторного использования token

Еще лучше:

Изменил:
- tests/auth/reset-token.test.ts

Проверка:
- pytest tests/auth/reset-token.test.ts -q
- exit code 0
- 4 passed

Observable result снижает неопределенность. Он позволяет человеку, reviewer agent или CI понять, что реально произошло.

Пример agent transcript

Ниже не реальный лог конкретного инструмента, а учебный transcript. Его задача - показать фазы agent loop.

User:
Добавь проверку, что consumed reset token нельзя использовать повторно.

[OBSERVE]
Agent reads task and current spec.

[PLAN]
Agent:
1. Найду существующие тесты reset token.
2. Добавлю failing regression test.
3. Запущу тест и проверю, что он падает.
4. Исправлю service logic.
5. Запущу targeted tests.

[SELECT TOOL]
search_repository("reset token consumed")

[OBSERVE RESULT]
Found:
- src/auth/reset_token_service.py
- tests/auth/test_reset_token.py

[ACT]
edit tests/auth/test_reset_token.py

[SELECT TOOL]
run_tests("tests/auth/test_reset_token.py -q")

[OBSERVE RESULT]
1 failed, 8 passed.
Failure: consumed token accepted.

[ACT]
edit src/auth/reset_token_service.py

[SELECT TOOL]
run_tests("tests/auth/test_reset_token.py -q")

[OBSERVE RESULT]
9 passed.

[STOP]
Agent returns:
- changed files
- test command
- exit code
- acceptance criterion status

Что важно в этом transcript:

агент не начал с реализации;
сначала был найден существующий код;
regression test появился до fix;
результат проверен командой;
завершение связано с evidence.

Когда агент должен остановиться

Agent loop не должен продолжаться бесконечно. Надежный coding agent останавливается не только когда "готово", но и когда возник риск неправильного решения.

Остановиться и запросить уточнение нужно, если:

specification противоречива;
невозможно определить expected behavior;
нужный файл или API contract не найден;
verification command падает из-за старой unrelated проблемы;
task требует изменения forbidden scope;
действие высокорисковое: удаление данных, deploy, secrets, permissions, billing.

Такой stop не является слабостью агента. Это часть управляемого процесса.

Мини-практика: разметить agent run

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

[OBSERVE]
[PLAN]
[SELECT TOOL]
[ACT]
[OBSERVE RESULT]
[STOP]

Затем ответьте:

Был ли у агента явный plan перед изменениями?
Какие tools он использовал?
Какие действия дали observable result?
Где агент мог уйти в drift?
Есть ли evidence завершения задачи?

Итоговый артефакт практики:

labs/01-agent-loop/transcript-analysis.md

Типичные ошибки

Ошибка 1. Называть любой chat agent'ом

Если система только отвечает текстом и не может действовать через tools, это chatbot, а не agent в инженерном смысле курса.

Ошибка 2. Считать tool call доказательством

Tool call сам по себе не доказательство. Важен результат tool call и то, как агент его использовал.

Ошибка 3. Давать coding agent права без allowed scope

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

Ошибка 4. Принимать длинный план за выполненную работу

План полезен, но он не меняет код и не запускает тесты. Завершение требует observable result.

Ошибка 5. Продолжать loop после неясного требования

Если expected behavior не определен, агент должен перейти в clarification, а не угадывать.

Критерии готовности

После урока студент должен уметь:

объяснить разницу между LLM, chatbot, agent и coding agent;
описать agent loop: observe, reason/plan, select tool, act, observe result;
привести пример observable result для coding task;
отличить plan от выполненного действия;
разметить простой transcript agent run по фазам loop;
объяснить, почему coding agent должен работать итеративно.

Краткое резюме

Chatbot отвечает. Agent действует через tools. Coding agent действует внутри репозитория: читает файлы, изменяет код, запускает проверки и анализирует результаты.

Базовая единица agentic development - не "ответ", а loop:

Observe -> Plan -> Act -> Observe Result -> Continue or Stop

Чем лучше организован этот loop, тем проще контролировать качество результата. Но если дать агенту слишком большую задачу без specification, allowed scope и verification, даже хороший loop начнет терять фокус.

Вопросы для самопроверки

Чем chatbot отличается от coding agent?
Почему tool call сам по себе не является evidence?
Что такое observable result в coding task?
На каком этапе agent loop нужно запускать tests?
Когда агент должен остановиться и запросить уточнение?

Что дальше

В следующем уроке мы разберем, почему one-shot development плохо масштабируется. Теперь, когда понятно, что coding agent работает итеративно, станет видно, почему задача "сделай всю фичу целиком" ломает управляемость loop и приводит к drift.