Interface: GenerationMiddleware<TContext>#

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

Activity-agnostic, observe-only middleware.

A thin lifecycle observer registerable on any activity via its middleware option. Unlike ChatMiddleware (which can also rewrite config, chunks, and tool calls), these hooks only observe — the right fit for the single request → response shape of media activities. Pass otelMiddleware() for OpenTelemetry, or implement the hooks directly for a custom backend.

Hooks are awaited in registration order. A hook that throws PROPAGATES and fails the activity — matching chat() middleware semantics. Keep them cheap; they run inline with the request.

Exactly one of onFinish / onAbort / onError fires per call.

Example#

import { generateImage } from '@tanstack/ai'
import { otelMiddleware } from '@tanstack/ai/middlewares/otel'
import { openaiImage } from '@tanstack/ai-openai'
import { trace } from '@opentelemetry/api'

await generateImage({
  adapter: openaiImage('gpt-image-1'),
  prompt: 'A serene mountain landscape at sunset',
  middleware: [otelMiddleware({ tracer: trace.getTracer('my-app') })],
})

Type Parameters#

TContext#

TContext = unknown

Properties#

name?#

optional name: string;

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

Optional name, surfaced in diagnostics.

onAbort()?#

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

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

Called when the activity is aborted (e.g. an abandoned stream).

Parameters#

ctx#

GenerationMiddlewareContext<TContext>

info#

GenerationAbortInfo

Returns#

void | Promise<void>

onError()?#

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

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

Called when the activity throws before completing.

Parameters#

ctx#

GenerationMiddlewareContext<TContext>

info#

GenerationErrorInfo

Returns#

void | Promise<void>

onFinish()?#

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

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

Called after the activity completes successfully.

Parameters#

ctx#

GenerationMiddlewareContext<TContext>

info#

GenerationFinishInfo

Returns#

void | Promise<void>

onStart()?#

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

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

Called before the adapter request begins.

Parameters#

ctx#

GenerationMiddlewareContext<TContext>

Returns#

void | Promise<void>

onUsage()?#

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

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

Called when the provider reports usage, before onFinish.

Parameters#

ctx#

GenerationMiddlewareContext<TContext>

usage#

GenerationUsageInfo

Returns#

void | Promise<void>