Создание CLI для AI-агентов: принципы дизайна на примере Google's gws CLI

Почему важен дизайн CLI, ориентированный на агентов

Опыт разработчика-человека (DX) оптимизирован для открываемости и прощения ошибок, в то время как опыт агента требует предсказуемости и многоуровневой защиты. В статье утверждается, что адаптация CLI, ориентированных на людей, для агентов неэффективна, и демонстрирует это на примере интерфейса командной строки gws для Google Workspace, который с первого дня проектировался с ИИ-агентами в качестве основных потребителей.

Ключевые принципы дизайна

Необработанные JSON-полезные нагрузки вместо специализированных флагов: Люди предпочитают простые флаги, такие как --title "Мой документ", но агентам лучше работать с прямыми JSON-полезными нагрузками, которые соответствуют схемам API без потери при переводе.

Пример сравнения:

Ориентированный на человека (10 флагов, плоское пространство имён):
my-cli spreadsheet create --title "Бюджет Q1" --locale "en_US" --timezone "America/Denver" --sheet-title "Январь" --sheet-type GRID --frozen-rows 1 --frozen-cols 2 --row-count 100 --col-count 10 --hidden false

Ориентированный на агента (один JSON-флаг):
gws sheets spreadsheets create --json '
{
  "properties": {"title": "Бюджет Q1", "locale": "en_US", "timeZone": "America/Denver"},
  "sheets": [{"properties": {"title": "Январь", "sheetType": "GRID", "gridProperties": {"frozenRowCount": 1, "frozenColumnCount": 2, "rowCount": 100, "columnCount": 10}, "hidden": false}}]
}'

Интерфейс командной строки gws использует флаги --params и --json для всех входных данных, принимая полные полезные нагрузки API напрямую. Рекомендуемый подход — поддерживать оба пути в одном двоичном файле, а не поддерживать отдельные инструменты.

Дополнительные соображения

В статье изложены несколько других соображений по дизайну CLI, ориентированных на агентов:

• Интроспекция схемы: Самодокументируемые схемы, которые агенты могут интроспектировать во время выполнения
• Дисциплина контекстного окна: Управление выводом для соответствия пределам контекста агента
• Укрепление входных данных: Защита от галлюцинаций агента
• Навыки агента: Поставка возможностей, а не просто команд
• Поддержка нескольких поверхностей: Работа с MCP, расширениями и переменными окружения
• Защитные механизмы: Режимы пробного запуска и санация ответов

Интерфейсы командной строки становятся интерфейсом с наименьшим трением для взаимодействия ИИ-агентов с внешними системами, требуя детерминированного, машиночитаемого вывода вместо интерфейсов, ориентированных на человека.