Codex SDK Event & Item

OpenAI Codex SDK(@openai/codex-sdk)에서 에이전트의 대화 처리를 구성하는 2가지 단위.

• Thread가 “대화 세션” 전체를 담당
• Turn이 “메시지 1개에 대한 처리 사이클”을 담당

Thread ── "대화 세션" (전체)
  └── Turn ── "처리 사이클" (메시지 1개마다)

OpenAI Codex SDK(@openai/codex-sdk)에서 에이전트의 스트리밍 응답을 표현하는 2계층 타입 시스템.

• Event가 “언제/어떤 상태 변화”
• Item이 “무엇에 대한 것인가”를 담당

ThreadEvent ── "상태 변화 알림" (언제)
  ├── item.started / item.updated / item.completed
  │     └── ThreadItem ── "콘텐츠 단위" (무엇을)
  └── thread.started / turn.started / turn.completed / turn.failed / error
        └── (ThreadItem 없음, 각자 고유 payload 또는 없음)

해당 개념이 필요한 이유

• Codex SDK는 에이전트 응답을 단일 문자열이 아닌 이벤트 스트림으로 전달함
• 텍스트, 추론, 도구 호출, 파일 변경 등 다양한 산출물이 섞여 나오므로, 구조적 타입 시스템이 필요
• Event/Item 2계층 구조를 이해해야 스트림을 올바르게 소비하고 필요한 데이터를 추출할 수 있음

AS-IS (구조 없이 단일 문자열 응답)

// 단순 API 호출 — 응답이 완성될 때까지 대기
const response = await api.chat("할일 등록해줘");
console.log(response.text); // "할일을 등록했습니다."
// → 중간 과정(추론, 도구 호출 등)이 보이지 않음

TO-BE (Event/Item 스트리밍)

// Codex SDK — 이벤트 스트림으로 중간 과정 실시간 수신
const { events } = await thread.runStreamed("할일 등록해줘");
for await (const event of events) {
  // event.type: "item.started" | "item.updated" | "item.completed" | ...
  // event.item.type: "reasoning" | "agent_message" | "mcp_tool_call" | ...
}
// → 추론, 도구 호출, 텍스트 생성 과정을 실시간으로 관찰 가능

Q) “1개의 Event에 N개의 Item이 들어갈 수 있나?”

• 아니다. 1 Event : 1 Item 관계다. item.started/item.updated/item.completed 의 payload는 item: ThreadItem (단수, 배열 아님)
• N개의 Item이 필요하면 N개의 Event가 따로 발생한다
• 하나의 Turn 안에서 여러 Event가 순차적으로 흐르는 구조

Q) “Thread, Turn은 Codex에 특화된 개념인가? Anthropic이나 Gemini와 공통인가?”

• Codex SDK 고유 명명이다. Anthropic Claude SDK는 query() + AsyncIterable<Message>, Gemini는 Chat + sendMessageStream()으로 동작한다
• “한 번의 사용자 입력에 대한 에이전트 처리 사이클”이라는 개념 자체는 공통이지만, 타입명과 API 구조가 다르다
• Codex에서의 정의:
  • Thread = 대화 세션 단위. codex.startThread()로 생성, thread_id로 식별
  • Turn = Thread 안에서 사용자 메시지 1개에 대한 에이전트의 전체 처리 사이클

ThreadEvent 전체 목록

Event type	Payload	설명
thread.started	thread_id: string	Thread 생성. 첫 이벤트로 1회만 발생
turn.started	(없음)	에이전트 처리 시작 (1 turn = 사용자 메시지 1개에 대한 전체 처리)
turn.completed	usage: Usage	에이전트 처리 완료. 토큰 사용량 포함
turn.failed	error: { message }	에이전트 처리 실패
item.started	item: ThreadItem	새 Item 생성 (보통 in_progress 상태)
item.updated	item: ThreadItem	Item 내용 업데이트 (중간 상태)
item.completed	item: ThreadItem	Item 완료 (최종 상태)
error	message: string	치명적 스트림 에러 (복구 불가)

