fix(core): preserve usage and cost metadata on structured output failures

.changeset/soft-cost-errors.md

@@ -0,0 +1,12 @@
+---
+"@voltagent/core": patch
+---
+
+fix: preserve usage and provider cost metadata on structured output failures
+
+When `generateText` receives a successful model response but structured output is not produced,
+VoltAgent now keeps the resolved usage, finish reason, and provider metadata on the resulting
+error path.
+
+This preserves provider-reported cost data for observability spans and makes the same metadata
+available to error hooks through `VoltAgentError.metadata`.

packages/core/src/agent/agent-observability.spec.ts

@@ -1,8 +1,10 @@
+import * as ai from "ai";
 import { MockLanguageModelV3, mockId, simulateReadableStream } from "ai/test";
 import { beforeEach, describe, expect, it, vi } from "vitest";
 import { z } from "zod";
 import { NodeVoltAgentObservability, WebSocketEventEmitter } from "../observability";
 import { SpanKind, SpanStatusCode } from "../observability/types";
+import { Tool } from "../tool";
 import { Agent } from "./agent";
 import { createOutputGuardrail } from "./guardrail";
 
@@ -265,6 +267,80 @@ describe("Agent with Observability", () => {
       unsubscribe();
     });
 
+    it("should preserve provider cost when structured output generation fails after a successful model call", async () => {
+      const events: any[] = [];
+      const unsubscribe = WebSocketEventEmitter.getInstance().onWebSocketEvent((event) => {
+        events.push(event);
+      });
+
+      const tool = new Tool({
+        name: "echo_tool",
+        description: "Echo tool",
+        parameters: z.object({ value: z.string() }),
+      });
+      mockModel.doGenerate = async () => ({
+        finishReason: makeFinishReason("tool-calls"),
+        usage: makeProviderUsage(10, 20),
+        content: [],
+        toolCalls: [
+          {
+            toolCallId: mockId(),
+            toolName: "echo_tool",
+            args: { value: "hello" },
+          },
+        ],
+        warnings: [],
+        logprobs: undefined,
+        providerMetadata: makeOpenRouterProviderMetadata(),
+      });
+
+      const agent = new Agent({
+        name: "cost-agent-structured-output-error",
+        purpose: "Testing provider cost observability on structured output failures",
+        instructions: "You are a cost test agent",
+        model: mockModel as any,
+        observability,
+        maxRetries: 0,
+        tools: [tool],
+      });
+
+      await expect(
+        agent.generateText("Track cost", {
+          output: ai.Output.object({
+            schema: z.object({
+              message: z.string(),
+            }),
+          }),
+        }),
+      ).rejects.toThrow("Structured output was requested but no final output was generated");
+
+      const endSpans = events
+        .filter((event) => event.type === "span:end")
+        .map((event) => event.span);
+
+      const llmSpan = endSpans.find(
+        (span) =>
+          span.attributes["span.type"] === "llm" &&
+          span.attributes["llm.operation"] === "generateText",
+      );
+      expect(llmSpan).toBeDefined();
+      expect(llmSpan.status.code).toBe(SpanStatusCode.ERROR);
+      expect(llmSpan.attributes["usage.cost"]).toBe(0.0012);
+
+      const rootSpan = endSpans.find(
+        (span) =>
+          span.name === "cost-agent-structured-output-error" &&
+          span.attributes["entity.type"] === "agent" &&
+          span.attributes["span.type"] !== "llm",
+      );
+      expect(rootSpan).toBeDefined();
+      expect(rootSpan.status.code).toBe(SpanStatusCode.ERROR);
+      expect(rootSpan.attributes["usage.cost"]).toBe(0.0012);
+      expect(rootSpan.attributes["usage.is_byok"]).toBe(true);
+
+      unsubscribe();
+    });
+
     it("should handle errors and set error status", async () => {
       const events: any[] = [];
       const unsubscribe = WebSocketEventEmitter.getInstance().onWebSocketEvent((event) => {

packages/core/src/agent/agent.spec.ts

@@ -801,6 +801,8 @@ Use pandas and summarize findings.`.split("\n"),
     });
 
     it("should throw a descriptive error when structured output is missing", async () => {
+      const onEnd = vi.fn();
+      const onError = vi.fn();
       const tool = new Tool({
         name: "echo_tool",
         description: "Echo tool",
@@ -814,6 +816,7 @@ Use pandas and summarize findings.`.split("\n"),
         model: mockModel as any,
         tools: [tool],
         maxRetries: 0,
+        hooks: { onEnd, onError },
       });
 
       const toolCall = {
@@ -852,6 +855,14 @@ Use pandas and summarize findings.`.split("\n"),
           timestamp: new Date(),
           messages: [],
         },
+        providerMetadata: {
+          openrouter: {
+            usage: {
+              cost: 0.0012,
+              isByok: true,
+            },
+          },
+        },
         steps: [
           {
             text: "Tool call completed.",
@@ -906,6 +917,33 @@ Use pandas and summarize findings.`.split("\n"),
         stage: "response_parsing",
         code: "STRUCTURED_OUTPUT_NOT_GENERATED",
       });
+      expect(onEnd).toHaveBeenCalledWith(
+        expect.objectContaining({
+          error: expect.objectContaining({
+            code: "STRUCTURED_OUTPUT_NOT_GENERATED",
+            stage: "response_parsing",
+            metadata: expect.objectContaining({
+              finishReason: "tool-calls",
+              usage: expect.objectContaining({
+                inputTokens: 12,
+                outputTokens: 6,
+                totalTokens: 18,
+              }),
+              providerMetadata: expect.objectContaining({
+                openrouter: expect.any(Object),
+              }),
+            }),
+          }),
+        }),
+      );
+      expect(onError).toHaveBeenCalledWith(
+        expect.objectContaining({
+          error: expect.objectContaining({
+            code: "STRUCTURED_OUTPUT_NOT_GENERATED",
+            stage: "response_parsing",
+          }),
+        }),
+      );
     });
   });
 

