Агент отвечает «у меня нет доступа к файлам» — что сломалось

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

Первая мысль — модель слабая. Почти всегда она неверна. Разберём, что происходит на самом деле.

Где обрывается цепочка

Модель не читает файлы. Она просит агент это сделать: возвращает не текст, а структурированный вызов вида «выполни run_bash с аргументом cat app/models.py». Агент выполняет команду и отправляет результат обратно.

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

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

То есть жалоба модели правдива. Неправда только вывод, который из неё делают.

Как проверить за одну минуту

Отправьте запрос вручную и посмотрите, есть ли в ответе вызов инструмента.

curl -s https://api.zukko.pro/v1/chat/completions \
  -H "Authorization: Bearer fetch_ваш_ключ" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-5",
    "max_tokens": 200,
    "messages": [{"role": "user", "content": "Сколько файлов в папке? Посчитай через bash."}],
    "tools": [{
      "type": "function",
      "function": {
        "name": "run_bash",
        "description": "Выполнить команду в bash",
        "parameters": {
          "type": "object",
          "properties": {"command": {"type": "string"}},
          "required": ["command"]
        }
      }
    }]
  }'

В ответе должен быть блок tool_calls с именем run_bash и аргументом вроде {"command": "ls | wc -l"}. Если вместо него пришёл обычный текст — вызовы инструментов не работают, и дело не в вашем агенте.

Для Anthropic-формата то же самое проверяется на адресе https://api.zukko.pro/v1/messages: там вызов приходит блоком tool_use внутри content.

Частые причины

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

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

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

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

Про несколько вызовов подряд

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

Так бывает, когда посредник собирает потоковый ответ и неправильно разделяет вызовы: некоторые поставщики нумеруют их все нулём, и наивная сборка по номеру склеивает их в один блок. Снаружи это выглядит как «агент сходит с ума на второй команде».

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

Что делать

Если проверка показала, что вызовы не доходят, а настройки агента в порядке — пишите поставщику, это его сторона. У Zukko↗ перевод вызовов инструментов работает в обоих форматах и для всех текстовых моделей, включая тех поставщиков, которые сами говорят только по-OpenAI.