본문으로 건너뛰기

Class: StreamProcessor

정의 위치: packages/ai/src/activities/chat/stream/processor.ts:183

StreamProcessor - AI 응답 스트림을 처리하는 상태 머신

전체 UIMessage[] 대화를 관리하고 변경될 때 이벤트를 발생시킵니다. 어댑터 계약을 신뢰합니다. 어댑터는 AG-UI 이벤트를 올바른 순서로 정제하여 발생시킵니다.

상태 추적:

  • 전체 메시지 배열
  • 메시지별 스트림 상태(텍스트, 도구 호출, 사고 과정)
  • 여러 동시 메시지 스트림
  • TOOL_CALL_END 이벤트를 통한 도구 호출 완료

참고​

  • docs/chat-architecture.md#streamprocessor-internal-state — 상태 필드 참조
  • docs/chat-architecture.md#adapter-contract — 이 클래스가 어댑터에 기대하는 동작

생성자​

생성자​

new StreamProcessor(options?): StreamProcessor;

정의 위치: packages/ai/src/activities/chat/stream/processor.ts:221

매개변수​

options?​

StreamProcessorOptions = {}

반환값​

StreamProcessor

메서드​

addToolApprovalResponse()​

addToolApprovalResponse(approvalId, approved): void;

정의 위치: packages/ai/src/activities/chat/stream/processor.ts:385

승인 응답을 추가합니다(onApprovalRequest 처리 후 클라이언트가 호출).

매개변수​

approvalId​

string

approved​

boolean

반환값​

void

addToolResult()​

addToolResult(
   toolCallId, 
   output, 
   error?): void;

정의 위치: packages/ai/src/activities/chat/stream/processor.ts:341

도구 결과를 추가합니다(onToolCall 처리 후 클라이언트가 호출).

매개변수​

toolCallId​

string

output​

any

error?​

string

반환값​

void

addUserMessage()​

addUserMessage(
   content, 
   id?, 
   metadata?): UIMessage;

정의 위치: packages/ai/src/activities/chat/stream/processor.ts:269

대화에 사용자 메시지를 추가합니다. 단순 문자열 콘텐츠와 멀티모달 콘텐츠 배열을 모두 지원합니다.

매개변수​

content​

string | ContentPart[]

메시지 콘텐츠(문자열 또는 콘텐츠 부분 배열)

id?​

string

선택적 사용자 지정 메시지 ID(지정하지 않으면 생성됨)

metadata?​

Record<string, any>

선택적 AG-UI 메타데이터 모음

반환값​

UIMessage

생성된 UIMessage

예제​

// Simple text message
processor.addUserMessage('Hello!')

// Multimodal message with image
processor.addUserMessage([
  { type: 'text', content: 'What is in this image?' },
  { type: 'image', source: { type: 'url', value: 'https://example.com/photo.jpg' } }
])

// With custom ID
processor.addUserMessage('Hello!', 'custom-id-123')

areAllToolsComplete()​

areAllToolsComplete(): boolean;

정의 위치: packages/ai/src/activities/chat/stream/processor.ts:416

마지막 어시스턴트 메시지의 모든 도구 호출이 완료되었는지 확인합니다. 자동 계속 로직에 유용합니다.

반환값​

boolean

clearMessages()​

clearMessages(): void;

정의 위치: packages/ai/src/activities/chat/stream/processor.ts:488

모든 메시지를 지웁니다.

반환값​

void

finalizeStream()​

finalizeStream(): void;

정의 위치: packages/ai/src/activities/chat/stream/processor.ts:2388

스트림을 종료합니다 — 보류 중인 모든 작업을 완료합니다.

비동기 이터러블이 종료될 때(스트림이 닫힐 때) 호출됩니다. 최종 안전망으로 작동하여 남은 도구 호출을 완료하고, 아직 발생하지 않은 텍스트를 플러시하며 onStreamEnd를 발생시킵니다.

반환값​

void

참고​

docs/chat-architecture.md#single-shot-text-response — 종료 단계

getCurrentAssistantMessageId()​

getCurrentAssistantMessageId(): string | null;

정의 위치: packages/ai/src/activities/chat/stream/processor.ts:325

현재 어시스턴트 메시지 ID를 가져옵니다(생성된 경우). prepareAssistantMessage()가 호출되었지만 아직 콘텐츠가 도착하지 않았다면 null을 반환합니다.

반환값​

string | null

