Open History to see the last commit
1---
2id: GenerationMiddleware
3title: GenerationMiddleware
4---
5
6# Interface: GenerationMiddleware\<TContext\>
7
8Defined in: [packages/ai/src/activities/middleware/types.ts:145](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/middleware/types.ts#L145)
9
10Activity-agnostic, observe-only middleware.
11
12A thin lifecycle observer registerable on any activity via its `middleware`
13option. Unlike `ChatMiddleware` (which can also rewrite config, chunks, and
14tool calls), these hooks only observe — the right fit for the single
15request → response shape of media activities. Pass `otelMiddleware()` for
16OpenTelemetry, or implement the hooks directly for a custom backend.
17
18Hooks are awaited in registration order. A hook that throws PROPAGATES and
19fails the activity — matching `chat()` middleware semantics. Keep them cheap;
20they run inline with the request.
21
22Exactly one of `onFinish` / `onAbort` / `onError` fires per call.
23
24## Example
25
26```ts
27import { generateImage } from '@tanstack/ai'
28import { otelMiddleware } from '@tanstack/ai/middlewares/otel'
29import { openaiImage } from '@tanstack/ai-openai'
30import { trace } from '@opentelemetry/api'
31
32await generateImage({
33 adapter: openaiImage('gpt-image-1'),
34 prompt: 'A serene mountain landscape at sunset',
35 middleware: [otelMiddleware({ tracer: trace.getTracer('my-app') })],
36})
37```
38
39## Type Parameters
40
41### TContext
42
43`TContext` = `unknown`
44
45## Properties
46
47### name?
48
49```ts
50optional name: string;
51```
52
53Defined in: [packages/ai/src/activities/middleware/types.ts:147](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/middleware/types.ts#L147)
54
55Optional name, surfaced in diagnostics.
56
57***
58
59### onAbort()?
60
61```ts
62optional onAbort: (ctx, info) => void | Promise<void>;
63```
64
65Defined in: [packages/ai/src/activities/middleware/types.ts:161](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/middleware/types.ts#L161)
66
67Called when the activity is aborted (e.g. an abandoned stream).
68
69#### Parameters
70
71##### ctx
72
73[`GenerationMiddlewareContext`](GenerationMiddlewareContext.md)\<`TContext`\>
74
75##### info
76
77[`GenerationAbortInfo`](GenerationAbortInfo.md)
78
79#### Returns
80
81`void` \| `Promise`\<`void`\>
82
83***
84
85### onError()?
86
87```ts
88optional onError: (ctx, info) => void | Promise<void>;
89```
90
91Defined in: [packages/ai/src/activities/middleware/types.ts:166](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/middleware/types.ts#L166)
92
93Called when the activity throws before completing.
94
95#### Parameters
96
97##### ctx
98
99[`GenerationMiddlewareContext`](GenerationMiddlewareContext.md)\<`TContext`\>
100
101##### info
102
103[`GenerationErrorInfo`](GenerationErrorInfo.md)
104
105#### Returns
106
107`void` \| `Promise`\<`void`\>
108
109***
110
111### onFinish()?
112
113```ts
114optional onFinish: (ctx, info) => void | Promise<void>;
115```
116
117Defined in: [packages/ai/src/activities/middleware/types.ts:156](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/middleware/types.ts#L156)
118
119Called after the activity completes successfully.
120
121#### Parameters
122
123##### ctx
124
125[`GenerationMiddlewareContext`](GenerationMiddlewareContext.md)\<`TContext`\>
126
127##### info
128
129[`GenerationFinishInfo`](GenerationFinishInfo.md)
130
131#### Returns
132
133`void` \| `Promise`\<`void`\>
134
135***
136
137### onStart()?
138
139```ts
140optional onStart: (ctx) => void | Promise<void>;
141```
142
143Defined in: [packages/ai/src/activities/middleware/types.ts:149](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/middleware/types.ts#L149)
144
145Called before the adapter request begins.
146
147#### Parameters
148
149##### ctx
150
151[`GenerationMiddlewareContext`](GenerationMiddlewareContext.md)\<`TContext`\>
152
153#### Returns
154
155`void` \| `Promise`\<`void`\>
156
157***
158
159### onUsage()?
160
161```ts
162optional onUsage: (ctx, usage) => void | Promise<void>;
163```
164
165Defined in: [packages/ai/src/activities/middleware/types.ts:151](https://github.com/TanStack/ai/blob/main/packages/ai/src/activities/middleware/types.ts#L151)
166
167Called when the provider reports usage, before `onFinish`.
168
169#### Parameters
170
171##### ctx
172
173[`GenerationMiddlewareContext`](GenerationMiddlewareContext.md)\<`TContext`\>
174
175##### usage
176
177[`GenerationUsageInfo`](GenerationUsageInfo.md)
178
179#### Returns
180
181`void` \| `Promise`\<`void`\>