packages/core/src/agent/agent.ts

@@ -336,6 +336,40 @@ const extractOpenRouterUsageCost = (providerMetadata: unknown): OpenRouterUsageC
   return Object.values(result).some((value) => value !== undefined) ? result : undefined;
 };
 
+type GenerationErrorDetails = {
+  usage?: LanguageModelUsage;
+  providerMetadata?: unknown;
+  finishReason?: string;
+};
+
+const toLanguageModelUsage = (value: unknown): LanguageModelUsage | undefined =>
+  isPlainObject(value) ? (value as LanguageModelUsage) : undefined;
+
+const extractGenerationErrorDetails = (error: unknown): GenerationErrorDetails => {
+  const metadata = isRecord(error) && isPlainObject(error.metadata) ? error.metadata : undefined;
+  const originalError = isRecord(error) ? error.originalError : undefined;
+
+  const usage = firstDefined(
+    isRecord(error) ? toLanguageModelUsage(error.usage) : undefined,
+    metadata ? toLanguageModelUsage(metadata.usage) : undefined,
+    isRecord(originalError) ? toLanguageModelUsage(originalError.usage) : undefined,
+  );
+
+  const providerMetadata = firstDefined(
+    metadata?.providerMetadata,
+    isRecord(error) ? error.providerMetadata : undefined,
+    isRecord(originalError) ? originalError.providerMetadata : undefined,
+  );
+
+  const finishReason = firstNonBlank(
+    isRecord(error) ? error.finishReason : undefined,
+    metadata?.finishReason,
+    isRecord(originalError) ? originalError.finishReason : undefined,
+  );
+
+  return { usage, providerMetadata, finishReason };
+};
+
 const isAssistantContentPart = (value: unknown): boolean => {
   if (!isRecord(value)) {
     return false;
@@ -1268,7 +1302,7 @@ export class Agent {
                     }),
                   );
 
-                  this.ensureStructuredOutputGenerated({
+                  await this.ensureStructuredOutputGenerated({
                     result: response,
                     output,
                     tools,
@@ -1286,7 +1320,13 @@ export class Agent {
 
                   return response;
                 } catch (error) {
-                  finalizeLLMSpan(SpanStatusCode.ERROR, { message: (error as Error).message });
+                  const errorDetails = extractGenerationErrorDetails(error);
+                  finalizeLLMSpan(SpanStatusCode.ERROR, {
+                    message: (error as Error).message,
+                    usage: errorDetails.usage,
+                    finishReason: errorDetails.finishReason,
+                    providerMetadata: errorDetails.providerMetadata,
+                  });
                   throw error;
                 }
               },
@@ -3541,15 +3581,15 @@ export class Agent {
     };
   }
 
-  private ensureStructuredOutputGenerated<
+  private async ensureStructuredOutputGenerated<
     TOOLS extends ToolSet,
     OUTPUT extends OutputSpec,
   >(params: {
     result: GenerateTextResult<TOOLS, OUTPUT>;
     output: OUTPUT | undefined;
     tools: Record<string, any>;
     maxSteps: number;
-  }): void {
+  }): Promise<void> {
     const { result, output, tools, maxSteps } = params;
     if (!output) {
       return;
@@ -3571,6 +3611,13 @@ export class Agent {
       const stepCount = result.steps?.length ?? 0;
       const finishReason = result.finishReason ?? "unknown";
       const reachedMaxSteps = stepCount >= maxSteps;
+      const providerMetadata = (result as { providerMetadata?: unknown }).providerMetadata;
+      const providerUsage = result.usage ? await Promise.resolve(result.usage) : undefined;
+      const usageForFinish = resolveFinishUsage({
+        providerMetadata,
+        usage: providerUsage,
+        totalUsage: (result as { totalUsage?: LanguageModelUsage }).totalUsage,
+      });
 
       const guidance =
         configuredToolCount > 0 || toolCalls.length > 0
@@ -3593,6 +3640,11 @@ export class Agent {
             maxSteps,
             configuredToolCount,
             toolCallCount: toolCalls.length,
+            usage: usageForFinish ? JSON.parse(safeStringify(usageForFinish)) : undefined,
+            providerMetadata:
+              providerMetadata !== undefined
+                ? JSON.parse(safeStringify(providerMetadata))
+                : undefined,
           },
         },
       );
@@ -7412,7 +7464,19 @@ export class Agent {
       throw oc.cancellationError;
     }
 
-    const voltagentError = createVoltAgentError(error);
+    const voltagentError = isVoltAgentError(error) ? error : createVoltAgentError(error);
+    const errorDetails = extractGenerationErrorDetails(voltagentError);
+
+    if (errorDetails.usage || errorDetails.providerMetadata !== undefined) {
+      this.recordRootSpanUsageAndProviderCost(
+        oc.traceContext,
+        errorDetails.usage,
+        errorDetails.providerMetadata,
+      );
+    }
+    if (errorDetails.finishReason) {
+      oc.traceContext.setFinishReason(errorDetails.finishReason);
+    }
 
     oc.traceContext.end("error", error);