인터페이스: ChatMiddleware<TContext, TInterruptDefinitions>

정의 위치: packages/ai/src/activities/chat/middleware/types.ts:565

Chat 미들웨어 인터페이스입니다.

모든 훅은 선택 사항입니다. 미들웨어는 배열 순서대로 구성됩니다.

onConfig: 설정이 미들웨어를 순서대로 통과합니다(첫 번째 변환이 이후 미들웨어에 영향을 줍니다).
onChunk: 각 출력 청크가 순서대로 다음 미들웨어에 전달됩니다.

예제

로깅 미들웨어

const loggingMiddleware: ChatMiddleware = {
  name: 'logging',
  onStart(ctx) { console.log('Chat started', ctx.requestId) },
  onChunk(ctx, chunk) { console.log('Chunk:', chunk.type) },
  onFinish(ctx, info) { console.log('Done:', info.duration, 'ms') },
}

삭제 미들웨어

const redactionMiddleware: ChatMiddleware = {
  name: 'redaction',
  onChunk(ctx, chunk) {
    if (chunk.type === 'TEXT_MESSAGE_CONTENT') {
      return { ...chunk, delta: redact(chunk.delta) }
    }
  },
}

확장 대상

DefinedChatMiddleware

타입 매개변수

TContext

TContext = unknown

TInterruptDefinitions

TInterruptDefinitions extends AnyInterruptDefinition = never

속성

name?

optional name?: string;

정의 위치: packages/ai/src/activities/chat/middleware/types.ts:570

디버깅 및 식별을 위한 선택적 이름입니다.

onAbort?

optional onAbort?: (ctx, info) => void | Promise<void>;

정의 위치: packages/ai/src/activities/chat/middleware/types.ts:758

채팅 실행이 중단될 때 호출됩니다. 실행마다 onFinish/onAbort/onError 중 정확히 하나가 호출됩니다.

매개변수

ctx

ChatMiddlewareContext<TContext>

info

AbortInfo

반환값

void | Promise<void>

onAfterToolCall?

optional onAfterToolCall?: (ctx, info) => void | Promise<void>;

정의 위치: packages/ai/src/activities/chat/middleware/types.ts:722

도구 실행이 완료된 후(성공 또는 실패) 호출됩니다.

매개변수

ctx

ChatMiddlewareContext<TContext>

info

AfterToolCallInfo

반환값

void | Promise<void>

onBeforeToolCall?

optional onBeforeToolCall?: (ctx, hookCtx) => 
  | BeforeToolCallDecision
| Promise<BeforeToolCallDecision>;

정의 위치: packages/ai/src/activities/chat/middleware/types.ts:714

도구가 실행되기 전에 호출됩니다. 관찰, 인수 변환, 실행 건너뛰기 또는 실행 중단을 수행할 수 있습니다.

매개변수

onChunk?

optional onChunk?: (ctx, chunk) => 
  | void
  | AGUIEvent
  | AGUIEvent[]
  | Promise<void | AGUIEvent | AGUIEvent[] | null>
  | null;

정의 위치: packages/ai/src/activities/chat/middleware/types.ts:700

chat()이 생성하는 모든 청크에 대해 호출됩니다. 청크를 관찰, 변환, 확장 또는 삭제할 수 있습니다.

매개변수

ctx

ChatMiddlewareContext<TContext>

chunk

AGUIEvent

반환값

void (통과), chunk (대체), chunk[] (확장), null (삭제)

onConfig?

optional onConfig?: (ctx, config) => 
  | void
  | Partial<ChatMiddlewareConfig>
  | Promise<
  | void
  | Partial<ChatMiddlewareConfig>
  | null>
  | null;

정의 위치: packages/ai/src/activities/chat/middleware/types.ts:628

채팅 설정을 관찰하거나 변환하기 위해 호출됩니다. 초기화 시점과 각 에이전트 반복의 시작 시점에 호출됩니다.

현재 설정과 병합할 부분 설정을 반환하거나, 통과시키려면 void를 반환합니다. 반환한 필드만 덮어쓰며 나머지는 모두 유지됩니다.

매개변수

ctx

ChatMiddlewareContext<TContext>

config

ChatMiddlewareConfig

반환값

onError?

optional onError?: (ctx, info) => void | Promise<void>;

정의 위치: packages/ai/src/activities/chat/middleware/types.ts:767

채팅 실행에서 처리되지 않은 오류가 발생할 때 호출됩니다. 실행마다 onFinish/onAbort/onError 중 정확히 하나가 호출됩니다.

매개변수

ctx

ChatMiddlewareContext<TContext>

info

ErrorInfo

반환값

void | Promise<void>

onFinish?

optional onFinish?: (ctx, info) => void | Promise<void>;

정의 위치: packages/ai/src/activities/chat/middleware/types.ts:749

채팅 실행이 정상적으로 완료될 때 호출됩니다. 실행마다 onFinish/onAbort/onError 중 정확히 하나가 호출됩니다.

매개변수

ctx

ChatMiddlewareContext<TContext>

info