// events.ts — Usage 타입
type Usage = {
  input_tokens: number;
  cached_input_tokens: number;
  output_tokens: number;
};

핵심: item.started / item.updated / item.completed 세 이벤트 모두 동일한 ThreadItem 구조체를 들고 온다. 차이는 Item 내부의 status 필드와 내용의 완성도.

ThreadItem 전체 목록

Item type	주요 필드	설명
agent_message	text: string	에이전트의 텍스트 응답
reasoning	text: string	내부 추론 과정 (thinking)
command_execution	command, aggregated_output, exit_code?, status	셸 명령 실행
file_change	changes: FileUpdateChange[], status	파일 변경 (add/delete/update)
mcp_tool_call	server, tool, arguments, result?, error?, status	MCP 도구 호출
web_search	query: string	웹 검색
todo_list	items: TodoItem[]	할 일 목록 관리
error	message: string	에러

// items.ts — ThreadItem 유니온
type ThreadItem =
  | AgentMessageItem    // { id, type: "agent_message", text }
  | ReasoningItem       // { id, type: "reasoning", text }
  | CommandExecutionItem // { id, type: "command_execution", command, aggregated_output, exit_code?, status }
  | FileChangeItem      // { id, type: "file_change", changes, status }
  | McpToolCallItem     // { id, type: "mcp_tool_call", server, tool, arguments, result?, error?, status }
  | WebSearchItem       // { id, type: "web_search", query }
  | TodoListItem        // { id, type: "todo_list", items }
  | ErrorItem;          // { id, type: "error", message }

라이프사이클

flowchart TD
    subgraph Thread
        TS[thread.started]

        subgraph Turn
            TUS[turn.started]
            subgraph Item
                IS[item.started]
                IU[item.updated]
                IC[item.completed]
                IS --> IU
                IU -->|"반복"| IU
                IU --> IC
                IS -->|"updated 없이"| IC
            end
            TUS --> IS
            IC -->|"다음 Item"| IS
            IC --> TUC[turn.completed]
            TUS -->|"실패"| TUF[turn.failed]
        end

        TS --> TUS
        TUC -->|"다음 Turn"| TUS
    end

    Thread -->|"치명적 에러 (스트림 종료)"| ERR[error]

    style Thread fill:#fff3e0,stroke:#f57c00,color:#333
    style Turn fill:#e3f2fd,stroke:#1976d2,color:#333
    style Item fill:#e8f5e9,stroke:#388e3c,color:#333

• thread.started: Thread 생성 시 1회만 발생
• turn: started 후 정상이면 completed, 실패하면 failed. 둘 다 없이 끝나는 경우는 error로 스트림 자체가 끊긴 경우
• item: started → updated(0~N회 반복) → completed가 정상 흐름. agent_message의 경우 텍스트가 토큰 단위로 누적되면서 updated가 여러 번 발생한다. turn.failed나 error 발생 시 item.completed 없이 끝날 수 있음
• turn.failed: 해당 Turn 즉시 종료. 이후 같은 Turn 내 이벤트 없음. Thread는 유지되므로 사용자가 새 메시지를 보내면 새 Turn 시작 가능
• error: Thread 레벨의 치명적 에러. turn/item 안에 속하지 않고 독립적으로 발생하며, 스트림이 종료됨

Item의 생명주기: started → updated → completed

하나의 Item은 3단계 이벤트를 거친다. text 필드는 delta가 아니라 매번 처음부터 끝까지의 전체 문자열이다:

sequenceDiagram
    autonumber
    participant SDK as Codex SDK
    participant App as Consumer

    SDK->>App: item.started { id: "item_01", text: "" }
    Note right of App: text = ""

    SDK->>App: item.updated { id: "item_01", text: "할일을" }
    Note right of App: text = "할일을"

    SDK->>App: item.updated { id: "item_01", text: "할일을 등록" }
    Note right of App: text = "할일을 등록"<br/>("할일을" 포함 + " 등록" 추가)

    SDK->>App: item.updated { id: "item_01", text: "할일을 등록하겠습니다." }
    Note right of App: text = "할일을 등록하겠습니다."<br/>("할일을 등록" 포함 + "하겠습니다." 추가)

    SDK->>App: item.completed { id: "item_01", text: "할일을 등록하겠습니다." }
    Note right of App: text = "할일을 등록하겠습니다."<br/>(마지막 updated와 동일한 전체 텍스트)

Q) “마지막 updated와 completed의 text는 동일한가? 모든 텍스트를 UI에 노출하면 중복되는 것 아닌가?”

• 맞다. 마지막 item.updated와 item.completed의 text는 동일하다. basic_streaming.ts 샘플이 item.completed에서만 text를 출력하고 item.updated는 무시하는 것이 이를 증명한다
• 따라서 UI 렌더링 시 append가 아닌 replace 해야 한다. 매번 전체 텍스트가 오기 때문에 append하면 중복이 생김
• 소비 전략 2가지:
  • Replace: 매번 전체 텍스트로 교체 (SDK 그대로 사용, 단순함)
  • Delta 계산: newText.slice(previousText.length)로 증분만 추출 (SSE 스트리밍처럼 delta 전송이 필요한 경우)

실전 이벤트 흐름 예시

사용자가 "할일 등록해줘: 오후 11시 미팅" 을 보낸 경우:

#	Event	Item type	핵심 데이터
1	thread.started	-	thread_id: "th_abc"
2	turn.started	-	(없음)
3	item.started	reasoning	text: ""
4	item.updated	reasoning	text: "사용자가 할일 등록을 원함"
5	item.completed	reasoning	text: "사용자가 할일 등록을 원함. createTodo 도구 사용"
6	item.started	agent_message	text: ""
7	item.updated	agent_message	text: "할일을 등록"
8	item.completed	agent_message	text: "할일을 등록하겠습니다."
9	item.started	mcp_tool_call	tool: "createTodo", status: "in_progress"
10	item.completed	mcp_tool_call	result: {...}, status: "completed"
11	item.started	agent_message	text: ""
12	item.updated	agent_message	text: "오후 11시 미팅 할일이"
13	item.completed	agent_message	text: "오후 11시 미팅 할일이 등록되었습니다."
14	turn.completed	-	usage: { input: 1234, cached: 500, output: 89 }

basic_streaming.ts 에서 읽는 SDK 사용 패턴

// 1. Thread 생성
const thread = codex.startThread();
 
// 2. 메시지 전송 + 스트리밍
const { events } = await thread.runStreamed(inputText);
 
// 3. for-await로 이벤트 소비 (AsyncIterable)
for await (const event of events) {
  switch (event.type) {
    case "item.completed":
      // Item 타입별 분기
      switch (event.item.type) {
        case "agent_message":
          console.log(event.item.text);  // 최종 전체 텍스트
          break;
        case "command_execution":
          console.log(event.item.command, event.item.aggregated_output);
          break;
      }
      break;
    case "item.updated":
    case "item.started":
      // 샘플에서는 todo_list만 처리
      if (event.item.type === "todo_list") { /* ... */ }
      break;
    case "turn.completed":
      console.log(event.usage);  // 토큰 사용량
      break;
  }
}

샘플의 패턴: item.completed에서 최종 결과를 읽고, item.updated는 todo_list처럼 중간 상태가 의미 있는 경우만 처리. 실시간 스트리밍 UI가 필요한 경우 item.updated의 agent_message도 처리해야 한다 (이전 text와 비교하여 delta 계산).

참고 문서

• Codex SDK events.ts
• Codex SDK items.ts
• Codex SDK basic_streaming.ts