CLI

Всё, что делает интерфейс, Voxagent отдаёт и через API — а API описывает себя достаточно подробно, чтобы универсальный клиент превратил его в командную строку. Обновлять ничего не нужно: список команд приезжает с сервера и следует за API сам.

Установка

Используем Restish. Он читает описание API при запуске и собирает команды из него.

brew install rest-sh/tap/restish

Другие системы — см. rest.sh. Страница написана под Restish 2.x, версия проверяется через restish --version.

Подключение

Одна команда, один раз:

restish api connect voxagent https://api.voxagent.ru \
  --spec https://api.voxagent.ru/swagger/cli/swagger.json

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

Discovered SpeakNode CLI
This API declares 2 auth scheme(s):
  OAuth2   oauth2 authorizationCode   … operations
Connected API "voxagent" (… operations discovered)

Идентификатор клиента, адрес входа и скоупы приезжают с сервера.

Переподключиться позже — например, когда у API появились новые команды — можно через --replace:

restish api connect voxagent https://api.voxagent.ru \
  --spec https://api.voxagent.ru/swagger/cli/swagger.json --replace

Как проходит вход

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

1. Вы выполняете команду — например restish voxagent get-users-me.
2. Открывается окно браузера с обычной страницей входа Voxagent.
3. Вы входите. Страница сообщает, что её можно закрыть.
4. Команда доигрывает и печатает результат.

Под капотом Restish слушает localhost:8484 и принимает туда возврат — поэтому настраивать и вставлять ничего не требуется.

Токен запоминается. Следующие команды ничего не спрашивают, а когда срок истекает — токен обновляется молча. Входить заново придётся только после выхода или после долгого перерыва.

Работа

Команды повторяют API: метод плюс путь.

restish voxagent get-users-me
restish voxagent get-agents
restish voxagent get-agents-id 3e4666bf-d5e5-4aa7-b8ce-cefe41c7568a

Аргументы пути идут по порядку, после команды. Посмотреть, что доступно:

restish voxagent --help              # все команды, по разделам
restish voxagent get-agents --help   # аргументы, форма запроса и ответа

Как читать вывод

По умолчанию приходит весь JSON целиком. Для списка это много, поэтому выберите нужные поля и попросите таблицу. Проекция пишется на jq:

restish voxagent get-agents \
  -f '.body.agents[] | {title, id, is_published}' -o table

┌──────────────────┬──────────────────────────────────────┬──────────────┐
│ title            │ id                                   │ is_published │
├──────────────────┼──────────────────────────────────────┼──────────────┤
│ Продажи          │ 3e4666bf-d5e5-4aa7-b8ce-cefe41c7568a │ true         │
│ Поддержка        │ 91ab2c7d-1f03-4e55-9c18-7a2be4d0c911 │ false        │
└──────────────────┴──────────────────────────────────────┴──────────────┘

Обратите внимание на форму ответа: список обычно лежит внутри поля, а не на верхнем уровне — body.agents, body.sessions, body.tools. Подсмотреть можно через restish voxagent <команда> --help.

restish voxagent get-sessions \
  -f '.body.sessions[] | {agent_title, status, duration_seconds}' -o table

Для одного поля jq не нужен:

restish voxagent get-agents -f 'body.agents[].title'

Форматы вывода: json (по умолчанию), yaml, table.

Передача данных

Тело запроса берётся из файла или со стандартного ввода:

restish voxagent post-analytics-conversations-search <request.json
echo '{"page": 1, "page_size": 20}' | restish voxagent post-analytics-conversations-search

--help у команды печатает готовый пример тела.

До чего дотянется, а до чего нет

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

Административные ручки исключены намеренно — их нет в списке команд вовсе.

Если что-то пошло не так