Перейти к основному содержанию
CLI Cursor Agent поддерживает несколько форматов вывода через опцию --output-format в сочетании с --print. Доступны структурированные форматы для программного использования (json, stream-json) и упрощённый текстовый формат для наглядного отслеживания прогресса.
Значение --output-format по умолчанию — stream-json. Эта опция действует только при выводе на экран (--print) или когда режим вывода определяется автоматически (stdout без TTY либо stdin, переданный через конвейер).

Формат JSON

Формат json выводит один объект JSON (с последующим переводом строки) после успешного завершения выполнения. Дельты и события инструментов не выводятся; текст агрегируется в итоговый результат. В случае ошибки процесс завершается с ненулевым кодом и записывает сообщение об ошибке в stderr. В таких случаях корректный объект JSON не выводится.

Успешный ответ

При успешном выполнении CLI выводит объект JSON со следующей структурой:
{
  "type": "result",
  "subtype": "success",
  "is_error": false,
  "duration_ms": 1234,
  "duration_api_ms": 1234,
  "result": "<полный текст помощника>",
  "session_id": "<uuid>",
  "request_id": "<необязательный ID запроса>"
}
ПолеОписание
typeВсегда "result" для итоговых результатов
subtypeВсегда "success" для успешных завершений
is_errorВсегда false для успешных ответов
duration_msОбщее время выполнения в миллисекундах
duration_api_msВремя запроса к API в миллисекундах (сейчас равно duration_ms)
resultПолный текст ответа ассистента (конкатенация всех текстовых дельт)
session_idУникальный идентификатор сеанса
request_idНеобязательный идентификатор запроса (может отсутствовать)

Формат Stream JSON

Формат вывода stream-json эмитирует NDJSON (JSON, разделённый переводами строки). Каждая строка содержит один JSON-объект, представляющий событие в реальном времени во время выполнения. Поток завершается терминальным событием result при успешном завершении. При ошибке процесс завершается с ненулевым кодом, и поток может завершиться раньше без терминального события; сообщение об ошибке выводится в stderr.

Типы событий

Инициализация системы

Эмитируется один раз в начале каждой сессии:
{
  "type": "system",
  "subtype": "init",
  "apiKeySource": "env|flag|login",
  "cwd": "/absolute/path",
  "session_id": "<uuid>",
  "model": "<название модели для отображения>",
  "permissionMode": "default"
}
В будущем к этому событию могут быть добавлены поля tools и mcp_servers.

Сообщение пользователя

Содержит ввод пользователя:
{
  "type": "user",
  "message": {
    "role": "user",
    "content": [{ "type": "text", "text": "<prompt>" }]
  },
  "session_id": "<uuid>"
}

Дельта текста ассистента

Выдаётся несколько раз по мере генерации ответа ассистентом. Эти события содержат поэтапные текстовые фрагменты:
{
  "type": "assistant",
  "message": {
    "role": "assistant",
    "content": [{ "type": "text", "text": "<фрагмент дельты>" }]
  },
  "session_id": "<uuid>"
}
Объедини все значения message.content[].text по порядку, чтобы восстановить полный ответ ассистента.

События вызова инструментов

Вызовы инструментов отслеживаются событиями начала и завершения: Начало вызова инструмента:
{
  "type": "tool_call",
  "subtype": "started",
  "call_id": "<string id>",
  "tool_call": {
    "readToolCall": {
      "args": { "path": "file.txt" }
    }
  },
  "session_id": "<uuid>"
}
Вызов инструмента выполнен:
{
  "type": "tool_call",
  "subtype": "completed",
  "call_id": "<string id>",
  "tool_call": {
    "readToolCall": {
      "args": { "path": "file.txt" },
      "result": {
        "success": {
          "content": "содержимое файла...",
          "isEmpty": false,
          "exceededLimit": false
          "totalLines": 54,
          "totalChars": 1254
        }
      }
    }
  },
  "session_id": "<uuid>"
}

Типы вызовов инструментов

Инструмент чтения файла:
  • Начало: tool_call.readToolCall.args содержит { "path": "file.txt" }
  • Завершение: tool_call.readToolCall.result.success содержит метаданные файла и его содержимое
Инструмент записи файла:
  • Начало: tool_call.writeToolCall.args содержит { "path": "file.txt", "fileText": "content...", "toolCallId": "id" }
  • Завершение: tool_call.writeToolCall.result.success содержит { "path": "/absolute/path", "linesCreated": 19, "fileSize": 942 }
Другие инструменты:
  • Могут использовать структуру tool_call.function вида { "name": "tool_name", "arguments": "..." }

Результат терминала