getMessages()​

getMessages(): UIMessage<unknown>[];

정의 위치: packages/ai/src/activities/chat/stream/processor.ts:408

현재 메시지를 가져옵니다.

반환값​

UIMessage&lt;unknown>[]

getRecording()​

getRecording(): ChunkRecording | null;

정의 위치: packages/ai/src/activities/chat/stream/processor.ts:2554

현재 녹화를 가져옵니다.

반환값​

ChunkRecording | null

getState()​

getState(): ProcessorState;

정의 위치: packages/ai/src/activities/chat/stream/processor.ts:2511

현재 프로세서 상태를 가져옵니다(모든 메시지에 걸쳐 집계됨).

반환값​

ProcessorState

prepareAssistantMessage()​

prepareAssistantMessage(): void;

정의 위치: packages/ai/src/activities/chat/stream/processor.ts:304

새 어시스턴트 메시지 스트림을 준비합니다. 메시지를 즉시 생성하지 않습니다. ensureAssistantMessage()를 통해 첫 번째 콘텐츠 포함 청크가 도착할 때 메시지를 지연 생성합니다. 자동 계속에서 콘텐츠가 생성되지 않을 때 빈 어시스턴트 메시지가 UI에서 깜박이는 현상을 방지합니다.

반환값​

void

process()​

process(stream): Promise<ProcessorResult>;

정의 위치: packages/ai/src/activities/chat/stream/processor.ts:506

스트림을 처리하고 핸들러를 통해 이벤트를 발생시킵니다.

매개변수​

stream​

AsyncIterable&lt;any>

반환값​

Promise&lt;ProcessorResult>

processChunk()​

processChunk(chunk): void;

정의 위치: packages/ai/src/activities/chat/stream/processor.ts:540

스트림의 단일 청크를 처리합니다.

모든 AG-UI 이벤트의 중앙 디스패치입니다. 각 이벤트 유형은 특정 핸들러에 매핑됩니다. switch에 나열되지 않은 이벤트는 의도적으로 무시합니다(STEP_STARTED, STATE_SNAPSHOT, STATE_DELTA).

매개변수​

chunk​

AGUIEvent

반환값​

void

참고​

docs/chat-architecture.md#adapter-contract — 예상 이벤트 유형 및 순서

removeMessagesAfter()​

removeMessagesAfter(index): void;

정의 위치: packages/ai/src/activities/chat/stream/processor.ts:456

특정 인덱스 이후의 메시지를 제거합니다(다시 로드/재시도용).

매개변수​

index​

number

반환값​

void

reset()​

reset(): void;

정의 위치: packages/ai/src/activities/chat/stream/processor.ts:2580

전체 재설정(메시지 포함)

반환값​

void

setMessages()​

setMessages(messages): void;

정의 위치: packages/ai/src/activities/chat/stream/processor.ts:240

메시지 배열을 설정합니다(예: 영속 상태에서 가져온 배열).

매개변수​

messages​

UIMessage&lt;unknown>[]

반환값​

void

startAssistantMessage()​

startAssistantMessage(messageId?): string;

정의 위치: packages/ai/src/activities/chat/stream/processor.ts:313

매개변수​

messageId?​

string

반환값​

string

지원 중단 예정​

대신 prepareAssistantMessage()를 사용합니다. 이 메서드는 어시스턴트 메시지를 즉시 생성하므로 빈 메시지가 깜박일 수 있습니다.

startRecording()​

startRecording(): void;

정의 위치: packages/ai/src/activities/chat/stream/processor.ts:2541

청크 녹화를 시작합니다.

반환값​

void

toModelMessages()​

toModelMessages(): ModelMessage<
  | string
  | ContentPart<unknown, unknown, unknown, unknown, unknown>[]
  | null>[];

정의 위치: packages/ai/src/activities/chat/stream/processor.ts:397

대화를 ModelMessages로 가져옵니다(LLM에 전송하기 위해).

반환값​

ModelMessage&lt; | string | ContentPart&lt;unknown, unknown, unknown, unknown, unknown>[] | null>[]

replay()​

static replay(recording, options?): Promise<ProcessorResult>;

정의 위치: packages/ai/src/activities/chat/stream/processor.ts:2599

프로세서를 통해 녹화를 재생합니다.

매개변수​

recording​

ChunkRecording

options?​

StreamProcessorOptions

반환값​

Promise&lt;ProcessorResult>