Interface: ChatMiddleware<TContext>#

Defined in: packages/ai/src/activities/chat/middleware/types.ts:343

Chat middleware interface.

All hooks are optional. Middleware is composed in array order:

• onConfig: config piped through middlewares in order (first transform influences later)
• onChunk: each output chunk is fed into the next middleware in order

Examples#

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 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) }
    }
  },
}

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

Type Parameters#

TContext#

TContext = unknown

Properties#

name?#

optional name: string;

optional name: string;

Defined in: packages/ai/src/activities/chat/middleware/types.ts:345

Optional name for debugging and identification

onAbort()?#

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

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

Defined in: packages/ai/src/activities/chat/middleware/types.ts:465

Called when the chat run is aborted. Exactly one of onFinish/onAbort/onError will be called per run.

Parameters#

ctx#

ChatMiddlewareContext<TContext>

info#

AbortInfo

Returns#

void | Promise<void>

onAfterToolCall()?#

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

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

Defined in: packages/ai/src/activities/chat/middleware/types.ts:429

Called after a tool execution completes (success or failure).

Parameters#

ctx#

ChatMiddlewareContext<TContext>

info#

AfterToolCallInfo

Returns#

void | Promise<void>

onBeforeToolCall()?#

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

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

Defined in: packages/ai/src/activities/chat/middleware/types.ts:421

Called before a tool is executed. Can observe, transform args, skip execution, or abort the run.

Parameters#

ctx#

ChatMiddlewareContext<TContext>

hookCtx#

ToolCallHookContext

Returns#

| BeforeToolCallDecision | Promise<BeforeToolCallDecision>

onChunk()?#

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

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

Defined in: packages/ai/src/activities/chat/middleware/types.ts:407

Called for every chunk yielded by chat(). Can observe, transform, expand, or drop chunks.

Parameters#

ctx#

ChatMiddlewareContext<TContext>

chunk#

AGUIEvent

Returns#

| void | AGUIEvent | AGUIEvent[] | Promise<void | AGUIEvent | AGUIEvent[] | null> | null

void (pass through), chunk (replace), chunk[] (expand), null (drop)

onConfig()?#

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

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

Defined in: packages/ai/src/activities/chat/middleware/types.ts:354

Called to observe or transform the chat configuration. Called at init and at the beginning of each agent iteration.

Return a partial config to merge with the current config, or void to pass through. Only the fields you return are overwritten — everything else is preserved.

Parameters#

ctx#

ChatMiddlewareContext<TContext>

config#

ChatMiddlewareConfig

Returns#

| void | Partial<ChatMiddlewareConfig> | Promise< | void | Partial<ChatMiddlewareConfig> | null> | null

onError()?#

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

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

Defined in: packages/ai/src/activities/chat/middleware/types.ts:474

Called when the chat run encounters an unhandled error. Exactly one of onFinish/onAbort/onError will be called per run.

Parameters#

ctx#

ChatMiddlewareContext<TContext>

info#

ErrorInfo

Returns#

void | Promise<void>

onFinish()?#

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

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

Defined in: packages/ai/src/activities/chat/middleware/types.ts:456

Called when the chat run completes normally. Exactly one of onFinish/onAbort/onError will be called per run.

Parameters#

ctx#

ChatMiddlewareContext<TContext>

info#

FinishInfo

Returns#

void | Promise<void>

onIteration()?#

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

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

Defined in: packages/ai/src/activities/chat/middleware/types.ts:396

Called at the start of each agent loop iteration, after a new assistant message ID is created. Use this to observe iteration boundaries.

Parameters#

ctx#

ChatMiddlewareContext<TContext>

info#

IterationInfo

Returns#

void | Promise<void>

onStart()?#

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

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

Defined in: packages/ai/src/activities/chat/middleware/types.ts:390

Called when the chat run starts (after initial onConfig).

Parameters#

ctx#

ChatMiddlewareContext<TContext>

Returns#

void | Promise<void>

onStructuredOutputConfig()?#

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

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

Defined in: packages/ai/src/activities/chat/middleware/types.ts:378

Called at the start of the final structured-output call (when the chat was invoked with outputSchema). Pipes through middleware in order, like onConfig, but with access to the JSON Schema being sent to the provider.

Return a partial to shallow-merge into the current config, or void to pass through.

Fires BEFORE onConfig at the structured-output boundary. onConfig also re-fires at the same boundary with ctx.phase === 'structuredOutput', receiving the post-onStructuredOutputConfig view of the config (minus outputSchema). Use onConfig for general-purpose transforms that apply to every adapter call; use this hook when you need to transform the outputSchema or apply structured-output-specific behavior.

Parameters#

ctx#

ChatMiddlewareContext<TContext>

config#

StructuredOutputMiddlewareConfig

Returns#

| void | Partial<StructuredOutputMiddlewareConfig> | Promise< | void | Partial<StructuredOutputMiddlewareConfig> | null> | null

onToolPhaseComplete()?#

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

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

Defined in: packages/ai/src/activities/chat/middleware/types.ts:438

Called after all tool calls in an iteration have been processed. Provides aggregate data about tool execution results, approvals, and client tools.

Parameters#

ctx#

ChatMiddlewareContext<TContext>

info#

ToolPhaseCompleteInfo

Returns#

void | Promise<void>

onUsage()?#

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

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

Defined in: packages/ai/src/activities/chat/middleware/types.ts:447

Called when usage data is available from a RUN_FINISHED chunk. Called once per model iteration that reports usage.

Parameters#

ctx#

ChatMiddlewareContext<TContext>

usage#

UsageInfo

Returns#

void | Promise<void>