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

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

Рядом живут более приземлённые вещи: настройка интеграции с терминалом, режим оболочки и конфигурация для облачного провайдера моделей. Их объединяет то, что все они про окружение, а не про агента. И именно окружение чаще всего оказывается причиной непонятных сбоев - особенно в корпоративной сети, где между процессом и сервисом стоит чужая инфраструктура, о существовании которой разработчик обычно узнаёт из сообщения об ошибке.

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

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