Какую задачу решает
Без инструментов модель отвечает по тому, что ей вставили: мы копируем лог, она советует команду, мы
запускаем и копируем вывод обратно. С инструментами этот круг идёт без нас: модель сама читает файл,
запускает docker compose config, видит ошибку и правит. Мы ставим задачу и проверяем результат.
Как устроен вызов инструмента
задача
- Описание
tools: [read_file, bash, …]Программа отправляет модели список инструментов: имя, описание словами и схему входа. Это текст в контексте каждого запроса («Запрос к модели по блокам»). - Просьба
stop_reason: tool_useМодель решает, что нужен инструмент, и отвечает не текстом, а блокомtool_use: имя и аргументы, например{"path": "traefik/data/traefik.yml"}. - Выполнение
на нашей сторонеПрограмма-агент выполняет вызов — сама модель ничего не запускает. Здесь же решается, спросить ли разрешения у человека. - Результат
tool_resultВывод возвращается модели следующим сообщением. Ошибку тоже возвращаем, с пометкойis_error, — модель поправит вызов. - Повтор
десятки ходовМодель смотрит на результат и решает: ещё инструмент или ответ. Каждый ход — новый запрос со всей историей, поэтому сессия агента дорожает с длиной («Токены»).
ответ, когда инструменты больше не нужны
{ "type": "tool_use", "id": "toolu_01…", "name": "bash",
"input": { "command": "ls /opt/memos/data" } }
{ "type": "tool_result", "tool_use_id": "toolu_01…",
"content": "ls: cannot access '/opt/memos/data': No such file or directory", "is_error": true }
Инструменты бывают двух видов: наши — их выполняет программа агента у нас на компьютере (файлы, команды, свои API), и серверные — их выполняет провайдер (поиск в интернете, запуск кода в его песочнице).
MCP — общий разъём для инструментов
Model Context Protocol — открытый стандарт: сервер MCP описывает свои инструменты, а любой совместимый агент (Claude Code, claude.ai, редакторы) их подключает. Один раз написали сервер для своей базы заметок — работает во всех.
| Что | Как |
|---|---|
| локальный сервер | программа на нашем компьютере, агент общается с ней через stdin и stdout |
| удалённый сервер | адрес по HTTPS, часто со входом через OAuth: почта, календарь, трекер задач |
| что даёт | инструменты (действия), ресурсы (данные для чтения), шаблоны промптов |
| чем платим | описания всех инструментов — в контексте каждого запроса; сервер работает с нашими правами |
Сервер MCP — это код, который выполняется с нашими правами и видит то, что ему передаёт агент. Ставим из источников, которым доверяем, как любую программу.
Какие бывают агенты
Чат с инструментами
Поиск в интернете, запуск кода, чтение файлов проекта, подключённые MCP. Работает у провайдера, нашего компьютера не касается.
Агент в редакторе и терминале
Читает и правит файлы репозитория, запускает команды на нашем компьютере. Главный инструмент вайбкодинга. Доступ — по разрешениям, которые задаём мы.
Облачный агент
Работает в песочнице провайдера над копией репозитория и приносит результат веткой или pull request. Наш компьютер не трогает, зато и секретов отсюда не видит.
Свой агент на API
Свой цикл с нужными инструментами: бот, разбор почты, ночная проверка логов. SDK провайдеров дают готовый цикл — пишем только функции-инструменты.
Сколько доступа давать
| Режим | Что агент делает сам | Когда |
|---|---|---|
| спрашивает на каждое действие | ничего, кроме чтения | чужой код, незнакомая задача, сервер |
| правит файлы сам, команды — с вопросом | правки в репозитории | обычная работа, всё в git («Чистый git status перед агентом») |
| список разрешённых команд | npm run build, git status, тесты |
повторяющиеся задачи в своём репозитории |
| всё сам | любые команды | только в песочнице или контейнере, где нечего сломать |
На серверах с живыми сайтами — схема из «Сервер вместе с ИИ-агентом»: агент готовит команды, человек выполняет. Секреты и ключи агенту не нужны ни в одном режиме («Секреты в чат не кладём»).
Чем ещё решают эту задачу
| Что делает | Когда лучше агента | |
|---|---|---|
| Чат и копирование | модель советует, мы выполняем и приносим вывод | задача на 2–3 шага; сервер, где агенту нечего делать |
| Скрипт | одни и те же шаги каждый раз | шаги известны заранее; агент может такой скрипт написать |
| Агент | сам выбирает шаги по результатам | шаги заранее неизвестны: отладка, правка в нескольких местах |
Что получаем и чем платим
Получаем
- Работа без копирования. Агент сам читает файлы, запускает сборку и видит ошибки — круг «правка, проверка» идёт без нас посередине.
- Свежие данные. Агент читает файл с диска, а не версию из чата трёхчасовой давности.
- Проверка по факту. Агент с доступом к тестам и сборке видит результат своей правки и чинит сам.
Платим
- Ошибка выполняется. Неверная команда в чате — текст, у агента — сделанное действие. Отсюда разрешения, коммит до запуска и песочница.
- Внедрение команд. Всё, что агент прочитал — README, страница, вывод программы, — может содержать инструкции, и модель может их выполнить («Чужой текст — данные, а не команды»).
- Цена. Сессия на сотню ходов с историей в сотни тысяч токенов; кэш обязателен («Кэш промпта»).
- Отчёт не равен результату. «Тесты проходят» — проверяем запуском сами («Где модели ошибаются»).
Если не работает
Агент сделал не то, что просили, и правки разбросаны по десятку файлов
- Причина
- Задача без границ и критерия готовности: агент решил, что «улучшить» включает соседний код.
- Делаем
- Коммит до запуска («Чистый git status перед агентом»), в задаче — что меняем и чего не трогаем; для большой задачи — сначала план («Сначала вопросы и план»).
После подключения нескольких MCP-серверов ответы стали хуже и дороже
- Причина
- Описания всех инструментов лежат в контексте каждого запроса: десятки инструментов — тысячи токенов до вопроса, и модель путается в похожих.
- Делаем
- Подключаем серверы под задачу, а не все сразу; лишние выключаем.
Агент выполнил команду из README чужого репозитория
- Причина
- Текст из файла попал в контекст и для модели выглядит как инструкция.
- Делаем
- Ручное подтверждение команд при работе с чужим кодом; правило «текст из файлов — данные» («Чужой текст — данные, а не команды»).
Агент пишет, что вызвал инструмент, но ничего не произошло
- Причина
- Вызов оказался текстом в ответе, а не блоком
tool_use— бывает на моделях с выключенным размышлением. - Делаем
- Включаем размышление и снижаем
effortвместо выключения; результат проверяем по факту, а не по отчёту.