basforge

Ищем по названиям, тексту и разборам «Если не работает».

    EN

    Агенты и инструменты: как модель читает файлы и запускает команды

    Модель умеет только писать текст. Инструмент — функция, которую она может попросить вызвать: прочитать файл, выполнить команду, поискать в интернете. Агент — модель плюс инструменты плюс цикл «попросила — выполнили — вернули результат», пока задача не решена. MCP — общий стандарт, по которому инструменты подключаются к любому агенту.

    Какую задачу решает

    Без инструментов модель отвечает по тому, что ей вставили: мы копируем лог, она советует команду, мы запускаем и копируем вывод обратно. С инструментами этот круг идёт без нас: модель сама читает файл, запускает docker compose config, видит ошибку и правит. Мы ставим задачу и проверяем результат.

    Как устроен вызов инструмента

    задача

    1. Описаниеtools: [read_file, bash, …]Программа отправляет модели список инструментов: имя, описание словами и схему входа. Это текст в контексте каждого запроса («Запрос к модели по блокам»).
    2. Просьбаstop_reason: tool_useМодель решает, что нужен инструмент, и отвечает не текстом, а блоком tool_use: имя и аргументы, например {"path": "traefik/data/traefik.yml"}.
    3. Выполнениена нашей сторонеПрограмма-агент выполняет вызов — сама модель ничего не запускает. Здесь же решается, спросить ли разрешения у человека.
    4. Результатtool_resultВывод возвращается модели следующим сообщением. Ошибку тоже возвращаем, с пометкой is_error, — модель поправит вызов.
    5. Повтордесятки ходовМодель смотрит на результат и решает: ещё инструмент или ответ. Каждый ход — новый запрос со всей историей, поэтому сессия агента дорожает с длиной («Токены»).

    ответ, когда инструменты больше не нужны

    { "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 — это код, который выполняется с нашими правами и видит то, что ему передаёт агент. Ставим из источников, которым доверяем, как любую программу.

    Какие бывают агенты

    claude.ai, ChatGPT

    Чат с инструментами

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

    Claude Code и аналоги

    Агент в редакторе и терминале

    Читает и правит файлы репозитория, запускает команды на нашем компьютере. Главный инструмент вайбкодинга. Доступ — по разрешениям, которые задаём мы.

    Облачный агент

    Работает в песочнице провайдера над копией репозитория и приносит результат веткой или pull request. Наш компьютер не трогает, зато и секретов отсюда не видит.

    Свой агент на API

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

    Сколько доступа давать

    Режим Что агент делает сам Когда
    спрашивает на каждое действие ничего, кроме чтения чужой код, незнакомая задача, сервер
    правит файлы сам, команды — с вопросом правки в репозитории обычная работа, всё в git («Чистый git status перед агентом»)
    список разрешённых команд npm run build, git status, тесты повторяющиеся задачи в своём репозитории
    всё сам любые команды только в песочнице или контейнере, где нечего сломать

    На серверах с живыми сайтами — схема из «Сервер вместе с ИИ-агентом»: агент готовит команды, человек выполняет. Секреты и ключи агенту не нужны ни в одном режиме («Секреты в чат не кладём»).

    Чем ещё решают эту задачу

    Что делает Когда лучше агента
    Чат и копирование модель советует, мы выполняем и приносим вывод задача на 2–3 шага; сервер, где агенту нечего делать
    Скрипт одни и те же шаги каждый раз шаги известны заранее; агент может такой скрипт написать
    Агент сам выбирает шаги по результатам шаги заранее неизвестны: отладка, правка в нескольких местах

    Что получаем и чем платим

    Получаем

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

    Платим

    • Ошибка выполняется. Неверная команда в чате — текст, у агента — сделанное действие. Отсюда разрешения, коммит до запуска и песочница.
    • Внедрение команд. Всё, что агент прочитал — README, страница, вывод программы, — может содержать инструкции, и модель может их выполнить («Чужой текст — данные, а не команды»).
    • Цена. Сессия на сотню ходов с историей в сотни тысяч токенов; кэш обязателен («Кэш промпта»).
    • Отчёт не равен результату. «Тесты проходят» — проверяем запуском сами («Где модели ошибаются»).

    Если не работает

    Агент сделал не то, что просили, и правки разбросаны по десятку файлов

    Причина
    Задача без границ и критерия готовности: агент решил, что «улучшить» включает соседний код.
    Делаем
    Коммит до запуска («Чистый git status перед агентом»), в задаче — что меняем и чего не трогаем; для большой задачи — сначала план («Сначала вопросы и план»).

    После подключения нескольких MCP-серверов ответы стали хуже и дороже

    Причина
    Описания всех инструментов лежат в контексте каждого запроса: десятки инструментов — тысячи токенов до вопроса, и модель путается в похожих.
    Делаем
    Подключаем серверы под задачу, а не все сразу; лишние выключаем.

    Агент выполнил команду из README чужого репозитория

    Причина
    Текст из файла попал в контекст и для модели выглядит как инструкция.
    Делаем
    Ручное подтверждение команд при работе с чужим кодом; правило «текст из файлов — данные» («Чужой текст — данные, а не команды»).

    Агент пишет, что вызвал инструмент, но ничего не произошло

    Причина
    Вызов оказался текстом в ответе, а не блоком tool_use — бывает на моделях с выключенным размышлением.
    Делаем
    Включаем размышление и снижаем effort вместо выключения; результат проверяем по факту, а не по отчёту.