본문으로 건너뛰기

인터페이스: DefinedChatMiddleware<TContext, TRequires, TProvides, TInterruptDefinitions>

정의 위치: packages/ai/src/activities/chat/middleware/define.ts:11

requires/provides 튜플 타입을 배열 포함 범위 검사와 빌더에 사용할 수 있도록 (const 추론을 통해) 정확하게 캡처하는 미들웨어입니다.

확장​

타입 매개변수​

TContext​

TContext

TRequires​

TRequires extends ReadonlyArray<CapabilityHandle>

TProvides​

TProvides extends ReadonlyArray<CapabilityHandle>

TInterruptDefinitions​

TInterruptDefinitions extends AnyInterruptDefinition = never

속성​

name?​

optional name?: string;

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

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

상속됨​

ChatMiddleware.name

onAbort?​

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

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

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

매개변수​

ctx​

ChatMiddlewareContext&lt;TContext>

info​

AbortInfo

반환값​

void | Promise&lt;void>

상속됨​

ChatMiddleware.onAbort

onAfterToolCall?​

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

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

도구 실행이 완료된 후(성공 또는 실패 여부와 관계없이) 호출됩니다.

매개변수​

ctx​

ChatMiddlewareContext&lt;TContext>

info​

AfterToolCallInfo

반환값​

void | Promise&lt;void>

상속됨​

ChatMiddleware.onAfterToolCall

onBeforeToolCall?​

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

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

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

매개변수​

ctx​

ChatMiddlewareContext&lt;TContext>

hookCtx​

ToolCallHookContext

반환값​

| BeforeToolCallDecision | Promise&lt;BeforeToolCallDecision>

상속됨​

ChatMiddleware.onBeforeToolCall

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&lt;TContext>

chunk​

AGUIEvent

반환값​

| void | AGUIEvent | AGUIEvent[] | Promise&lt;void | AGUIEvent | AGUIEvent[] | null> | null

void (그대로 전달), chunk (대체), chunk[] (expand), null (삭제)

상속됨​

ChatMiddleware.onChunk

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&lt;TContext>

config​

ChatMiddlewareConfig

반환값​

| void | Partial&lt;ChatMiddlewareConfig> | Promise&lt; | void | Partial&lt;ChatMiddlewareConfig> | null> | null

상속됨​

ChatMiddleware.onConfig

onError?​

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

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

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

매개변수​

ctx​

ChatMiddlewareContext&lt;TContext>

info​

ErrorInfo

반환값​

void | Promise&lt;void>

상속됨​

ChatMiddleware.onError

onFinish?​

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

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

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

매개변수​

ctx​

ChatMiddlewareContext&lt;TContext>

info​

FinishInfo

반환값​

void | Promise&lt;void>

상속됨​

ChatMiddleware.onFinish

onInterruptBoundary?​

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

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

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

매개변수​

ctx​

ChatMiddlewareContext&lt;TContext> & object

반환값​

| InterruptBoundaryResult&lt;TInterruptDefinitions> | Promise&lt;InterruptBoundaryResult&lt;TInterruptDefinitions>>

상속됨​

ChatMiddleware.onInterruptBoundary

onInterruptResolution?​

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

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

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

매개변수​

ctx​

ChatMiddlewareContext&lt;TContext>

resolutions​

InterruptResolutionCollection&lt;TInterruptDefinitions>

반환값​

| InterruptResolutionResult | Promise&lt;InterruptResolutionResult>

상속됨​

ChatMiddleware.onInterruptResolution

onIteration?​

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

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

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

매개변수​

ctx​

ChatMiddlewareContext&lt;TContext>

info​

IterationInfo

반환값​

void | Promise&lt;void>

상속됨​

ChatMiddleware.onIteration

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&lt;TContext>

state​

AgentLoopState

반환값​

boolean | void | Promise&lt;boolean | void>

상속됨​

ChatMiddleware.onShouldContinue

onStart?​

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

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

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

매개변수​

ctx​

ChatMiddlewareContext&lt;TContext>

반환값​

void | Promise&lt;void>

상속됨​

ChatMiddleware.onStart

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와 마찬가지로 미들웨어를 순서대로 통과하지만, 프로바이더에 전달되는 JSON Schema에 액세스할 수 있습니다.

현재 구성에 얕게 병합할 부분 구성을 반환하거나, 그대로 전달하려면 void를 반환합니다.

구조화된 출력 경계에서 onConfig보다 먼저 실행됩니다. onConfig도 같은 경계에서 ctx.phase === 'structuredOutput'와 함께 다시 실행되며, onStructuredOutputConfig 이후 구성의 뷰(outputSchema 제외)를 받습니다. 모든 어댑터 호출에 적용할 일반적인 변환에는 onConfig를 사용하고, outputSchema를 변환하거나 구조화된 출력에만 해당하는 동작을 적용해야 할 때는 이 훅을 사용합니다.

매개변수​

ctx​

ChatMiddlewareContext&lt;TContext>

config​

StructuredOutputMiddlewareConfig

반환값​

| void | Partial&lt;StructuredOutputMiddlewareConfig> | Promise&lt; | void | Partial&lt;StructuredOutputMiddlewareConfig> | null> | null

상속됨​

ChatMiddleware.onStructuredOutputConfig

onToolPhaseComplete?​

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

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

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

매개변수​

ctx​

ChatMiddlewareContext&lt;TContext>

info​

ToolPhaseCompleteInfo

반환값​

void | Promise&lt;void>

상속됨​

ChatMiddleware.onToolPhaseComplete

onUsage?​

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

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

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

매개변수​

ctx​

ChatMiddlewareContext&lt;TContext>

usage​

UsageInfo

반환값​

void | Promise&lt;void>

상속됨​

ChatMiddleware.onUsage

optionalRequires?​

optional optionalRequires?: readonly CapabilityHandle[];

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

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

상속됨​

ChatMiddleware.optionalRequires

provides?​

optional provides?: TProvides;

정의 위치: packages/ai/src/activities/chat/middleware/define.ts:18

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

재정의​

ChatMiddleware.provides

requires?​

optional requires?: TRequires;

정의 위치: packages/ai/src/activities/chat/middleware/define.ts:17

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

재정의​

ChatMiddleware.requires

sandbox?​

optional sandbox?: ChatSandboxHooks<TContext>;

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

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

상속됨​

ChatMiddleware.sandbox

setup?​

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

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

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

매개변수​

ctx​

ChatMiddlewareContext&lt;TContext>

반환값​

void | Promise&lt;void>

상속됨​

ChatMiddleware.setup