FinishInfo

반환값

void | Promise<void>

onInterruptBoundary?

optional onInterruptBoundary?: (ctx) => 
  | InterruptBoundaryResult<TInterruptDefinitions>
| Promise<InterruptBoundaryResult<TInterruptDefinitions>>;

정의 위치: packages/ai/src/activities/chat/middleware/types.ts:576

수명 주기 경계에서 호출됩니다. 실행을 일시 중지하려면 인터럽트 요청을 반환합니다. 동일한 경계의 모든 미들웨어 요청은 하나의 배치를 구성합니다.

매개변수

ctx

ChatMiddlewareContext<TContext> & object

반환값

| InterruptBoundaryResult<TInterruptDefinitions> | Promise<InterruptBoundaryResult<TInterruptDefinitions>>

onInterruptResolution?

optional onInterruptResolution?: (ctx, resolutions) => 
  | InterruptResolutionResult
| Promise<InterruptResolutionResult>;

정의 위치: packages/ai/src/activities/chat/middleware/types.ts:586

클라이언트가 등록된 인터럽트에 응답한 후 계속 실행할 때 호출됩니다. 대기 중인 도구의 계속, 취소 또는 중지를 결정하려면 toolResume을 반환합니다.

매개변수

ctx

ChatMiddlewareContext<TContext>

resolutions

InterruptResolutionCollection<TInterruptDefinitions>

반환값

| InterruptResolutionResult | Promise<InterruptResolutionResult>

onIteration?

optional onIteration?: (ctx, info) => void | Promise<void>;

정의 위치: packages/ai/src/activities/chat/middleware/types.ts:670

새 assistant 메시지 ID가 생성된 후 각 에이전트 루프 반복의 시작 시점에 호출됩니다. 반복 경계를 관찰할 때 사용합니다.

매개변수

ctx

ChatMiddlewareContext<TContext>

info

IterationInfo

반환값

void | Promise<void>

onShouldContinue?

optional onShouldContinue?: (ctx, state) => boolean | void | Promise<boolean | void>;

정의 위치: packages/ai/src/activities/chat/middleware/types.ts:689

엔진이 다른 에이전트 루프 반복을 시작할지 결정할 때 호출됩니다(도구 단계 후 또는 모델 턴 사이).

추가 반복을 중지하려면 false를 반환합니다. 계속하려면 true, void 또는 undefined를 반환합니다. 미들웨어 간 AND 의미 및 agentLoopStrategy와 결합되므로 어떤 false든 루프를 중지합니다.

실행을 중단하지 않습니다. 스트림은 현재 메시지와 함께 정상적으로 완료됩니다. 강제 중단이 필요할 때만 ctx.abort()를 사용합니다.

전략에 전달되는 동일한 AgentLoopState를 받습니다 (iterationCount, toolCallCount, lastTurnToolCallCount 등).

매개변수

ctx

ChatMiddlewareContext<TContext>

state

AgentLoopState

반환값

boolean | void | Promise<boolean | void>

onStart?

optional onStart?: (ctx) => void | Promise<void>;

정의 위치: packages/ai/src/activities/chat/middleware/types.ts:664

채팅 실행이 시작될 때(초기 onConfig 후) 호출됩니다.

매개변수

ctx

ChatMiddlewareContext<TContext>

반환값

void | Promise<void>

onStructuredOutputConfig?

optional onStructuredOutputConfig?: (ctx, config) => 
  | void
  | Partial<StructuredOutputMiddlewareConfig>
  | Promise<
  | void
  | Partial<StructuredOutputMiddlewareConfig>
  | null>
  | null;

정의 위치: packages/ai/src/activities/chat/middleware/types.ts:652

최종 구조화된 출력 호출의 시작 시점에 호출됩니다(채팅이 outputSchema와 함께 호출된 경우). onConfig와 같이 미들웨어를 순서대로 통과하며 provider로 전송되는 JSON Schema에 접근할 수 있습니다.

현재 설정에 얕게 병합할 부분 설정을 반환하거나, 통과시키려면 void를 반환합니다.

구조화된 출력 경계에서 onConfig보다 먼저 실행됩니다. onConfig도 동일한 경계에서 ctx.phase === 'structuredOutput'인 상태로 다시 실행되며 outputSchema를 제외한 onStructuredOutputConfig 이후 설정 뷰를 받습니다. 모든 어댑터 호출에 적용되는 범용 변환에는 onConfig를 사용하고, outputSchema를 변환하거나 구조화된 출력에 특화된 동작을 적용해야 할 때는 이 훅을 사용합니다.

매개변수

ctx

ChatMiddlewareContext<TContext>

config

StructuredOutputMiddlewareConfig

반환값

onToolPhaseComplete?

optional onToolPhaseComplete?: (ctx, info) => void | Promise<void>;

정의 위치: packages/ai/src/activities/chat/middleware/types.ts:731

반복에서 모든 도구 호출이 처리된 후 호출됩니다. 도구 실행 결과, 승인 및 클라이언트 도구에 대한 집계 데이터를 제공합니다.

