GenerationMiddleware

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

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:197

Optional name, surfaced in diagnostics.

onAbort?#

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

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

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:216

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:206

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:199

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:201

Called when the provider reports usage, before onFinish.

Parameters#

ctx#

GenerationMiddlewareContext<TContext>

usage#

GenerationUsageInfo

Returns#

void | Promise<void>