@aigne/core 1.61.0-beta.3 → 1.61.0-beta.5

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # Changelog
 
+## [1.61.0-beta.5](https://github.com/AIGNE-io/aigne-framework/compare/core-v1.61.0-beta.4...core-v1.61.0-beta.5) (2025-09-25)
+
+
+### Features
+
+* **core:** add automatic JSON parsing and validation for structured outputs ([#548](https://github.com/AIGNE-io/aigne-framework/issues/548)) ([9077f93](https://github.com/AIGNE-io/aigne-framework/commit/9077f93856865915aaf5e8caa5638ef0b7f05b1e))
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @aigne/observability-api bumped to 0.11.0-beta
+
+## [1.61.0-beta.4](https://github.com/AIGNE-io/aigne-framework/compare/core-v1.61.0-beta.3...core-v1.61.0-beta.4) (2025-09-25)
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @aigne/observability-api bumped to 0.10.5-beta
+
 ## [1.61.0-beta.3](https://github.com/AIGNE-io/aigne-framework/compare/core-v1.61.0-beta.2...core-v1.61.0-beta.3) (2025-09-24)
 
 

package/lib/cjs/agents/chat-model.d.ts

@@ -111,6 +111,15 @@ export declare abstract class ChatModel extends Model<ChatModelInput, ChatModelO
      */
     abstract process(input: ChatModelInput, options: AgentInvokeOptions): PromiseOrValue<AgentProcessResult<ChatModelOutput>>;
     protected processAgentOutput(input: ChatModelInput, output: Exclude<AgentResponse<ChatModelOutput>, AgentResponseStream<ChatModelOutput>>, options: AgentInvokeOptions): Promise<ChatModelOutput>;
+    protected validateJsonSchema<T>(schema: object, data: T, options?: {
+        safe?: false;
+    }): T;
+    protected validateJsonSchema<T>(schema: object, data: T, options: {
+        safe: true;
+    }): z.SafeParseReturnType<T, T>;
+    protected validateJsonSchema<T>(schema: object, data: T, options?: {
+        safe?: boolean;
+    }): T | z.SafeParseReturnType<T, T>;
 }
 /**
  * Input message format for ChatModel

package/lib/cjs/agents/chat-model.js

@@ -35,8 +35,9 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.chatModelOutputUsageSchema = exports.unionContentSchema = exports.textContentSchema = exports.roleSchema = exports.ChatModel = exports.StructuredOutputError = void 0;
 const index_js_1 = require("@aigne/platform-helpers/nodejs/index.js");
-const ajv_1 = require("ajv");
 const zod_1 = require("zod");
+const zod_from_json_schema_1 = require("zod-from-json-schema");
+const json_schema_js_1 = require("../utils/json-schema.js");
 const type_utils_js_1 = require("../utils/type-utils.js");
 const agent_js_1 = require("./agent.js");
 const model_js_1 = require("./model.js");
@@ -213,19 +214,6 @@ class ChatModel extends model_js_1.Model {
      * @param options Options for invoking the agent
      */
     async postprocess(input, output, options) {
-        // Restore original tool names in the output
-        if (output.toolCalls?.length) {
-            const toolsMap = input._toolsMap;
-            if (toolsMap) {
-                for (const toolCall of output.toolCalls) {
-                    const originalTool = toolsMap[toolCall.function.name];
-                    if (!originalTool) {
-                        throw new Error(`Tool "${toolCall.function.name}" not found in tools map`);
-                    }
-                    toolCall.function.name = originalTool.function.name;
-                }
-            }
-        }
         super.postprocess(input, output, options);
         const { usage } = output;
         if (usage) {
@@ -245,16 +233,38 @@ class ChatModel extends model_js_1.Model {
         }
         // Remove fields with `null` value for validation
         output = (0, type_utils_js_1.omitByDeep)(output, (value) => (0, type_utils_js_1.isNil)(value));
+        const toolCalls = output.toolCalls;
         if (input.responseFormat?.type === "json_schema" &&
             // NOTE: Should not validate if there are tool calls
-            !output.toolCalls?.length) {
-            const ajv = new ajv_1.Ajv();
-            if (!ajv.validate(input.responseFormat.jsonSchema.schema, output.json)) {
-                throw new StructuredOutputError(`Output JSON does not conform to the provided JSON schema: ${ajv.errorsText()}`);
+            !toolCalls?.length) {
+            output.json = this.validateJsonSchema(input.responseFormat.jsonSchema.schema, output.json);
+        }
+        // Restore original tool names in the output
+        if (toolCalls?.length) {
+            const toolsMap = input._toolsMap;
+            if (toolsMap) {
+                for (const toolCall of toolCalls) {
+                    const originalTool = toolsMap[toolCall.function.name];
+                    if (!originalTool) {
+                        throw new Error(`Tool "${toolCall.function.name}" not found in tools map`);
+                    }
+                    toolCall.function.name = originalTool.function.name;
+                    toolCall.function.arguments = this.validateJsonSchema(originalTool.function.parameters, toolCall.function.arguments);
+                }
             }
         }
         return super.processAgentOutput(input, output, options);
     }
+    validateJsonSchema(schema, data, options) {
+        const s = (0, json_schema_js_1.wrapAutoParseJsonSchema)((0, zod_from_json_schema_1.convertJsonSchemaToZod)(schema));
+        const r = s.safeParse(data);
+        if (options?.safe)
+            return r;
+        if (r.error) {
+            throw new StructuredOutputError(`Output JSON does not conform to the provided JSON schema: ${r.error.errors.map((i) => `${i.path}: ${i.message}`).join(", ")}`);
+        }
+        return r.data;
+    }
 }
 exports.ChatModel = ChatModel;
 exports.roleSchema = zod_1.z.union([

package/lib/cjs/utils/json-schema.d.ts

@@ -1,4 +1,4 @@
-import type { ZodType, z } from "zod";
+import { type ZodType, z } from "zod";
 import type { Message } from "../agents/agent.js";
 export declare function outputSchemaToResponseFormatSchema(agentOutput: ZodType<Message>): Record<string, unknown>;
 export declare function parseJSON(json: string): any;
@@ -11,3 +11,4 @@ export declare function parseJSON(json: string): any;
  */
 export declare function ensureZodUnionArray<T extends z.ZodType>(union: T[]): [T, T, ...T[]];
 export declare function isZodSchema(schema: ZodType): schema is ZodType;
+export declare const wrapAutoParseJsonSchema: <T extends ZodType>(schema: T) => T;

package/lib/cjs/utils/json-schema.js

@@ -1,10 +1,13 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.wrapAutoParseJsonSchema = void 0;
 exports.outputSchemaToResponseFormatSchema = outputSchemaToResponseFormatSchema;
 exports.parseJSON = parseJSON;
 exports.ensureZodUnionArray = ensureZodUnionArray;
 exports.isZodSchema = isZodSchema;
+const zod_1 = require("zod");
 const zod_to_json_schema_1 = require("zod-to-json-schema");
+const json_utils_js_1 = require("./json-utils.js");
 const logger_js_1 = require("./logger.js");
 const type_utils_js_1 = require("./type-utils.js");
 function outputSchemaToResponseFormatSchema(agentOutput) {
@@ -90,3 +93,25 @@ function convertNullableToOptional(schema) {
     }
     return [schema, false];
 }
+const wrapJsonParse = (schema) => {
+    return zod_1.z.preprocess((val) => (typeof val === "string" ? (0, json_utils_js_1.safeParseJSON)(val) : val), schema);
+};
+const wrapAutoParseJsonSchema = (schema) => {
+    if (schema instanceof zod_1.z.ZodNullable)
+        return zod_1.z.nullable((0, exports.wrapAutoParseJsonSchema)(schema._def.innerType));
+    if (schema instanceof zod_1.z.ZodOptional)
+        return zod_1.z.optional((0, exports.wrapAutoParseJsonSchema)(schema._def.innerType));
+    if (schema instanceof zod_1.z.ZodObject) {
+        const newSchema = schema.extend(Object.fromEntries(Object.entries(schema.shape).map(([key, value]) => [
+            key,
+            (0, exports.wrapAutoParseJsonSchema)(value),
+        ])));
+        return wrapJsonParse(newSchema);
+    }
+    if (schema instanceof zod_1.z.ZodArray) {
+        schema._def.type = (0, exports.wrapAutoParseJsonSchema)(schema._def.type);
+        return wrapJsonParse(schema);
+    }
+    return schema;
+};
+exports.wrapAutoParseJsonSchema = wrapAutoParseJsonSchema;

package/lib/dts/agents/chat-model.d.ts

@@ -111,6 +111,15 @@ export declare abstract class ChatModel extends Model<ChatModelInput, ChatModelO
      */
     abstract process(input: ChatModelInput, options: AgentInvokeOptions): PromiseOrValue<AgentProcessResult<ChatModelOutput>>;
     protected processAgentOutput(input: ChatModelInput, output: Exclude<AgentResponse<ChatModelOutput>, AgentResponseStream<ChatModelOutput>>, options: AgentInvokeOptions): Promise<ChatModelOutput>;
+    protected validateJsonSchema<T>(schema: object, data: T, options?: {
+        safe?: false;
+    }): T;
+    protected validateJsonSchema<T>(schema: object, data: T, options: {
+        safe: true;
+    }): z.SafeParseReturnType<T, T>;
+    protected validateJsonSchema<T>(schema: object, data: T, options?: {
+        safe?: boolean;
+    }): T | z.SafeParseReturnType<T, T>;
 }
 /**
  * Input message format for ChatModel

package/lib/dts/utils/json-schema.d.ts

@@ -1,4 +1,4 @@
-import type { ZodType, z } from "zod";
+import { type ZodType, z } from "zod";
 import type { Message } from "../agents/agent.js";
 export declare function outputSchemaToResponseFormatSchema(agentOutput: ZodType<Message>): Record<string, unknown>;
 export declare function parseJSON(json: string): any;
@@ -11,3 +11,4 @@ export declare function parseJSON(json: string): any;
  */
 export declare function ensureZodUnionArray<T extends z.ZodType>(union: T[]): [T, T, ...T[]];
 export declare function isZodSchema(schema: ZodType): schema is ZodType;
+export declare const wrapAutoParseJsonSchema: <T extends ZodType>(schema: T) => T;

package/lib/esm/agents/chat-model.d.ts

@@ -111,6 +111,15 @@ export declare abstract class ChatModel extends Model<ChatModelInput, ChatModelO
      */
     abstract process(input: ChatModelInput, options: AgentInvokeOptions): PromiseOrValue<AgentProcessResult<ChatModelOutput>>;
     protected processAgentOutput(input: ChatModelInput, output: Exclude<AgentResponse<ChatModelOutput>, AgentResponseStream<ChatModelOutput>>, options: AgentInvokeOptions): Promise<ChatModelOutput>;
+    protected validateJsonSchema<T>(schema: object, data: T, options?: {
+        safe?: false;
+    }): T;
+    protected validateJsonSchema<T>(schema: object, data: T, options: {
+        safe: true;
+    }): z.SafeParseReturnType<T, T>;
+    protected validateJsonSchema<T>(schema: object, data: T, options?: {
+        safe?: boolean;
+    }): T | z.SafeParseReturnType<T, T>;
 }
 /**
  * Input message format for ChatModel

package/lib/esm/agents/chat-model.js

@@ -1,6 +1,7 @@
 import { nodejs } from "@aigne/platform-helpers/nodejs/index.js";
-import { Ajv } from "ajv";
 import { z } from "zod";
+import { convertJsonSchemaToZod } from "zod-from-json-schema";
+import { wrapAutoParseJsonSchema } from "../utils/json-schema.js";
 import { checkArguments, isNil, omitByDeep } from "../utils/type-utils.js";
 import { agentOptionsSchema, } from "./agent.js";
 import { fileContentSchema, fileUnionContentSchema, localContentSchema, Model, urlContentSchema, } from "./model.js";
@@ -176,19 +177,6 @@ export class ChatModel extends Model {
      * @param options Options for invoking the agent
      */
     async postprocess(input, output, options) {
-        // Restore original tool names in the output
-        if (output.toolCalls?.length) {
-            const toolsMap = input._toolsMap;
-            if (toolsMap) {
-                for (const toolCall of output.toolCalls) {
-                    const originalTool = toolsMap[toolCall.function.name];
-                    if (!originalTool) {
-                        throw new Error(`Tool "${toolCall.function.name}" not found in tools map`);
-                    }
-                    toolCall.function.name = originalTool.function.name;
-                }
-            }
-        }
         super.postprocess(input, output, options);
         const { usage } = output;
         if (usage) {
@@ -208,16 +196,38 @@ export class ChatModel extends Model {
         }
         // Remove fields with `null` value for validation
         output = omitByDeep(output, (value) => isNil(value));
+        const toolCalls = output.toolCalls;
         if (input.responseFormat?.type === "json_schema" &&
             // NOTE: Should not validate if there are tool calls
-            !output.toolCalls?.length) {
-            const ajv = new Ajv();
-            if (!ajv.validate(input.responseFormat.jsonSchema.schema, output.json)) {
-                throw new StructuredOutputError(`Output JSON does not conform to the provided JSON schema: ${ajv.errorsText()}`);
+            !toolCalls?.length) {
+            output.json = this.validateJsonSchema(input.responseFormat.jsonSchema.schema, output.json);
+        }
+        // Restore original tool names in the output
+        if (toolCalls?.length) {
+            const toolsMap = input._toolsMap;
+            if (toolsMap) {
+                for (const toolCall of toolCalls) {
+                    const originalTool = toolsMap[toolCall.function.name];
+                    if (!originalTool) {
+                        throw new Error(`Tool "${toolCall.function.name}" not found in tools map`);
+                    }
+                    toolCall.function.name = originalTool.function.name;
+                    toolCall.function.arguments = this.validateJsonSchema(originalTool.function.parameters, toolCall.function.arguments);
+                }
             }
         }
         return super.processAgentOutput(input, output, options);
     }
+    validateJsonSchema(schema, data, options) {
+        const s = wrapAutoParseJsonSchema(convertJsonSchemaToZod(schema));
+        const r = s.safeParse(data);
+        if (options?.safe)
+            return r;
+        if (r.error) {
+            throw new StructuredOutputError(`Output JSON does not conform to the provided JSON schema: ${r.error.errors.map((i) => `${i.path}: ${i.message}`).join(", ")}`);
+        }
+        return r.data;
+    }
 }
 export const roleSchema = z.union([
     z.literal("system"),

package/lib/esm/utils/json-schema.d.ts

@@ -1,4 +1,4 @@
-import type { ZodType, z } from "zod";
+import { type ZodType, z } from "zod";
 import type { Message } from "../agents/agent.js";
 export declare function outputSchemaToResponseFormatSchema(agentOutput: ZodType<Message>): Record<string, unknown>;
 export declare function parseJSON(json: string): any;
@@ -11,3 +11,4 @@ export declare function parseJSON(json: string): any;
  */
 export declare function ensureZodUnionArray<T extends z.ZodType>(union: T[]): [T, T, ...T[]];
 export declare function isZodSchema(schema: ZodType): schema is ZodType;
+export declare const wrapAutoParseJsonSchema: <T extends ZodType>(schema: T) => T;

package/lib/esm/utils/json-schema.js

@@ -1,4 +1,6 @@
+import { z } from "zod";
 import { zodToJsonSchema } from "zod-to-json-schema";
+import { safeParseJSON } from "./json-utils.js";
 import { logger } from "./logger.js";
 import { isEmpty, isRecord } from "./type-utils.js";
 export function outputSchemaToResponseFormatSchema(agentOutput) {
@@ -84,3 +86,24 @@ function convertNullableToOptional(schema) {
     }
     return [schema, false];
 }
+const wrapJsonParse = (schema) => {
+    return z.preprocess((val) => (typeof val === "string" ? safeParseJSON(val) : val), schema);
+};
+export const wrapAutoParseJsonSchema = (schema) => {
+    if (schema instanceof z.ZodNullable)
+        return z.nullable(wrapAutoParseJsonSchema(schema._def.innerType));
+    if (schema instanceof z.ZodOptional)
+        return z.optional(wrapAutoParseJsonSchema(schema._def.innerType));
+    if (schema instanceof z.ZodObject) {
+        const newSchema = schema.extend(Object.fromEntries(Object.entries(schema.shape).map(([key, value]) => [
+            key,
+            wrapAutoParseJsonSchema(value),
+        ])));
+        return wrapJsonParse(newSchema);
+    }
+    if (schema instanceof z.ZodArray) {
+        schema._def.type = wrapAutoParseJsonSchema(schema._def.type);
+        return wrapJsonParse(schema);
+    }
+    return schema;
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aigne/core",
-  "version": "1.61.0-beta.3",
+  "version": "1.61.0-beta.5",
   "description": "The functional core of agentic AI",
   "publishConfig": {
     "access": "public"
@@ -71,7 +71,6 @@
     "@opentelemetry/api": "^1.9.0",
     "@opentelemetry/sdk-trace-base": "^2.1.0",
     "@types/debug": "^4.1.12",
-    "ajv": "^8.17.1",
     "camelize-ts": "^3.0.0",
     "content-type": "^1.0.5",
     "debug": "^4.4.3",
@@ -91,8 +90,9 @@
     "uuid": "^13.0.0",
     "yaml": "^2.8.1",
     "zod": "^3.25.67",
+    "zod-from-json-schema": "^0.0.5",
     "zod-to-json-schema": "^3.24.6",
-    "@aigne/observability-api": "^0.10.4",
+    "@aigne/observability-api": "^0.11.0-beta",
     "@aigne/platform-helpers": "^0.6.3-beta"
   },
   "devDependencies": {