Interface: ChatMiddleware#
Defined in: packages/typescript/ai/src/activities/chat/middleware/types.ts:350
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 redactionMiddleware: ChatMiddleware = {
name: 'redaction',
onChunk(ctx, chunk) {
if (chunk.type === 'TEXT_MESSAGE_CONTENT') {
return { ...chunk, delta: redact(chunk.delta) }
}
},
}
Properties#
name?#
optional name: string;
Defined in: packages/typescript/ai/src/activities/chat/middleware/types.ts:352
Optional name for debugging and identification
onAbort()?#
optional onAbort: (ctx, info) => void | Promise<void>;
Defined in: packages/typescript/ai/src/activities/chat/middleware/types.ts:472
Called when the chat run is aborted. Exactly one of onFinish/onAbort/onError will be called per run.
Parameters#
ctx#
info#
Returns#
void | Promise<void>
onAfterToolCall()?#
optional onAfterToolCall: (ctx, info) => void | Promise<void>;
Defined in: packages/typescript/ai/src/activities/chat/middleware/types.ts:436
Called after a tool execution completes (success or failure).
Parameters#
ctx#
info#
Returns#
void | Promise<void>
onBeforeToolCall()?#
optional onBeforeToolCall: (ctx, hookCtx) =>
| BeforeToolCallDecision
| Promise<BeforeToolCallDecision>;
Defined in: packages/typescript/ai/src/activities/chat/middleware/types.ts:428
Called before a tool is executed. Can observe, transform args, skip execution, or abort the run.
Parameters#
ctx#
hookCtx#
Returns#
| BeforeToolCallDecision
| Promise<BeforeToolCallDecision>
onChunk()?#
optional onChunk: (ctx, chunk) =>
| void
| AGUIEvent
| AGUIEvent[]
| Promise<void | AGUIEvent | AGUIEvent[] | null>
| null;
Defined in: packages/typescript/ai/src/activities/chat/middleware/types.ts:414
Called for every chunk yielded by chat(). Can observe, transform, expand, or drop chunks.
Parameters#
ctx#
chunk#
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;
Defined in: packages/typescript/ai/src/activities/chat/middleware/types.ts:361
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#
config#
Returns#
| void
| Partial<ChatMiddlewareConfig>
| Promise<
| void
| Partial<ChatMiddlewareConfig>
| null>
| null
onError()?#
optional onError: (ctx, info) => void | Promise<void>;
Defined in: packages/typescript/ai/src/activities/chat/middleware/types.ts:481
Called when the chat run encounters an unhandled error. Exactly one of onFinish/onAbort/onError will be called per run.
Parameters#
ctx#
info#
Returns#
void | Promise<void>
onFinish()?#
optional onFinish: (ctx, info) => void | Promise<void>;
Defined in: packages/typescript/ai/src/activities/chat/middleware/types.ts:463
Called when the chat run completes normally. Exactly one of onFinish/onAbort/onError will be called per run.
Parameters#
ctx#
info#
Returns#
void | Promise<void>
onIteration()?#
optional onIteration: (ctx, info) => void | Promise<void>;
Defined in: packages/typescript/ai/src/activities/chat/middleware/types.ts:403
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#
info#
Returns#
void | Promise<void>
onStart()?#
optional onStart: (ctx) => void | Promise<void>;
Defined in: packages/typescript/ai/src/activities/chat/middleware/types.ts:397
Called when the chat run starts (after initial onConfig).
Parameters#
ctx#
Returns#
void | Promise<void>
onStructuredOutputConfig()?#
optional onStructuredOutputConfig: (ctx, config) =>
| void
| Partial<StructuredOutputMiddlewareConfig>
| Promise<
| void
| Partial<StructuredOutputMiddlewareConfig>
| null>
| null;
Defined in: packages/typescript/ai/src/activities/chat/middleware/types.ts:385
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#
config#
StructuredOutputMiddlewareConfig
Returns#
| void
| Partial<StructuredOutputMiddlewareConfig>
| Promise<
| void
| Partial<StructuredOutputMiddlewareConfig>
| null>
| null
onToolPhaseComplete()?#
optional onToolPhaseComplete: (ctx, info) => void | Promise<void>;
Defined in: packages/typescript/ai/src/activities/chat/middleware/types.ts:445
Called after all tool calls in an iteration have been processed. Provides aggregate data about tool execution results, approvals, and client tools.
Parameters#
ctx#
info#
Returns#
void | Promise<void>
onUsage()?#
optional onUsage: (ctx, usage) => void | Promise<void>;
Defined in: packages/typescript/ai/src/activities/chat/middleware/types.ts:454
Called when usage data is available from a RUN_FINISHED chunk. Called once per model iteration that reports usage.
Parameters#
ctx#
usage#
Returns#
void | Promise<void>