--output-format
в сочетании с --print
. Доступны структурированные форматы для программного использования (json
, stream-json
) и упрощённый текстовый формат для наглядного отслеживания прогресса.
Значение
--output-format
по умолчанию — stream-json
. Эта опция действует только при выводе на экран (--print
) или когда режим вывода определяется автоматически (stdout без TTY либо stdin, переданный через конвейер).Формат JSON
json
выводит один объект JSON (с последующим переводом строки) после успешного завершения выполнения. Дельты и события инструментов не выводятся; текст агрегируется в итоговый результат.
В случае ошибки процесс завершается с ненулевым кодом и записывает сообщение об ошибке в stderr. В таких случаях корректный объект JSON не выводится.
Успешный ответ
Поле | Описание |
---|---|
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.
Типы событий
Инициализация системы
В будущем к этому событию могут быть добавлены поля
tools
и mcp_servers
.Сообщение пользователя
Дельта текста ассистента
Объедини все значения
message.content[].text
по порядку, чтобы восстановить полный ответ ассистента.События вызова инструментов
Типы вызовов инструментов
- Начало:
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": "..." }
Результат терминала
Пример последовательности
Текстовый формат
text
предоставляет упрощённый, удобочитаемый поток действий агента. Вместо подробных JSON-событий он выдаёт лаконичные текстовые описания того, что агент делает в реальном времени.
Этот формат удобен для мониторинга прогресса агента без накладных расходов на парсинг структурированных данных, что делает его идеальным для логирования, отладки или простого трекинга прогресса.
Пример вывода
Заметки по реализации
- Каждое событие выводится одной строкой, оканчивающейся символом
\n
- События
thinking
скрываются в режиме печати и не появляются ни в одном формате вывода - Со временем могут добавляться новые поля с сохранением обратной совместимости (клиентам следует игнорировать неизвестные поля)
- Потоковый формат предоставляет обновления в реальном времени, тогда как формат JSON дожидается завершения перед выводом результата
- Конкатенируй все дельты сообщений
assistant
, чтобы восстановить полный ответ - Идентификаторы вызовов инструментов можно использовать для сопоставления событий начала и завершения
- Идентификаторы сессии остаются неизменными на протяжении одного запуска агента