Interface PerTraceTelemetry

Optionally runs the language model call in a telemetry-integration-specific context. This enables auto-instrumented model provider requests to become children of the current model-call span.

The options carry the model-call start-event content as context (the event fields are optional), alongside the always-present callId and the execute function that performs the model call.

Optionally runs the tool execute function in a telemetry-integration-specific context. This enables nested traces — e.g. when a tool's execute function calls generateText, the inner call's spans become children of the tool span.

The options carry the tool-execution start-event content as context (the event fields are optional), alongside the always-present callId, toolCallId, and the execute function to run.

Called when a streaming text generation operation is aborted before it completes.

Called when an individual embedding model call (doEmbed) completes. Contains the embeddings, usage, and any warnings from the model response.

Called when an individual embedding model call (doEmbed) begins. For embed, there is one call. For embedMany, there may be multiple calls when values are chunked.

Called when an operation completes. Fired for text generation (generateText/streamText), object generation (generateObject/streamObject), embedding (embed/embedMany), and reranking operations.

Use the event shape or operationId to distinguish between operation types.

Called when an unrecoverable error occurs during the generation lifecycle. The error value is untyped — it may be an Error instance, an AISDKError, or any thrown value.

Use this to record error details on telemetry spans and set error status.

Called after the model response has been normalized and parsed, but before any client-side tool execution begins.

Called immediately before the provider model call begins. Unlike onStepStart, this callback is scoped to model work only and excludes any later client-side tool execution.

Called when an object generation step (single LLM invocation) completes, with the raw result before JSON parsing and schema validation.

Called when an object generation step (single LLM invocation) begins. For generateObject/streamObject there is always exactly one step.

Called when an individual reranking model call (doRerank) completes. Contains the ranking results from the model response.

Called when an individual reranking model call (doRerank) begins. There is one call per rerank invocation.

Called when an operation begins. Fired for text generation (generateText/streamText), object generation (generateObject/streamObject), embedding (embed/embedMany), and reranking operations.

Use the operationId field to distinguish between operation types.

Called when an individual step (single LLM invocation) completes. The event is a StepResult containing the model's response, tool calls and results, usage statistics, finish reason, and optional request/response bodies.

Called when an individual step (single LLM invocation) completes.

Called when an individual step (single LLM invocation) begins. A generation may consist of multiple steps (e.g. when tool calls trigger follow-up LLM calls). Use this to create per-step spans or record step-level inputs.

The event includes the step number, accumulated previous step results, and the messages that will be sent to the model.

Called when a tool execution completes, either successfully or with an error. The event uses a discriminated union on the success field — check event.success to determine whether output or error is available.

The event includes execution time (toolExecutionMs) for performance tracking.

Called when a tool execution begins, before the tool's execute function is invoked. Use this to create tool-level spans or log tool invocations.