매개변수

ctx

ChatMiddlewareContext<TContext>

info

ToolPhaseCompleteInfo

반환값

void | Promise<void>

onUsage?

optional onUsage?: (ctx, usage) => void | Promise<void>;

정의 위치: packages/ai/src/activities/chat/middleware/types.ts:740

RUN_FINISHED 청크에서 사용량 데이터를 사용할 수 있을 때 호출됩니다. 사용량을 보고하는 모델 반복마다 한 번 호출됩니다.

매개변수

ctx

ChatMiddlewareContext<TContext>

usage

UsageInfo

반환값

void | Promise<void>

optionalRequires?

optional optionalRequires?: readonly CapabilityHandle[];

정의 위치: packages/ai/src/activities/chat/middleware/types.ts:611

이 미들웨어가 존재할 경우 사용하지만 필수로 요구하지는 않는 기능입니다. 게이팅하지 않으므로 검증 오류를 일으키지 않습니다. 다음으로 읽습니다. getX(ctx, { optional: true }).

provides?

optional provides?: readonly CapabilityHandle[];

정의 위치: packages/ai/src/activities/chat/middleware/types.ts:604

이 미들웨어가 제공하는 기능입니다. 선언된 각 기능은 setup 내부에서 해당 provide 접근자를 통해 반드시 제공되어야 하며, 그렇지 않으면 설정 단계 후 chat()이 오류를 발생시킵니다.

requires?

optional requires?: readonly CapabilityHandle[];

정의 위치: packages/ai/src/activities/chat/middleware/types.ts:597

이 미들웨어가 요구하는 기능입니다. chat()은 일부 미들웨어(또는 어댑터)가 각 기능을 제공하는지 검증합니다. 충족되지 않은 요구 사항은 컴파일 시간 오류 (배열 적용 범위 / 빌더)이자 어댑터 실행 전 런타임 오류입니다.

sandbox?

optional sandbox?: ChatSandboxHooks<TContext>;

정의 위치: packages/ai/src/activities/chat/middleware/types.ts:776

샌드박스 파일 이벤트 훅입니다. withSandbox가 제공한 샌드박스가 실행 중 활성화되어 파일이 생성·변경·삭제될 때 실행됩니다. 서버 측에서 동작합니다.

setup?

optional setup?: (ctx) => void | Promise<void>;

정의 위치: packages/ai/src/activities/chat/middleware/types.ts:619

프로비저닝 훅입니다. 배열 순서에 따른 모든 미들웨어에서 onConfig(init)보다 먼저 실행됩니다. provide 접근자를 호출하여 이후 미들웨어(onConfig 이후)가 기능을 사용할 수 있도록 할 때 사용합니다. 안정적인 컨텍스트를 받으며 변경 가능한 설정은 받지 않습니다.

매개변수

ctx

ChatMiddlewareContext<TContext>

반환값

void | Promise<void>

예제​

확장 대상​

타입 매개변수​

TContext​

TInterruptDefinitions​

속성​

name?​

onAbort?​

매개변수​

ctx​

info​

반환값​

onAfterToolCall?​

매개변수​

ctx​

info​

반환값​

onBeforeToolCall?​

매개변수​

ctx​

hookCtx​

반환값​

onChunk?​

매개변수​

ctx​

chunk​

반환값​

onConfig?​

매개변수​

ctx​

config​

반환값​

onError?​

매개변수​

ctx​

info​

반환값​

onFinish?​

매개변수​

ctx​

info​

반환값​

onInterruptBoundary?​

매개변수​

ctx​

반환값​

onInterruptResolution?​

매개변수​

ctx​

resolutions​

반환값​

onIteration?​

매개변수​

ctx​

info​

반환값​

onShouldContinue?​

매개변수​

ctx​

state​

반환값​

onStart?​

매개변수​

ctx​

반환값​

onStructuredOutputConfig?​

매개변수​

ctx​

config​

반환값​

onToolPhaseComplete?​

매개변수​

ctx​

info​

반환값​

onUsage?​

매개변수​

ctx​

usage​

반환값​

예제

확장 대상

타입 매개변수

TContext

TInterruptDefinitions

속성

name?

onAbort?

매개변수

ctx

info

반환값

onAfterToolCall?

매개변수

ctx

info

반환값

onBeforeToolCall?

매개변수

ctx

hookCtx

반환값

onChunk?

매개변수

ctx

chunk

반환값

onConfig?

매개변수

ctx

config

반환값

onError?

매개변수

ctx

info

반환값

onFinish?

매개변수

ctx

info

반환값

onInterruptBoundary?

매개변수

ctx

반환값

onInterruptResolution?

매개변수

ctx

resolutions

반환값

onIteration?

매개변수

ctx

info

반환값

onShouldContinue?

매개변수

ctx

state

반환값

onStart?

매개변수

ctx

반환값

onStructuredOutputConfig?

매개변수

ctx

config

반환값

onToolPhaseComplete?

매개변수

ctx

info

반환값

onUsage?

매개변수

ctx

usage

반환값