--output-format
cuando se combina con --print
. Estos formatos incluyen formatos estructurados para uso programático (json
, stream-json
) y un formato de texto simplificado para seguir el progreso de forma legible para humanos.
El
--output-format
predeterminado es stream-json
. Esta opción solo es válida al imprimir (--print
) o cuando se infiere el modo de impresión (stdout no TTY o stdin canalizado).Formato JSON
json
emite un único objeto JSON (seguido de un salto de línea) cuando la ejecución se completa correctamente. No se emiten deltas ni eventos de herramientas; el texto se agrega en el resultado final.
En caso de error, el proceso termina con un código distinto de cero y escribe un mensaje de error en stderr. No se emite ningún objeto JSON bien formado en casos de error.
Respuesta exitosa
Campo | Descripción |
---|---|
type | Siempre "result" para resultados del terminal |
subtype | Siempre "success" para completaciones correctas |
is_error | Siempre false para respuestas correctas |
duration_ms | Tiempo total de ejecución en milisegundos |
duration_api_ms | Tiempo de la solicitud a la API en milisegundos (actualmente igual a duration_ms ) |
result | Texto completo de la respuesta del asistente (concatenación de todos los deltas de texto) |
session_id | Identificador único de la sesión |
request_id | Identificador opcional de la solicitud (puede omitirse) |
Formato JSON de streaming
stream-json
emite JSON delimitado por saltos de línea (NDJSON). Cada línea contiene un único objeto JSON que representa un evento en tiempo real durante la ejecución.
El stream termina con un evento terminal result
en caso de éxito. En caso de fallo, el proceso finaliza con un código distinto de cero y el stream puede terminar antes sin un evento terminal; se escribe un mensaje de error en stderr.
Tipos de eventos
Inicialización del sistema
En el futuro, podrían añadirse a este evento campos como
tools
y mcp_servers
.Mensaje del usuario
Delta de texto del assistant
Concatena todos los valores de
message.content[].text
en orden para reconstruir la respuesta completa del asistente.Eventos de llamada a herramientas
Tipos de llamadas de herramienta
- Iniciada:
tool_call.readToolCall.args
contiene{ "path": "file.txt" }
- Completada:
tool_call.readToolCall.result.success
incluye metadatos y contenido del archivo
- Iniciada:
tool_call.writeToolCall.args
contiene{ "path": "file.txt", "fileText": "content...", "toolCallId": "id" }
- Completada:
tool_call.writeToolCall.result.success
incluye{ "path": "/absolute/path", "linesCreated": 19, "fileSize": 942 }
- Puede usar la estructura
tool_call.function
con{ "name": "tool_name", "arguments": "..." }
Resultado del terminal
Secuencia de ejemplo
Formato de texto
text
ofrece un flujo simplificado y legible para humanos de las acciones del agente. En lugar de eventos JSON detallados, entrega descripciones de texto concisas sobre lo que el agente está haciendo en tiempo real.
Este formato sirve para monitorear el progreso del agente sin la carga de parsear datos estructurados, lo que lo hace ideal para logging, depuración o un seguimiento simple del progreso.
Ejemplo de salida
Notas de implementación
- Cada evento se emite como una única línea terminada en
\n
- Los eventos
thinking
se suprimen en modo impresión y no aparecen en ninguno de los formatos de salida - Se pueden agregar campos con el tiempo de forma retrocompatible (los consumidores deben ignorar los campos desconocidos)
- El formato de flujo (stream) ofrece actualizaciones en tiempo real, mientras que el formato JSON espera a que finalice para mostrar los resultados
- Concatena todos los deltas del mensaje de
assistant
para reconstruir la respuesta completa - Los IDs de llamadas a herramientas pueden usarse para correlacionar los eventos de inicio y finalización
- Los IDs de sesión se mantienen consistentes durante una única ejecución del agente