--print
와 함께 사용할 때 --output-format
옵션으로 여러 출력 형식을 제공해. 여기에는 프로그램에서 쓰기 위한 구조화된 형식(json
, stream-json
)과 사람이 읽기 쉬운 진행 상황 추적을 위한 단순화된 텍스트 형식이 포함돼.
기본
--output-format
은 stream-json
이야. 이 옵션은 출력할 때(--print
)나 출력 모드가 추론되는 경우(비 TTY stdout 또는 파이프된 stdin)에서만 유효해.JSON 형식
json
출력 형식은 실행이 성공적으로 완료되면 하나의 JSON 객체(뒤이어 개행 문자)를 내보내. 델타와 도구 이벤트는 출력되지 않고, 텍스트는 최종 결과로 집계돼.
실패하면 프로세스는 0이 아닌 종료 코드로 종료되고, 오류 메시지를 stderr에 기록해. 실패한 경우에는 제대로 형성된 JSON 객체가 출력되지 않아.
성공 응답
Field | Description |
---|---|
type | 터미널 결과의 경우 항상 "result" |
subtype | 성공적으로 완료된 경우 항상 "success" |
is_error | 성공적인 응답인 경우 항상 false |
duration_ms | 총 실행 시간(밀리초) |
duration_api_ms | API 요청 시간(밀리초) (현재 duration_ms 와 동일) |
result | 어시스턴트의 전체 응답 텍스트(모든 텍스트 델타를 연결한 값) |
session_id | 고유한 세션 식별자 |
request_id | 선택적 요청 식별자(생략될 수 있음) |
스트림 JSON 형식
stream-json
출력 형식은 줄바꿈으로 구분된 JSON(NDJSON)을 내보내. 각 줄엔 실행 중에 발생한 실시간 이벤트를 나타내는 단일 JSON 객체가 들어 있어.
스트림은 성공하면 마지막에 result
터미널 이벤트로 끝나. 실패하면 프로세스가 0이 아닌 코드로 종료되고, 터미널 이벤트 없이 스트림이 일찍 끝날 수도 있어. 오류 메시지는 stderr로 출력돼.
이벤트 유형
시스템 초기화
앞으로 이 이벤트에는
tools
, mcp_servers
같은 필드가 추가될 수도 있어.사용자 메시지
어시스턴트 텍스트 델타
전체 assistant 응답을 재구성하려면 순서대로 모든
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 }
포함
{ "name": "tool_name", "arguments": "..." }
와 함께tool_call.function
구조를 사용할 수 있음
터미널 결과
예시 시퀀스
텍스트 형식
text
출력 형식은 간결하고 사람이 읽기 쉬운 에이전트 동작 스트림을 제공해. 상세한 JSON 이벤트 대신, 에이전트가 실시간으로 무엇을 하는지에 대한 짧은 텍스트 설명을 출력해.
이 형식은 구조화된 데이터를 파싱하는 오버헤드 없이 에이전트 진행 상황을 모니터링하기에 유용해서, 로깅, 디버깅, 또는 간단한 진행 상황 추적에 이상적이야.
출력 예시
구현 노트
- 각 이벤트는
\n
으로 끝나는 한 줄로 출력됨 thinking
이벤트는 print 모드에서 숨겨지며 어떤 출력 형식에도 나타나지 않음- 필드는 시간이 지나며 역호환 방식으로 추가될 수 있음(클라이언트는 알 수 없는 필드를 무시해야 함)
- 스트림 형식은 실시간 업데이트를 제공하고, JSON 형식은 완료될 때까지 기다렸다가 결과를 출력함
- 전체 응답을 재구성하려면 모든
assistant
메시지 델타를 이어 붙이면 됨 - 툴 호출 ID로 시작/완료 이벤트를 매칭할 수 있음
- 세션 ID는 단일 에이전트 실행 내내 동일하게 유지됨