| id | ChatMiddleware |
|---|---|
| title | ChatMiddleware |
Defined in: packages/typescript/ai/src/activities/chat/middleware/types.ts:342
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
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) }
}
},
}optional name: string;Defined in: packages/typescript/ai/src/activities/chat/middleware/types.ts:344
Optional name for debugging and identification
optional onAbort: (ctx, info) => void | Promise<void>;Defined in: packages/typescript/ai/src/activities/chat/middleware/types.ts:464
Called when the chat run is aborted. Exactly one of onFinish/onAbort/onError will be called per run.
void | Promise<void>
optional onAfterToolCall: (ctx, info) => void | Promise<void>;Defined in: packages/typescript/ai/src/activities/chat/middleware/types.ts:428
Called after a tool execution completes (success or failure).
void | Promise<void>
optional onBeforeToolCall: (ctx, hookCtx) =>
| BeforeToolCallDecision
| Promise<BeforeToolCallDecision>;Defined in: packages/typescript/ai/src/activities/chat/middleware/types.ts:420
Called before a tool is executed. Can observe, transform args, skip execution, or abort the run.
| BeforeToolCallDecision
| Promise<BeforeToolCallDecision>
optional onChunk: (ctx, chunk) =>
| void
| AGUIEvent
| AGUIEvent[]
| Promise<void | AGUIEvent | AGUIEvent[] | null>
| null;Defined in: packages/typescript/ai/src/activities/chat/middleware/types.ts:406
Called for every chunk yielded by chat(). Can observe, transform, expand, or drop chunks.
| void
| AGUIEvent
| AGUIEvent[]
| Promise<void | AGUIEvent | AGUIEvent[] | null>
| null
void (pass through), chunk (replace), chunk[] (expand), null (drop)
optional onConfig: (ctx, config) =>
| void
| Partial<ChatMiddlewareConfig>
| Promise<void | Partial<ChatMiddlewareConfig>>
| null;Defined in: packages/typescript/ai/src/activities/chat/middleware/types.ts:353
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.
| void
| Partial<ChatMiddlewareConfig>
| Promise<void | Partial<ChatMiddlewareConfig>>
| null
optional onError: (ctx, info) => void | Promise<void>;Defined in: packages/typescript/ai/src/activities/chat/middleware/types.ts:473
Called when the chat run encounters an unhandled error. Exactly one of onFinish/onAbort/onError will be called per run.
void | Promise<void>
optional onFinish: (ctx, info) => void | Promise<void>;Defined in: packages/typescript/ai/src/activities/chat/middleware/types.ts:455
Called when the chat run completes normally. Exactly one of onFinish/onAbort/onError will be called per run.
void | Promise<void>
optional onIteration: (ctx, info) => void | Promise<void>;Defined in: packages/typescript/ai/src/activities/chat/middleware/types.ts:395
Called at the start of each agent loop iteration, after a new assistant message ID is created. Use this to observe iteration boundaries.
void | Promise<void>
optional onStart: (ctx) => void | Promise<void>;Defined in: packages/typescript/ai/src/activities/chat/middleware/types.ts:389
Called when the chat run starts (after initial onConfig).
void | Promise<void>
optional onStructuredOutputConfig: (ctx, config) =>
| void
| Partial<StructuredOutputMiddlewareConfig>
| Promise<
| void
| Partial<StructuredOutputMiddlewareConfig>>
| null;Defined in: packages/typescript/ai/src/activities/chat/middleware/types.ts:377
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.
StructuredOutputMiddlewareConfig
| void
| Partial<StructuredOutputMiddlewareConfig>
| Promise<
| void
| Partial<StructuredOutputMiddlewareConfig>>
| null
optional onToolPhaseComplete: (ctx, info) => void | Promise<void>;Defined in: packages/typescript/ai/src/activities/chat/middleware/types.ts:437
Called after all tool calls in an iteration have been processed. Provides aggregate data about tool execution results, approvals, and client tools.
void | Promise<void>
optional onUsage: (ctx, usage) => void | Promise<void>;Defined in: packages/typescript/ai/src/activities/chat/middleware/types.ts:446
Called when usage data is available from a RUN_FINISHED chunk. Called once per model iteration that reports usage.
void | Promise<void>