@aigne/core 1.55.1 → 1.56.0

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [1.56.0](https://github.com/AIGNE-io/aigne-framework/compare/core-v1.55.1...core-v1.56.0) (2025-08-27)
+
+
+### Features
+
+* **models:** add retry mechanism for network errors and structured output validation errors ([#418](https://github.com/AIGNE-io/aigne-framework/issues/418)) ([52bc9ee](https://github.com/AIGNE-io/aigne-framework/commit/52bc9eec5f4f4fa3c3f26881c405f4f89dad01c9))
+
 ## [1.55.1](https://github.com/AIGNE-io/aigne-framework/compare/core-v1.55.0...core-v1.55.1) (2025-08-26)
 
 

package/lib/cjs/agents/agent.d.ts

@@ -122,6 +122,7 @@ export interface AgentOptions<I extends Message = Message, O extends Message = M
      */
     maxRetrieveMemoryCount?: number;
     hooks?: AgentHooks<I, O> | AgentHooks<I, O>[];
+    retryOnError?: Agent<I, O>["retryOnError"] | boolean;
 }
 export declare const agentOptionsSchema: ZodObject<{
     [key in keyof AgentOptions]: ZodType<AgentOptions[key]>;
@@ -217,6 +218,13 @@ export declare abstract class Agent<I extends Message = any, O extends Message =
      * {@includeCode ../../test/agents/agent.test.ts#example-agent-hooks}
      */
     readonly hooks: AgentHooks<I, O>[];
+    retryOnError?: {
+        retries?: number;
+        minTimeout?: number;
+        factor?: number;
+        randomize?: boolean;
+        shouldRetry?: (error: Error) => boolean | Promise<boolean>;
+    };
     /**
      * List of GuideRail agents applied to this agent
      *

package/lib/cjs/agents/agent.js

@@ -57,6 +57,9 @@ const type_utils_js_1 = require("../utils/type-utils.js");
 const types_js_1 = require("./types.js");
 __exportStar(require("./types.js"), exports);
 exports.DEFAULT_INPUT_ACTION_GET = "$get";
+const DEFAULT_RETRIES = 3;
+const DEFAULT_RETRY_MIN_TIMEOUT = 1000;
+const DEFAULT_RETRY_FACTOR = 2;
 const hooksSchema = zod_1.z.object({
     onStart: zod_1.z.custom().optional(),
     onEnd: zod_1.z.custom().optional(),
@@ -82,6 +85,18 @@ exports.agentOptionsSchema = zod_1.z.object({
     maxRetrieveMemoryCount: zod_1.z.number().optional(),
     hooks: zod_1.z.union([zod_1.z.array(hooksSchema), hooksSchema]).optional(),
     guideRails: zod_1.z.array(zod_1.z.custom()).optional(),
+    retryOnError: zod_1.z
+        .union([
+        zod_1.z.boolean(),
+        zod_1.z.object({
+            retries: zod_1.z.number().int().min(0),
+            minTimeout: zod_1.z.number().min(0).optional(),
+            factor: zod_1.z.number().min(1).optional(),
+            randomize: zod_1.z.boolean().optional(),
+            shouldRetry: zod_1.z.custom().optional(),
+        }),
+    ])
+        .optional(),
 });
 /**
  * Agent is the base class for all agents.
@@ -107,6 +122,7 @@ exports.agentOptionsSchema = zod_1.z.object({
  */
 class Agent {
     constructor(options = {}) {
+        (0, type_utils_js_1.checkArguments)("Agent options", exports.agentOptionsSchema, options);
         const { inputSchema, outputSchema } = options;
         this.name = options.name || this.constructor.name;
         this.alias = options.alias;
@@ -135,6 +151,12 @@ class Agent {
         this.asyncMemoryRecord = options.asyncMemoryRecord;
         this.maxRetrieveMemoryCount = options.maxRetrieveMemoryCount;
         this.hooks = (0, type_utils_js_1.flat)(options.hooks);
+        this.retryOnError =
+            options.retryOnError === false
+                ? undefined
+                : options.retryOnError === true
+                    ? { retries: DEFAULT_RETRIES }
+                    : options.retryOnError;
         this.guideRails = options.guideRails;
     }
     /**
@@ -158,6 +180,7 @@ class Agent {
      * {@includeCode ../../test/agents/agent.test.ts#example-agent-hooks}
      */
     hooks;
+    retryOnError;
     /**
      * List of GuideRail agents applied to this agent
      *
@@ -387,6 +410,7 @@ class Agent {
     }
     async *processStreamingAndRetry(input, options) {
         let output = {};
+        let attempt = 0;
         for (;;) {
             // Reset output to avoid accumulating old data
             const resetOutput = Object.fromEntries(Object.entries(output).map(([key]) => [key, null]));
@@ -415,6 +439,15 @@ class Agent {
                 break;
             }
             catch (error) {
+                if (this.retryOnError?.retries) {
+                    const { retries, minTimeout = DEFAULT_RETRY_MIN_TIMEOUT, factor = DEFAULT_RETRY_FACTOR, randomize = false, shouldRetry, } = this.retryOnError;
+                    if (attempt++ < retries && (!shouldRetry || (await shouldRetry(error)))) {
+                        const timeout = minTimeout * factor ** (attempt - 1) * (randomize ? 1 + Math.random() : 1);
+                        logger_js_1.logger.warn(`Agent ${this.name} attempt ${attempt} of ${retries} failed with error: ${error}. Retrying in ${timeout}ms...`);
+                        await new Promise((resolve) => setTimeout(resolve, timeout));
+                        continue;
+                    }
+                }
                 const res = await this.processAgentError(input, error, options);
                 if (!res.retry)
                     throw res.error ?? error;

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

@@ -1,6 +1,8 @@
 import { z } from "zod";
-import type { PromiseOrValue } from "../utils/type-utils.js";
+import { type PromiseOrValue } from "../utils/type-utils.js";
 import { Agent, type AgentInvokeOptions, type AgentOptions, type AgentProcessResult, type Message } from "./agent.js";
+export declare class StructuredOutputError extends Error {
+}
 /**
  * ChatModel is an abstract base class for interacting with Large Language Models (LLMs).
  *

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

@@ -1,8 +1,21 @@
 "use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.chatModelOutputUsageSchema = exports.ChatModel = void 0;
+exports.chatModelOutputUsageSchema = exports.ChatModel = exports.StructuredOutputError = void 0;
+const ajv_1 = require("ajv");
+const is_network_error_1 = __importDefault(require("is-network-error"));
 const zod_1 = require("zod");
+const type_utils_js_1 = require("../utils/type-utils.js");
 const agent_js_1 = require("./agent.js");
+const CHAT_MODEL_DEFAULT_RETRY_OPTIONS = {
+    retries: 3,
+    shouldRetry: (error) => error instanceof StructuredOutputError || (0, is_network_error_1.default)(error),
+};
+class StructuredOutputError extends Error {
+}
+exports.StructuredOutputError = StructuredOutputError;
 /**
  * ChatModel is an abstract base class for interacting with Large Language Models (LLMs).
  *
@@ -29,10 +42,21 @@ const agent_js_1 = require("./agent.js");
 class ChatModel extends agent_js_1.Agent {
     tag = "ChatModelAgent";
     constructor(options) {
+        if (options)
+            (0, type_utils_js_1.checkArguments)("ChatModel", agent_js_1.agentOptionsSchema, options);
+        const retryOnError = options?.retryOnError === false
+            ? false
+            : options?.retryOnError === true
+                ? CHAT_MODEL_DEFAULT_RETRY_OPTIONS
+                : {
+                    ...CHAT_MODEL_DEFAULT_RETRY_OPTIONS,
+                    ...options?.retryOnError,
+                };
         super({
             ...options,
             inputSchema: chatModelInputSchema,
             outputSchema: chatModelOutputSchema,
+            retryOnError,
         });
     }
     get credential() {
@@ -137,6 +161,14 @@ class ChatModel extends agent_js_1.Agent {
                 }
             }
         }
+        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()}`);
+            }
+        }
         super.postprocess(input, output, options);
         const { usage } = output;
         if (usage) {

package/lib/dts/agents/agent.d.ts

@@ -122,6 +122,7 @@ export interface AgentOptions<I extends Message = Message, O extends Message = M
      */
     maxRetrieveMemoryCount?: number;
     hooks?: AgentHooks<I, O> | AgentHooks<I, O>[];
+    retryOnError?: Agent<I, O>["retryOnError"] | boolean;
 }
 export declare const agentOptionsSchema: ZodObject<{
     [key in keyof AgentOptions]: ZodType<AgentOptions[key]>;
@@ -217,6 +218,13 @@ export declare abstract class Agent<I extends Message = any, O extends Message =
      * {@includeCode ../../test/agents/agent.test.ts#example-agent-hooks}
      */
     readonly hooks: AgentHooks<I, O>[];
+    retryOnError?: {
+        retries?: number;
+        minTimeout?: number;
+        factor?: number;
+        randomize?: boolean;
+        shouldRetry?: (error: Error) => boolean | Promise<boolean>;
+    };
     /**
      * List of GuideRail agents applied to this agent
      *

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

@@ -1,6 +1,8 @@
 import { z } from "zod";
-import type { PromiseOrValue } from "../utils/type-utils.js";
+import { type PromiseOrValue } from "../utils/type-utils.js";
 import { Agent, type AgentInvokeOptions, type AgentOptions, type AgentProcessResult, type Message } from "./agent.js";
+export declare class StructuredOutputError extends Error {
+}
 /**
  * ChatModel is an abstract base class for interacting with Large Language Models (LLMs).
  *

package/lib/esm/agents/agent.d.ts

@@ -122,6 +122,7 @@ export interface AgentOptions<I extends Message = Message, O extends Message = M
      */
     maxRetrieveMemoryCount?: number;
     hooks?: AgentHooks<I, O> | AgentHooks<I, O>[];
+    retryOnError?: Agent<I, O>["retryOnError"] | boolean;
 }
 export declare const agentOptionsSchema: ZodObject<{
     [key in keyof AgentOptions]: ZodType<AgentOptions[key]>;
@@ -217,6 +218,13 @@ export declare abstract class Agent<I extends Message = any, O extends Message =
      * {@includeCode ../../test/agents/agent.test.ts#example-agent-hooks}
      */
     readonly hooks: AgentHooks<I, O>[];
+    retryOnError?: {
+        retries?: number;
+        minTimeout?: number;
+        factor?: number;
+        randomize?: boolean;
+        shouldRetry?: (error: Error) => boolean | Promise<boolean>;
+    };
     /**
      * List of GuideRail agents applied to this agent
      *

package/lib/esm/agents/agent.js

@@ -9,6 +9,9 @@ import { checkArguments, createAccessorArray, flat, isEmpty, isNil, isNonNullabl
 import { replaceTransferAgentToName, transferToAgentOutput, } from "./types.js";
 export * from "./types.js";
 export const DEFAULT_INPUT_ACTION_GET = "$get";
+const DEFAULT_RETRIES = 3;
+const DEFAULT_RETRY_MIN_TIMEOUT = 1000;
+const DEFAULT_RETRY_FACTOR = 2;
 const hooksSchema = z.object({
     onStart: z.custom().optional(),
     onEnd: z.custom().optional(),
@@ -34,6 +37,18 @@ export const agentOptionsSchema = z.object({
     maxRetrieveMemoryCount: z.number().optional(),
     hooks: z.union([z.array(hooksSchema), hooksSchema]).optional(),
     guideRails: z.array(z.custom()).optional(),
+    retryOnError: z
+        .union([
+        z.boolean(),
+        z.object({
+            retries: z.number().int().min(0),
+            minTimeout: z.number().min(0).optional(),
+            factor: z.number().min(1).optional(),
+            randomize: z.boolean().optional(),
+            shouldRetry: z.custom().optional(),
+        }),
+    ])
+        .optional(),
 });
 /**
  * Agent is the base class for all agents.
@@ -59,6 +74,7 @@ export const agentOptionsSchema = z.object({
  */
 export class Agent {
     constructor(options = {}) {
+        checkArguments("Agent options", agentOptionsSchema, options);
         const { inputSchema, outputSchema } = options;
         this.name = options.name || this.constructor.name;
         this.alias = options.alias;
@@ -87,6 +103,12 @@ export class Agent {
         this.asyncMemoryRecord = options.asyncMemoryRecord;
         this.maxRetrieveMemoryCount = options.maxRetrieveMemoryCount;
         this.hooks = flat(options.hooks);
+        this.retryOnError =
+            options.retryOnError === false
+                ? undefined
+                : options.retryOnError === true
+                    ? { retries: DEFAULT_RETRIES }
+                    : options.retryOnError;
         this.guideRails = options.guideRails;
     }
     /**
@@ -110,6 +132,7 @@ export class Agent {
      * {@includeCode ../../test/agents/agent.test.ts#example-agent-hooks}
      */
     hooks;
+    retryOnError;
     /**
      * List of GuideRail agents applied to this agent
      *
@@ -339,6 +362,7 @@ export class Agent {
     }
     async *processStreamingAndRetry(input, options) {
         let output = {};
+        let attempt = 0;
         for (;;) {
             // Reset output to avoid accumulating old data
             const resetOutput = Object.fromEntries(Object.entries(output).map(([key]) => [key, null]));
@@ -367,6 +391,15 @@ export class Agent {
                 break;
             }
             catch (error) {
+                if (this.retryOnError?.retries) {
+                    const { retries, minTimeout = DEFAULT_RETRY_MIN_TIMEOUT, factor = DEFAULT_RETRY_FACTOR, randomize = false, shouldRetry, } = this.retryOnError;
+                    if (attempt++ < retries && (!shouldRetry || (await shouldRetry(error)))) {
+                        const timeout = minTimeout * factor ** (attempt - 1) * (randomize ? 1 + Math.random() : 1);
+                        logger.warn(`Agent ${this.name} attempt ${attempt} of ${retries} failed with error: ${error}. Retrying in ${timeout}ms...`);
+                        await new Promise((resolve) => setTimeout(resolve, timeout));
+                        continue;
+                    }
+                }
                 const res = await this.processAgentError(input, error, options);
                 if (!res.retry)
                     throw res.error ?? error;

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

@@ -1,6 +1,8 @@
 import { z } from "zod";
-import type { PromiseOrValue } from "../utils/type-utils.js";
+import { type PromiseOrValue } from "../utils/type-utils.js";
 import { Agent, type AgentInvokeOptions, type AgentOptions, type AgentProcessResult, type Message } from "./agent.js";
+export declare class StructuredOutputError extends Error {
+}
 /**
  * ChatModel is an abstract base class for interacting with Large Language Models (LLMs).
  *

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

@@ -1,5 +1,14 @@
+import { Ajv } from "ajv";
+import isNetworkError from "is-network-error";
 import { z } from "zod";
-import { Agent, } from "./agent.js";
+import { checkArguments } from "../utils/type-utils.js";
+import { Agent, agentOptionsSchema, } from "./agent.js";
+const CHAT_MODEL_DEFAULT_RETRY_OPTIONS = {
+    retries: 3,
+    shouldRetry: (error) => error instanceof StructuredOutputError || isNetworkError(error),
+};
+export class StructuredOutputError extends Error {
+}
 /**
  * ChatModel is an abstract base class for interacting with Large Language Models (LLMs).
  *
@@ -26,10 +35,21 @@ import { Agent, } from "./agent.js";
 export class ChatModel extends Agent {
     tag = "ChatModelAgent";
     constructor(options) {
+        if (options)
+            checkArguments("ChatModel", agentOptionsSchema, options);
+        const retryOnError = options?.retryOnError === false
+            ? false
+            : options?.retryOnError === true
+                ? CHAT_MODEL_DEFAULT_RETRY_OPTIONS
+                : {
+                    ...CHAT_MODEL_DEFAULT_RETRY_OPTIONS,
+                    ...options?.retryOnError,
+                };
         super({
             ...options,
             inputSchema: chatModelInputSchema,
             outputSchema: chatModelOutputSchema,
+            retryOnError,
         });
     }
     get credential() {
@@ -134,6 +154,14 @@ export class ChatModel extends Agent {
                 }
             }
         }
+        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()}`);
+            }
+        }
         super.postprocess(input, output, options);
         const { usage } = output;
         if (usage) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aigne/core",
-  "version": "1.55.1",
+  "version": "1.56.0",
   "description": "The functional core of agentic AI",
   "publishConfig": {
     "access": "public"
@@ -71,6 +71,7 @@
     "@opentelemetry/api": "^1.9.0",
     "@opentelemetry/sdk-trace-base": "^2.0.1",
     "@types/debug": "^4.1.12",
+    "ajv": "^8.17.1",
     "camelize-ts": "^3.0.0",
     "content-type": "^1.0.5",
     "debug": "^4.4.1",
@@ -78,6 +79,7 @@
     "fast-deep-equal": "^3.1.3",
     "fastq": "^1.19.1",
     "immer": "^10.1.1",
+    "is-network-error": "^1.1.0",
     "jaison": "^2.0.2",
     "jsonata": "^2.0.6",
     "nunjucks": "^3.2.4",