feat(ai): add experimental callbacks in generateText (#12654)

## Background

our current telemetry setup was heavily integrated with OTel. this is
the first step in decoupling the telemetry from the core functions

## Summary

- added callback `experimental_onStart` that exposes the data/events
that happen at the very beginning
- added callback `experimental_onStepStart`
- added callback `experimental_onToolCallStart`
- added callback `experimental_onToolCallFinish`
- modified callback `onStepFinish` - turned into an event that returns
[this](https://github.com/vercel/ai/pull/12654/changes#diff-d56ad94c7c3802f6ed5388ec6735018d179fa70735a40c8c79def79e5927d946R1024-R1045)
information

## Manual Verification



## Checklist

- [x] Tests have been added / updated (for bug fixes / features)
- [x] Documentation has been added / updated (for bug fixes / features)
- [x] A _patch_ changeset for relevant packages has been added (for bug
fixes / features - run `pnpm changeset` in the project root)
- [x] I have reviewed this pull request (self-review)

## Future Work

- add callbacks for streamText()
- refactor generateImage
- refactor embed
- https://github.com/vercel/ai/pull/12654/changes#r2829080416

Author: aayush-kapoor

.changeset/lazy-cougars-smoke.md

@@ -0,0 +1,5 @@
+---
+'ai': patch
+---
+
+feat(ai): add experimental callbacks in generateText

content/docs/03-agents/02-building-agents.mdx

@@ -331,13 +331,14 @@ export async function POST(request: Request) {
 
 ### Track Step Progress
 
-Use `onStepFinish` to track each step's progress, including token usage:
+Use `onStepFinish` to track each step's progress, including token usage.
+The callback receives a `stepNumber` (zero-based) to identify which step just completed:
 
 ```ts
 const result = await myAgent.generate({
   prompt: 'Research and summarize the latest AI trends',
-  onStepFinish: async ({ usage, finishReason, toolCalls }) => {
-    console.log('Step completed:', {
+  onStepFinish: async ({ stepNumber, usage, finishReason, toolCalls }) => {
+    console.log(`Step ${stepNumber} completed:`, {
       inputTokens: usage.inputTokens,
       outputTokens: usage.outputTokens,
       finishReason,
@@ -352,18 +353,18 @@ You can also define `onStepFinish` in the constructor for agent-wide tracking. W
 ```ts
 const agent = new ToolLoopAgent({
   model: __MODEL__,
-  onStepFinish: async ({ usage }) => {
+  onStepFinish: async ({ stepNumber, usage }) => {
     // Agent-wide logging
-    console.log('Agent step:', usage.totalTokens);
+    console.log(`Agent step ${stepNumber}:`, usage.totalTokens);
   },
 });
 
 // Method-level callback runs after constructor callback
 const result = await agent.generate({
   prompt: 'Hello',
-  onStepFinish: async ({ usage }) => {
+  onStepFinish: async ({ stepNumber, usage }) => {
     // Per-call tracking (e.g., for billing)
-    await trackUsage(usage);
+    await trackUsage(stepNumber, usage);
   },
 });
 ```

content/docs/03-ai-sdk-core/05-generating-text.mdx

@@ -105,6 +105,60 @@ const result = await generateText({
 });
 ```
 
+### Lifecycle callbacks (experimental)
+
+<Note type="warning">
+  Experimental callbacks are subject to breaking changes in incremental package
+  releases.
+</Note>
+
+`generateText` provides several experimental lifecycle callbacks that let you hook into different phases of the generation process.
+These are useful for logging, observability, debugging, and custom telemetry.
+Errors thrown inside these callbacks are silently caught and do not break the generation flow.
+
+```tsx
+import { generateText } from 'ai';
+__PROVIDER_IMPORT__;
+
+const result = await generateText({
+  model: __MODEL__,
+  prompt: 'What is the weather in San Francisco?',
+  tools: {
+    // ... your tools
+  },
+
+  experimental_onStart({ model, settings, functionId }) {
+    console.log('Generation started', { model, functionId });
+  },
+
+  experimental_onStepStart({ stepNumber, model, promptMessages }) {
+    console.log(`Step ${stepNumber} starting`, { model: model.modelId });
+  },
+
+  experimental_onToolCallStart({ toolName, toolCallId, input }) {
+    console.log(`Tool call starting: ${toolName}`, { toolCallId });
+  },
+
+  experimental_onToolCallFinish({ toolName, durationMs, error }) {
+    console.log(`Tool call finished: ${toolName} (${durationMs}ms)`, {
+      success: !error,
+    });
+  },
+
+  onStepFinish({ stepNumber, finishReason, usage }) {
+    console.log(`Step ${stepNumber} finished`, { finishReason, usage });
+  },
+});
+```
+
+The available lifecycle callbacks are:
+
+- **`experimental_onStart`**: Called once when the `generateText` operation begins, before any LLM calls. Receives model info, prompt, settings, and telemetry metadata.
+- **`experimental_onStepStart`**: Called before each step (LLM call). Receives the step number, model, prompt messages being sent, tools, and prior steps.
+- **`experimental_onToolCallStart`**: Called right before a tool's `execute` function runs. Receives the tool name, call ID, and input.
+- **`experimental_onToolCallFinish`**: Called right after a tool's `execute` function completes or errors. Receives the tool name, call ID, input, output (or undefined on error), error (or undefined on success), and `durationMs`.
+- **`onStepFinish`**: Called after each step finishes. Now also includes `stepNumber` (zero-based index of the completed step).
+
 ## `streamText`
 
 Depending on your model and prompt, it can take a large language model (LLM) up to a minute to finish generating its response. This delay can be unacceptable for interactive use cases such as chatbots or real-time applications, where users expect immediate responses.

content/docs/03-ai-sdk-core/15-tools-and-tool-calling.mdx

@@ -304,17 +304,59 @@ is triggered when a step is finished,
 i.e. all text deltas, tool calls, and tool results for the step are available.
 When you have multiple steps, the callback is triggered for each step.
 
-```tsx highlight="5-7"
+The callback receives a `stepNumber` (zero-based) to identify which step just completed:
+
+```tsx highlight="5-8"
 import { generateText } from 'ai';
 
 const result = await generateText({
   // ...
-  onStepFinish({ text, toolCalls, toolResults, finishReason, usage }) {
+  onStepFinish({
+    stepNumber,
+    text,
+    toolCalls,
+    toolResults,
+    finishReason,
+    usage,
+  }) {
+    console.log(`Step ${stepNumber} finished (${finishReason})`);
     // your own logic, e.g. for saving the chat history or recording usage
   },
 });
 ```
 
+### Tool execution lifecycle callbacks
+
+You can use `experimental_onToolCallStart` and `experimental_onToolCallFinish` to observe tool execution.
+These callbacks are called right before and after each tool's `execute` function, giving you
+visibility into tool execution timing, inputs, outputs, and errors:
+
+```tsx highlight="5-14"
+import { generateText } from 'ai';
+
+const result = await generateText({
+  // ... model, tools, prompt
+  experimental_onToolCallStart({ toolName, toolCallId, input }) {
+    console.log(`Calling tool: ${toolName}`, { toolCallId, input });
+  },
+  experimental_onToolCallFinish({
+    toolName,
+    toolCallId,
+    output,
+    error,
+    durationMs,
+  }) {
+    if (error) {
+      console.error(`Tool ${toolName} failed after ${durationMs}ms:`, error);
+    } else {
+      console.log(`Tool ${toolName} completed in ${durationMs}ms`, { output });
+    }
+  },
+});
+```
+
+Errors thrown inside these callbacks are silently caught and do not break the generation flow.
+
 ### `prepareStep` callback
 
 The `prepareStep` callback is called before a step is started.