--output-format
in Kombination mit --print
mehrere Ausgabeformate. Dazu zählen strukturierte Formate für die programmgesteuerte Nutzung (json
, stream-json
) sowie ein vereinfachtes Textformat für eine gut lesbare Fortschrittsanzeige.
Das Standard-
--output-format
ist stream-json
. Diese Option ist nur gültig beim Ausgeben (--print
) oder wenn der Ausgabemodus inferred wird (nicht-TTY-stdout oder per Pipe übergebenes stdin).JSON-Format
json
-Ausgabeformat gibt bei erfolgreichem Abschluss genau ein JSON-Objekt aus (gefolgt von einem Zeilenumbruch). Deltas und Tool-Ereignisse werden nicht ausgegeben; Text wird zum Endergebnis zusammengefasst.
Im Fehlerfall beendet sich der Prozess mit einem ungleich null gesetzten Rückgabecode und schreibt eine Fehlermeldung nach stderr. In Fehlerfällen wird kein wohlgeformtes JSON-Objekt ausgegeben.
Erfolgs-Response
Feld | Beschreibung |
---|---|
type | Immer "result" für Terminal-Ergebnisse |
subtype | Immer "success" bei erfolgreichen Abschlüssen |
is_error | Immer false bei erfolgreichen Antworten |
duration_ms | Gesamtausführungszeit in Millisekunden |
duration_api_ms | API-Anfragezeit in Millisekunden (aktuell identisch mit duration_ms ) |
result | Vollständiger Antworttext des Assistenten (Verkettung aller Text-Deltas) |
session_id | Eindeutige Sitzungskennung |
request_id | Optionale Anfragekennung (kann entfallen) |
Stream-JSON-Format
stream-json
-Ausgabeformat gibt zeilenweise JSON (NDJSON) aus. Jede Zeile enthält ein einzelnes JSON-Objekt, das ein Echtzeit-Ereignis während der Ausführung darstellt.
Der Stream endet bei Erfolg mit einem abschließenden result
-Event. Bei einem Fehler beendet sich der Prozess mit einem von null verschiedenen Code, und der Stream kann ohne abschließendes Event vorzeitig enden; eine Fehlermeldung wird auf stderr geschrieben.
Ereignistypen
Systeminitialisierung
In Zukunft könnten Felder wie
tools
und mcp_servers
zu diesem Event hinzukommen.Benutzernachricht
Assistant-Text-Delta
Verkette alle
message.content[].text
-Werte in der richtigen Reihenfolge, um die vollständige Antwort des Assistenten zu rekonstruieren.Tool-Call-Ereignisse
Tool-Call-Typen
- Gestartet:
tool_call.readToolCall.args
enthält{ "path": "file.txt" }
- Abgeschlossen:
tool_call.readToolCall.result.success
enthält Dateimetadaten und Inhalt
- Gestartet:
tool_call.writeToolCall.args
enthält{ "path": "file.txt", "fileText": "content...", "toolCallId": "id" }
- Abgeschlossen:
tool_call.writeToolCall.result.success
enthält{ "path": "/absolute/path", "linesCreated": 19, "fileSize": 942 }
- Können die Struktur
tool_call.function
mit{ "name": "tool_name", "arguments": "..." }
verwenden
Terminal-Resultat
Beispielsequenz
Textformat
text
liefert einen vereinfachten, gut lesbaren Stream von Agent-Aktionen. Statt detaillierter JSON-Events gibt es prägnante Textbeschreibungen dessen aus, was der Agent in Echtzeit tut.
Dieses Format ist hilfreich, um den Fortschritt des Agents zu überwachen, ohne den Overhead beim Parsen strukturierter Daten – ideal für Logging, Debugging oder einfaches Fortschritts-Tracking.
Beispielausgabe
Hinweise zur Implementierung
- Jedes Event wird als einzelne Zeile mit
\n
beendet thinking
-Events werden im Print-Modus unterdrückt und erscheinen in keinem der Ausgabeformate- Feld-Erweiterungen können im Laufe der Zeit rückwärtskompatibel erfolgen (Consumers sollten unbekannte Felder ignorieren)
- Das Stream-Format liefert Echtzeit-Updates, während das JSON-Format bis zum Abschluss wartet und erst dann Ergebnisse ausgibt
- Alle
assistant
-Nachrichten-Deltas zusammenfügen, um die vollständige Antwort zu rekonstruieren - Tool-Call-IDs können verwendet werden, um Start- und Abschluss-Events zu korrelieren
- Session-IDs bleiben während einer einzelnen Agent-Ausführung konsistent