Финальное событие, эмитируемое при успешном завершении:
{
  "type": "result",
  "subtype": "success",
  "duration_ms": 1234,
  "duration_api_ms": 1234,
  "is_error": false,
  "result": "<полный текст ассистента>",
  "session_id": "<uuid>",
  "request_id": "<необязательный ID запроса>"
}

Пример последовательности

Вот типичная последовательность NDJSON, показывающая обычный ход событий:
{"type":"system","subtype":"init","apiKeySource":"login","cwd":"/Users/user/project","session_id":"c6b62c6f-7ead-4fd6-9922-e952131177ff","model":"Claude 4 Sonnet","permissionMode":"default"}
{"type":"user","message":{"role":"user","content":[{"type":"text","text":"Прочитай README.md и сделай краткое резюме"}]},"session_id":"c6b62c6f-7ead-4fd6-9922-e952131177ff"}
{"type":"assistant","message":{"role":"assistant","content":[{"type":"text","text":"Я "}]},"session_id":"c6b62c6f-7ead-4fd6-9922-e952131177ff"}
{"type":"assistant","message":{"role":"assistant","content":[{"type":"text","text":"прочитаю файл README.md"}]},"session_id":"c6b62c6f-7ead-4fd6-9922-e952131177ff"}
{"type":"tool_call","subtype":"started","call_id":"toolu_vrtx_01NnjaR886UcE8whekg2MGJd","tool_call":{"readToolCall":{"args":{"path":"README.md"}}},"session_id":"c6b62c6f-7ead-4fd6-9922-e952131177ff"}
{"type":"tool_call","subtype":"completed","call_id":"toolu_vrtx_01NnjaR886UcE8whekg2MGJd","tool_call":{"readToolCall":{"args":{"path":"README.md"},"result":{"success":{"content":"# Project\n\nThis is a sample project...","isEmpty":false,"exceededLimit":false,"totalLines":54,"totalChars":1254}}}},"session_id":"c6b62c6f-7ead-4fd6-9922-e952131177ff"}
{"type":"assistant","message":{"role":"assistant","content":[{"type":"text","text":" и сделаю краткое резюме"}]},"session_id":"c6b62c6f-7ead-4fd6-9922-e952131177ff"}
{"type":"tool_call","subtype":"started","call_id":"toolu_vrtx_01Q3VHVnWFSKygaRPT7WDxrv","tool_call":{"writeToolCall":{"args":{"path":"summary.txt","fileText":"# README Summary\n\nThis project contains...","toolCallId":"toolu_vrtx_01Q3VHVnWFSKygaRPT7WDxrv"}}},"session_id":"c6b62c6f-7ead-4fd6-9922-e952131177ff"}
{"type":"tool_call","subtype":"completed","call_id":"toolu_vrtx_01Q3VHVnWFSKygaRPT7WDxrv","tool_call":{"writeToolCall":{"args":{"path":"summary.txt","fileText":"# README Summary\n\nThis project contains...","toolCallId":"toolu_vrtx_01Q3VHVnWFSKygaRPT7WDxrv"},"result":{"success":{"path":"/Users/user/project/summary.txt","linesCreated":19,"fileSize":942}}}},"session_id":"c6b62c6f-7ead-4fd6-9922-e952131177ff"}
{"type":"result","subtype":"success","duration_ms":5234,"duration_api_ms":5234,"is_error":false,"result":"Я прочитаю файл README.md и сделаю краткое резюме","session_id":"c6b62c6f-7ead-4fd6-9922-e952131177ff","request_id":"10e11780-df2f-45dc-a1ff-4540af32e9c0"}

Текстовый формат

Формат вывода text предоставляет упрощённый, удобочитаемый поток действий агента. Вместо подробных JSON-событий он выдаёт лаконичные текстовые описания того, что агент делает в реальном времени. Этот формат удобен для мониторинга прогресса агента без накладных расходов на парсинг структурированных данных, что делает его идеальным для логирования, отладки или простого трекинга прогресса.

Пример вывода

Прочтён файл
Изменён файл
Выполнена команда в терминале
Создан новый файл
Каждое действие выводится на новой строке по мере выполнения агентом, что даёт мгновенную обратную связь о его прогрессе в выполнении задачи.

Заметки по реализации

  • Каждое событие выводится одной строкой, оканчивающейся символом \n
  • События thinking скрываются в режиме печати и не появляются ни в одном формате вывода
  • Со временем могут добавляться новые поля с сохранением обратной совместимости (клиентам следует игнорировать неизвестные поля)
  • Потоковый формат предоставляет обновления в реальном времени, тогда как формат JSON дожидается завершения перед выводом результата
  • Конкатенируй все дельты сообщений assistant, чтобы восстановить полный ответ
  • Идентификаторы вызовов инструментов можно использовать для сопоставления событий начала и завершения
  • Идентификаторы сессии остаются неизменными на протяжении одного запуска агента
I