@aigne/core 1.36.0 → 1.37.0

package/CHANGELOG.md

@@ -12,6 +12,18 @@
   * dependencies
     * @aigne/observability bumped to 0.1.0
 
+## [1.37.0](https://github.com/AIGNE-io/aigne-framework/compare/core-v1.36.0...core-v1.37.0) (2025-07-22)
+
+
+### Features
+
+* **core:** add reflection mode support to TeamAgent ([#273](https://github.com/AIGNE-io/aigne-framework/issues/273)) ([4e2dad6](https://github.com/AIGNE-io/aigne-framework/commit/4e2dad687c1caefa231c7a7620651d060f8c8b9d))
+
+
+### Bug Fixes
+
+* **core:** function agent should use common schema from yaml definition ([#270](https://github.com/AIGNE-io/aigne-framework/issues/270)) ([076a489](https://github.com/AIGNE-io/aigne-framework/commit/076a4896948c397518e99df46c1a443ea43daa64))
+
 ## [1.36.0](https://github.com/AIGNE-io/aigne-framework/compare/core-v1.35.0...core-v1.36.0) (2025-07-17)
 
 

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

@@ -22,6 +22,73 @@ export declare enum ProcessMode {
      */
     parallel = "parallel"
 }
+export declare const DEFAULT_REFLECTION_MAX_ITERATIONS = 3;
+/**
+ * Configuration for reflection mode processing in TeamAgent.
+ *
+ * Reflection mode enables iterative refinement of agent outputs through a review process.
+ * The team agent will repeatedly process the input and have a reviewer agent evaluate
+ * the output until it meets approval criteria or reaches the maximum iteration limit.
+ *
+ * This is particularly useful for:
+ * - Quality assurance workflows where outputs need validation
+ * - Iterative improvement processes where initial results can be refined
+ * - Self-correcting agent systems that learn from feedback
+ */
+export interface ReflectionMode {
+    /**
+     * The agent responsible for reviewing and providing feedback on the team's output.
+     *
+     * The reviewer agent receives the combined output from the team's processing
+     * and should provide feedback or evaluation that can be used to determine
+     * whether the output meets the required standards.
+     */
+    reviewer: Agent;
+    /**
+     * Function that determines whether the reviewer's output indicates approval.
+     *
+     * This function receives the reviewer agent's output message and should return:
+     * - `true` or truthy value: The output is approved and processing should stop
+     * - `false` or falsy value: The output needs improvement and another iteration should run
+     *
+     * The function can be synchronous or asynchronous, allowing for complex approval logic
+     * including external validation, scoring systems, or human-in-the-loop approval.
+     *
+     * @param output - The message output from the reviewer agent
+     * @returns A boolean or truthy/falsy value indicating approval status
+     */
+    isApproved: (output: Message) => PromiseOrValue<boolean | unknown>;
+    /**
+     * Maximum number of reflection iterations before giving up.
+     *
+     * This prevents infinite loops when the approval criteria cannot be met.
+     * If the maximum iterations are reached without approval, the process will
+     * throw an error indicating the reflection failed to converge.
+     *
+     * @default 3
+     */
+    maxIterations?: number;
+    /**
+     * Controls the behavior when maximum iterations are reached without approval.
+     *
+     * When set to `true`, the TeamAgent will return the last generated output
+     * instead of throwing an error when the maximum number of reflection iterations
+     * is reached without the reviewer's approval.
+     *
+     * When set to `false` or undefined, the TeamAgent will throw an error
+     * indicating that the reflection process failed to converge within the
+     * maximum iteration limit.
+     *
+     * This option is useful for scenarios where:
+     * - You want to get the best available result even if it's not perfect
+     * - The approval criteria might be too strict for the given context
+     * - You prefer graceful degradation over complete failure
+     * - You want to implement custom error handling based on the returned result
+     *
+     * @default false
+     */
+    returnLastOnMaxIterations?: boolean;
+}
 /**
  * Configuration options for creating a TeamAgent.
  *
@@ -33,6 +100,21 @@ export interface TeamAgentOptions<I extends Message, O extends Message> extends
      * @default {ProcessMode.sequential}
      */
     mode?: ProcessMode;
+    /**
+     * Configuration for reflection mode processing.
+     *
+     * When enabled, the TeamAgent will use an iterative refinement process where:
+     * 1. The team processes the input normally
+     * 2. A reviewer agent evaluates the output
+     * 3. If not approved, the process repeats with the previous output as context
+     * 4. This continues until approval or maximum iterations are reached
+     *
+     * This enables self-improving agent workflows that can iteratively refine
+     * their outputs based on feedback from a specialized reviewer agent.
+     *
+     * @see ReflectionMode for detailed configuration options
+     */
+    reflection?: ReflectionMode;
     /**
      * Specifies which input field should be treated as an array for iterative processing.
      *
@@ -116,6 +198,14 @@ export declare class TeamAgent<I extends Message, O extends Message> extends Age
      * This can be either sequential (one after another) or parallel (all at once).
      */
     mode: ProcessMode;
+    /**
+     * The reflection mode configuration with guaranteed maxIterations value.
+     *
+     * This is the internal representation after processing the user-provided
+     * reflection configuration, ensuring that maxIterations always has a value
+     * (defaulting to DEFAULT_REFLECTION_MAX_ITERATIONS if not specified).
+     */
+    reflection?: ReflectionMode & Required<Pick<ReflectionMode, "maxIterations">>;
     /**
      * The input field key to iterate over when processing array inputs.
      *
@@ -148,8 +238,10 @@ export declare class TeamAgent<I extends Message, O extends Message> extends Age
      * @returns A stream of message chunks that collectively form the response
      */
     process(input: I, options: AgentInvokeOptions): PromiseOrValue<AgentProcessResult<O>>;
+    private _processNonReflection;
+    private _processReflection;
     private _processIterator;
-    private _process;
+    private _processNonIterator;
     /**
      * Process input sequentially through each agent in the team.
      *

package/lib/cjs/agents/team-agent.js

@@ -3,7 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.TeamAgent = exports.ProcessMode = void 0;
+exports.TeamAgent = exports.DEFAULT_REFLECTION_MAX_ITERATIONS = exports.ProcessMode = void 0;
 const node_assert_1 = __importDefault(require("node:assert"));
 const immer_1 = require("immer");
 const stream_utils_js_1 = require("../utils/stream-utils.js");
@@ -32,6 +32,7 @@ var ProcessMode;
      */
     ProcessMode["parallel"] = "parallel";
 })(ProcessMode || (exports.ProcessMode = ProcessMode = {}));
+exports.DEFAULT_REFLECTION_MAX_ITERATIONS = 3;
 /**
  * TeamAgent coordinates a group of agents working together to accomplish tasks.
  *
@@ -76,6 +77,10 @@ class TeamAgent extends agent_js_1.Agent {
     constructor(options) {
         super(options);
         this.mode = options.mode ?? ProcessMode.sequential;
+        this.reflection = options.reflection && {
+            ...options.reflection,
+            maxIterations: options.reflection.maxIterations ?? exports.DEFAULT_REFLECTION_MAX_ITERATIONS,
+        };
         this.iterateOn = options.iterateOn;
         this.iterateWithPreviousOutput = options.iterateWithPreviousOutput;
     }
@@ -85,6 +90,14 @@ class TeamAgent extends agent_js_1.Agent {
      * This can be either sequential (one after another) or parallel (all at once).
      */
     mode;
+    /**
+     * The reflection mode configuration with guaranteed maxIterations value.
+     *
+     * This is the internal representation after processing the user-provided
+     * reflection configuration, ensuring that maxIterations always has a value
+     * (defaulting to DEFAULT_REFLECTION_MAX_ITERATIONS if not specified).
+     */
+    reflection;
     /**
      * The input field key to iterate over when processing array inputs.
      *
@@ -119,10 +132,35 @@ class TeamAgent extends agent_js_1.Agent {
     process(input, options) {
         if (!this.skills.length)
             throw new Error("TeamAgent must have at least one skill defined.");
+        if (this.reflection)
+            return this._processReflection(input, options);
+        return this._processNonReflection(input, options);
+    }
+    _processNonReflection(input, options) {
         if (this.iterateOn) {
             return this._processIterator(this.iterateOn, input, options);
         }
-        return this._process(input, options);
+        return this._processNonIterator(input, options);
+    }
+    async _processReflection(input, options) {
+        (0, node_assert_1.default)(this.reflection, "Reflection mode must be defined for reflection processing");
+        let iterations = 0;
+        const previousOutput = { ...input };
+        for (;;) {
+            const output = await (0, agent_js_1.agentProcessResultToObject)(await this._processNonReflection(previousOutput, options));
+            Object.assign(previousOutput, output);
+            const reviewOutput = await options.context.invoke(this.reflection.reviewer, previousOutput);
+            Object.assign(previousOutput, reviewOutput);
+            const approved = await this.reflection.isApproved(reviewOutput);
+            if (approved)
+                return output;
+            if (++iterations >= this.reflection.maxIterations) {
+                if (this.reflection.returnLastOnMaxIterations)
+                    return output;
+                break;
+            }
+        }
+        throw new Error(`Reflection mode exceeded max iterations ${this.reflection.maxIterations}. Please review the feedback and try again.`);
     }
     async *_processIterator(key, input, options) {
         (0, node_assert_1.default)(this.iterateOn, "iterateInputKey must be defined for iterator processing");
@@ -133,7 +171,7 @@ class TeamAgent extends agent_js_1.Agent {
             const item = arr[i];
             if (!(0, type_utils_js_1.isRecord)(item))
                 throw new TypeError(`Expected ${String(key)} to be an object, got ${typeof item}`);
-            const res = await (0, agent_js_1.agentProcessResultToObject)(await this._process({ ...input, [key]: arr, ...item }, { ...options, streaming: false }));
+            const res = await (0, agent_js_1.agentProcessResultToObject)(await this._processNonIterator({ ...input, [key]: arr, ...item }, { ...options, streaming: false }));
             // Merge the item result with the original item used for next iteration
             if (this.iterateWithPreviousOutput) {
                 arr = (0, immer_1.produce)(arr, (draft) => {
@@ -146,7 +184,7 @@ class TeamAgent extends agent_js_1.Agent {
             yield { delta: { json: { [key]: result } } };
         }
     }
-    _process(input, options) {
+    _processNonIterator(input, options) {
         switch (this.mode) {
             case ProcessMode.sequential:
                 return this._processSequential(input, options);

package/lib/cjs/loader/agent-js.d.ts

@@ -1,8 +1,2 @@
-import { Agent, type FunctionAgentFn } from "../agents/agent.js";
-export declare function loadAgentFromJsFile(path: string): Promise<Agent<any, any> | {
-    process: FunctionAgentFn;
-    name: string;
-    description?: string | undefined;
-    inputSchema?: any;
-    outputSchema?: any;
-}>;
+import { Agent } from "../agents/agent.js";
+export declare function loadAgentFromJsFile(path: string): Promise<Agent<any, any> | import("./agent-yaml.js").AgentSchema>;

package/lib/cjs/loader/agent-js.js

@@ -34,27 +34,19 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.loadAgentFromJsFile = loadAgentFromJsFile;
-const json_schema_to_zod_1 = require("@aigne/json-schema-to-zod");
-const zod_1 = require("zod");
 const agent_js_1 = require("../agents/agent.js");
 const type_utils_js_1 = require("../utils/type-utils.js");
-const schema_js_1 = require("./schema.js");
+const agent_yaml_js_1 = require("./agent-yaml.js");
 async function loadAgentFromJsFile(path) {
-    const agentJsFileSchema = (0, schema_js_1.camelizeSchema)(zod_1.z.object({
-        name: zod_1.z.string(),
-        description: (0, schema_js_1.optionalize)(zod_1.z.string()),
-        inputSchema: (0, schema_js_1.optionalize)((0, schema_js_1.inputOutputSchema)({ path })).transform((v) => v ? (0, json_schema_to_zod_1.jsonSchemaToZod)(v) : undefined),
-        outputSchema: (0, schema_js_1.optionalize)((0, schema_js_1.inputOutputSchema)({ path })).transform((v) => v ? (0, json_schema_to_zod_1.jsonSchemaToZod)(v) : undefined),
-        process: zod_1.z.custom(),
-    }));
     const { default: agent } = await (0, type_utils_js_1.tryOrThrow)(() => Promise.resolve(`${path}`).then(s => __importStar(require(s))), (error) => new Error(`Failed to load agent definition from ${path}: ${error.message}`));
     if (agent instanceof agent_js_1.Agent)
         return agent;
     if (typeof agent !== "function") {
         throw new Error(`Agent file ${path} must export a default function, but got ${typeof agent}`);
     }
-    return (0, type_utils_js_1.tryOrThrow)(() => agentJsFileSchema.parseAsync({
+    return (0, type_utils_js_1.tryOrThrow)(() => (0, agent_yaml_js_1.parseAgentFile)(path, {
         ...agent,
+        type: "function",
         name: agent.agent_name || agent.agentName || agent.name,
         process: agent,
     }), (error) => new Error(`Failed to parse agent from ${path}: ${error.message}`));

package/lib/cjs/loader/agent-yaml.d.ts

@@ -1,4 +1,5 @@
 import { type ZodType } from "zod";
+import type { FunctionAgentFn } from "../agents/agent.js";
 import { AIAgentToolChoice } from "../agents/ai-agent.js";
 import { ProcessMode } from "../agents/team-agent.js";
 export interface HooksSchema {
@@ -15,7 +16,7 @@ export type NestAgentSchema = string | {
     defaultInput?: Record<string, any>;
     hooks?: HooksSchema | HooksSchema[];
 } | AgentSchema;
-interface BaseAgentSchema {
+export interface BaseAgentSchema {
     name?: string;
     description?: string;
     inputSchema?: ZodType<Record<string, any>>;
@@ -28,28 +29,32 @@ interface BaseAgentSchema {
         subscribeTopic?: string[];
     };
 }
-interface AIAgentSchema extends BaseAgentSchema {
+export interface AIAgentSchema extends BaseAgentSchema {
     type: "ai";
     instructions?: string;
     inputKey?: string;
     outputKey?: string;
     toolChoice?: AIAgentToolChoice;
 }
-interface MCPAgentSchema extends BaseAgentSchema {
+export interface MCPAgentSchema extends BaseAgentSchema {
     type: "mcp";
     url?: string;
     command?: string;
     args?: string[];
 }
-interface TeamAgentSchema extends BaseAgentSchema {
+export interface TeamAgentSchema extends BaseAgentSchema {
     type: "team";
     mode?: ProcessMode;
     iterateOn?: string;
 }
-interface TransformAgentSchema extends BaseAgentSchema {
+export interface TransformAgentSchema extends BaseAgentSchema {
     type: "transform";
     jsonata: string;
 }
-type AgentSchema = AIAgentSchema | MCPAgentSchema | TeamAgentSchema | TransformAgentSchema;
+export interface FunctionAgentSchema extends BaseAgentSchema {
+    type: "function";
+    process: FunctionAgentFn;
+}
+export type AgentSchema = AIAgentSchema | MCPAgentSchema | TeamAgentSchema | TransformAgentSchema | FunctionAgentSchema;
+export declare function parseAgentFile(path: string, data: object): Promise<AgentSchema>;
 export declare function loadAgentFromYamlFile(path: string): Promise<AgentSchema>;
-export {};

package/lib/cjs/loader/agent-yaml.js

@@ -1,5 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseAgentFile = parseAgentFile;
 exports.loadAgentFromYamlFile = loadAgentFromYamlFile;
 const json_schema_to_zod_1 = require("@aigne/json-schema-to-zod");
 const index_js_1 = require("@aigne/platform-helpers/nodejs/index.js");
@@ -9,7 +10,7 @@ const ai_agent_js_1 = require("../agents/ai-agent.js");
 const team_agent_js_1 = require("../agents/team-agent.js");
 const type_utils_js_1 = require("../utils/type-utils.js");
 const schema_js_1 = require("./schema.js");
-async function loadAgentFromYamlFile(path) {
+async function parseAgentFile(path, data) {
     const agentSchema = zod_1.z.lazy(() => {
         const nestAgentSchema = zod_1.z.lazy(() => zod_1.z.union([
             agentSchema,
@@ -84,11 +85,20 @@ async function loadAgentFromYamlFile(path) {
                 jsonata: zod_1.z.string(),
             })
                 .extend(baseAgentSchema.shape),
+            zod_1.z
+                .object({
+                type: zod_1.z.literal("function"),
+                process: zod_1.z.custom(),
+            })
+                .extend(baseAgentSchema.shape),
         ]));
     });
+    return agentSchema.parseAsync(data);
+}
+async function loadAgentFromYamlFile(path) {
     const raw = await (0, type_utils_js_1.tryOrThrow)(() => index_js_1.nodejs.fs.readFile(path, "utf8"), (error) => new Error(`Failed to load agent definition from ${path}: ${error.message}`));
     const json = (0, type_utils_js_1.tryOrThrow)(() => (0, yaml_1.parse)(raw), (error) => new Error(`Failed to parse agent definition from ${path}: ${error.message}`));
-    const agent = await (0, type_utils_js_1.tryOrThrow)(async () => await agentSchema.parseAsync({
+    const agent = await (0, type_utils_js_1.tryOrThrow)(async () => await parseAgentFile(path, {
         ...json,
         type: json.type ?? "ai",
         skills: json.skills ?? json.tools,

package/lib/cjs/loader/index.js

@@ -44,7 +44,7 @@ async function loadAgent(path, options, agentOptions) {
         const agent = await (0, agent_js_js_1.loadAgentFromJsFile)(path);
         if (agent instanceof agent_js_1.Agent)
             return agent;
-        return agent_js_1.FunctionAgent.from(agent);
+        return parseAgent(path, agent, options, agentOptions);
     }
     if ([".yml", ".yaml"].includes(index_js_1.nodejs.path.extname(path))) {
         const agent = await (0, agent_yaml_js_1.loadAgentFromYamlFile)(path);
@@ -133,6 +133,12 @@ async function parseAgent(path, agent, options, agentOptions) {
                 jsonata: agent.jsonata,
             });
         }
+        case "function": {
+            return agent_js_1.FunctionAgent.from({
+                ...baseOptions,
+                process: agent.process,
+            });
+        }
     }
 }
 async function loadMemory(memories, provider, options) {

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

@@ -22,6 +22,73 @@ export declare enum ProcessMode {
      */
     parallel = "parallel"
 }
+export declare const DEFAULT_REFLECTION_MAX_ITERATIONS = 3;
+/**
+ * Configuration for reflection mode processing in TeamAgent.
+ *
+ * Reflection mode enables iterative refinement of agent outputs through a review process.
+ * The team agent will repeatedly process the input and have a reviewer agent evaluate
+ * the output until it meets approval criteria or reaches the maximum iteration limit.
+ *
+ * This is particularly useful for:
+ * - Quality assurance workflows where outputs need validation
+ * - Iterative improvement processes where initial results can be refined
+ * - Self-correcting agent systems that learn from feedback
+ */
+export interface ReflectionMode {
+    /**
+     * The agent responsible for reviewing and providing feedback on the team's output.
+     *
+     * The reviewer agent receives the combined output from the team's processing
+     * and should provide feedback or evaluation that can be used to determine
+     * whether the output meets the required standards.
+     */
+    reviewer: Agent;
+    /**
+     * Function that determines whether the reviewer's output indicates approval.
+     *
+     * This function receives the reviewer agent's output message and should return:
+     * - `true` or truthy value: The output is approved and processing should stop
+     * - `false` or falsy value: The output needs improvement and another iteration should run
+     *
+     * The function can be synchronous or asynchronous, allowing for complex approval logic
+     * including external validation, scoring systems, or human-in-the-loop approval.
+     *
+     * @param output - The message output from the reviewer agent
+     * @returns A boolean or truthy/falsy value indicating approval status
+     */
+    isApproved: (output: Message) => PromiseOrValue<boolean | unknown>;
+    /**
+     * Maximum number of reflection iterations before giving up.
+     *
+     * This prevents infinite loops when the approval criteria cannot be met.
+     * If the maximum iterations are reached without approval, the process will
+     * throw an error indicating the reflection failed to converge.
+     *
+     * @default 3
+     */
+    maxIterations?: number;
+    /**
+     * Controls the behavior when maximum iterations are reached without approval.
+     *
+     * When set to `true`, the TeamAgent will return the last generated output
+     * instead of throwing an error when the maximum number of reflection iterations
+     * is reached without the reviewer's approval.
+     *
+     * When set to `false` or undefined, the TeamAgent will throw an error
+     * indicating that the reflection process failed to converge within the
+     * maximum iteration limit.
+     *
+     * This option is useful for scenarios where:
+     * - You want to get the best available result even if it's not perfect
+     * - The approval criteria might be too strict for the given context
+     * - You prefer graceful degradation over complete failure
+     * - You want to implement custom error handling based on the returned result
+     *
+     * @default false
+     */
+    returnLastOnMaxIterations?: boolean;
+}
 /**
  * Configuration options for creating a TeamAgent.
  *
@@ -33,6 +100,21 @@ export interface TeamAgentOptions<I extends Message, O extends Message> extends
      * @default {ProcessMode.sequential}
      */
     mode?: ProcessMode;
+    /**
+     * Configuration for reflection mode processing.
+     *
+     * When enabled, the TeamAgent will use an iterative refinement process where:
+     * 1. The team processes the input normally
+     * 2. A reviewer agent evaluates the output
+     * 3. If not approved, the process repeats with the previous output as context
+     * 4. This continues until approval or maximum iterations are reached
+     *
+     * This enables self-improving agent workflows that can iteratively refine
+     * their outputs based on feedback from a specialized reviewer agent.
+     *
+     * @see ReflectionMode for detailed configuration options
+     */
+    reflection?: ReflectionMode;
     /**
      * Specifies which input field should be treated as an array for iterative processing.
      *
@@ -116,6 +198,14 @@ export declare class TeamAgent<I extends Message, O extends Message> extends Age
      * This can be either sequential (one after another) or parallel (all at once).
      */
     mode: ProcessMode;
+    /**
+     * The reflection mode configuration with guaranteed maxIterations value.
+     *
+     * This is the internal representation after processing the user-provided
+     * reflection configuration, ensuring that maxIterations always has a value
+     * (defaulting to DEFAULT_REFLECTION_MAX_ITERATIONS if not specified).
+     */
+    reflection?: ReflectionMode & Required<Pick<ReflectionMode, "maxIterations">>;
     /**
      * The input field key to iterate over when processing array inputs.
      *
@@ -148,8 +238,10 @@ export declare class TeamAgent<I extends Message, O extends Message> extends Age
      * @returns A stream of message chunks that collectively form the response
      */
     process(input: I, options: AgentInvokeOptions): PromiseOrValue<AgentProcessResult<O>>;
+    private _processNonReflection;
+    private _processReflection;
     private _processIterator;
-    private _process;
+    private _processNonIterator;
     /**
      * Process input sequentially through each agent in the team.
      *

package/lib/dts/loader/agent-js.d.ts

@@ -1,8 +1,2 @@
-import { Agent, type FunctionAgentFn } from "../agents/agent.js";
-export declare function loadAgentFromJsFile(path: string): Promise<Agent<any, any> | {
-    process: FunctionAgentFn;
-    name: string;
-    description?: string | undefined;
-    inputSchema?: any;
-    outputSchema?: any;
-}>;
+import { Agent } from "../agents/agent.js";
+export declare function loadAgentFromJsFile(path: string): Promise<Agent<any, any> | import("./agent-yaml.js").AgentSchema>;

package/lib/dts/loader/agent-yaml.d.ts

@@ -1,4 +1,5 @@
 import { type ZodType } from "zod";
+import type { FunctionAgentFn } from "../agents/agent.js";
 import { AIAgentToolChoice } from "../agents/ai-agent.js";
 import { ProcessMode } from "../agents/team-agent.js";
 export interface HooksSchema {
@@ -15,7 +16,7 @@ export type NestAgentSchema = string | {
     defaultInput?: Record<string, any>;
     hooks?: HooksSchema | HooksSchema[];
 } | AgentSchema;
-interface BaseAgentSchema {
+export interface BaseAgentSchema {
     name?: string;
     description?: string;
     inputSchema?: ZodType<Record<string, any>>;
@@ -28,28 +29,32 @@ interface BaseAgentSchema {
         subscribeTopic?: string[];
     };
 }
-interface AIAgentSchema extends BaseAgentSchema {
+export interface AIAgentSchema extends BaseAgentSchema {
     type: "ai";
     instructions?: string;
     inputKey?: string;
     outputKey?: string;
     toolChoice?: AIAgentToolChoice;
 }
-interface MCPAgentSchema extends BaseAgentSchema {
+export interface MCPAgentSchema extends BaseAgentSchema {
     type: "mcp";
     url?: string;
     command?: string;
     args?: string[];
 }
-interface TeamAgentSchema extends BaseAgentSchema {
+export interface TeamAgentSchema extends BaseAgentSchema {
     type: "team";
     mode?: ProcessMode;
     iterateOn?: string;
 }
-interface TransformAgentSchema extends BaseAgentSchema {
+export interface TransformAgentSchema extends BaseAgentSchema {
     type: "transform";
     jsonata: string;
 }
-type AgentSchema = AIAgentSchema | MCPAgentSchema | TeamAgentSchema | TransformAgentSchema;
+export interface FunctionAgentSchema extends BaseAgentSchema {
+    type: "function";
+    process: FunctionAgentFn;
+}
+export type AgentSchema = AIAgentSchema | MCPAgentSchema | TeamAgentSchema | TransformAgentSchema | FunctionAgentSchema;
+export declare function parseAgentFile(path: string, data: object): Promise<AgentSchema>;
 export declare function loadAgentFromYamlFile(path: string): Promise<AgentSchema>;
-export {};

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

@@ -22,6 +22,73 @@ export declare enum ProcessMode {
      */
     parallel = "parallel"
 }
+export declare const DEFAULT_REFLECTION_MAX_ITERATIONS = 3;
+/**
+ * Configuration for reflection mode processing in TeamAgent.
+ *
+ * Reflection mode enables iterative refinement of agent outputs through a review process.
+ * The team agent will repeatedly process the input and have a reviewer agent evaluate
+ * the output until it meets approval criteria or reaches the maximum iteration limit.
+ *
+ * This is particularly useful for:
+ * - Quality assurance workflows where outputs need validation
+ * - Iterative improvement processes where initial results can be refined
+ * - Self-correcting agent systems that learn from feedback
+ */
+export interface ReflectionMode {
+    /**
+     * The agent responsible for reviewing and providing feedback on the team's output.
+     *
+     * The reviewer agent receives the combined output from the team's processing
+     * and should provide feedback or evaluation that can be used to determine
+     * whether the output meets the required standards.
+     */
+    reviewer: Agent;
+    /**
+     * Function that determines whether the reviewer's output indicates approval.
+     *
+     * This function receives the reviewer agent's output message and should return:
+     * - `true` or truthy value: The output is approved and processing should stop
+     * - `false` or falsy value: The output needs improvement and another iteration should run
+     *
+     * The function can be synchronous or asynchronous, allowing for complex approval logic
+     * including external validation, scoring systems, or human-in-the-loop approval.
+     *
+     * @param output - The message output from the reviewer agent
+     * @returns A boolean or truthy/falsy value indicating approval status
+     */
+    isApproved: (output: Message) => PromiseOrValue<boolean | unknown>;
+    /**
+     * Maximum number of reflection iterations before giving up.
+     *
+     * This prevents infinite loops when the approval criteria cannot be met.
+     * If the maximum iterations are reached without approval, the process will
+     * throw an error indicating the reflection failed to converge.
+     *
+     * @default 3
+     */
+    maxIterations?: number;
+    /**
+     * Controls the behavior when maximum iterations are reached without approval.
+     *
+     * When set to `true`, the TeamAgent will return the last generated output
+     * instead of throwing an error when the maximum number of reflection iterations
+     * is reached without the reviewer's approval.
+     *
+     * When set to `false` or undefined, the TeamAgent will throw an error
+     * indicating that the reflection process failed to converge within the
+     * maximum iteration limit.
+     *
+     * This option is useful for scenarios where:
+     * - You want to get the best available result even if it's not perfect
+     * - The approval criteria might be too strict for the given context
+     * - You prefer graceful degradation over complete failure
+     * - You want to implement custom error handling based on the returned result
+     *
+     * @default false
+     */
+    returnLastOnMaxIterations?: boolean;
+}
 /**
  * Configuration options for creating a TeamAgent.
  *
@@ -33,6 +100,21 @@ export interface TeamAgentOptions<I extends Message, O extends Message> extends
      * @default {ProcessMode.sequential}
      */
     mode?: ProcessMode;
+    /**
+     * Configuration for reflection mode processing.
+     *
+     * When enabled, the TeamAgent will use an iterative refinement process where:
+     * 1. The team processes the input normally
+     * 2. A reviewer agent evaluates the output
+     * 3. If not approved, the process repeats with the previous output as context
+     * 4. This continues until approval or maximum iterations are reached
+     *
+     * This enables self-improving agent workflows that can iteratively refine
+     * their outputs based on feedback from a specialized reviewer agent.
+     *
+     * @see ReflectionMode for detailed configuration options
+     */
+    reflection?: ReflectionMode;
     /**
      * Specifies which input field should be treated as an array for iterative processing.
      *
@@ -116,6 +198,14 @@ export declare class TeamAgent<I extends Message, O extends Message> extends Age
      * This can be either sequential (one after another) or parallel (all at once).
      */
     mode: ProcessMode;
+    /**
+     * The reflection mode configuration with guaranteed maxIterations value.
+     *
+     * This is the internal representation after processing the user-provided
+     * reflection configuration, ensuring that maxIterations always has a value
+     * (defaulting to DEFAULT_REFLECTION_MAX_ITERATIONS if not specified).
+     */
+    reflection?: ReflectionMode & Required<Pick<ReflectionMode, "maxIterations">>;
     /**
      * The input field key to iterate over when processing array inputs.
      *
@@ -148,8 +238,10 @@ export declare class TeamAgent<I extends Message, O extends Message> extends Age
      * @returns A stream of message chunks that collectively form the response
      */
     process(input: I, options: AgentInvokeOptions): PromiseOrValue<AgentProcessResult<O>>;
+    private _processNonReflection;
+    private _processReflection;
     private _processIterator;
-    private _process;
+    private _processNonIterator;
     /**
      * Process input sequentially through each agent in the team.
      *

package/lib/esm/agents/team-agent.js

@@ -26,6 +26,7 @@ export var ProcessMode;
      */
     ProcessMode["parallel"] = "parallel";
 })(ProcessMode || (ProcessMode = {}));
+export const DEFAULT_REFLECTION_MAX_ITERATIONS = 3;
 /**
  * TeamAgent coordinates a group of agents working together to accomplish tasks.
  *
@@ -70,6 +71,10 @@ export class TeamAgent extends Agent {
     constructor(options) {
         super(options);
         this.mode = options.mode ?? ProcessMode.sequential;
+        this.reflection = options.reflection && {
+            ...options.reflection,
+            maxIterations: options.reflection.maxIterations ?? DEFAULT_REFLECTION_MAX_ITERATIONS,
+        };
         this.iterateOn = options.iterateOn;
         this.iterateWithPreviousOutput = options.iterateWithPreviousOutput;
     }
@@ -79,6 +84,14 @@ export class TeamAgent extends Agent {
      * This can be either sequential (one after another) or parallel (all at once).
      */
     mode;
+    /**
+     * The reflection mode configuration with guaranteed maxIterations value.
+     *
+     * This is the internal representation after processing the user-provided
+     * reflection configuration, ensuring that maxIterations always has a value
+     * (defaulting to DEFAULT_REFLECTION_MAX_ITERATIONS if not specified).
+     */
+    reflection;
     /**
      * The input field key to iterate over when processing array inputs.
      *
@@ -113,10 +126,35 @@ export class TeamAgent extends Agent {
     process(input, options) {
         if (!this.skills.length)
             throw new Error("TeamAgent must have at least one skill defined.");
+        if (this.reflection)
+            return this._processReflection(input, options);
+        return this._processNonReflection(input, options);
+    }
+    _processNonReflection(input, options) {
         if (this.iterateOn) {
             return this._processIterator(this.iterateOn, input, options);
         }
-        return this._process(input, options);
+        return this._processNonIterator(input, options);
+    }
+    async _processReflection(input, options) {
+        assert(this.reflection, "Reflection mode must be defined for reflection processing");
+        let iterations = 0;
+        const previousOutput = { ...input };
+        for (;;) {
+            const output = await agentProcessResultToObject(await this._processNonReflection(previousOutput, options));
+            Object.assign(previousOutput, output);
+            const reviewOutput = await options.context.invoke(this.reflection.reviewer, previousOutput);
+            Object.assign(previousOutput, reviewOutput);
+            const approved = await this.reflection.isApproved(reviewOutput);
+            if (approved)
+                return output;
+            if (++iterations >= this.reflection.maxIterations) {
+                if (this.reflection.returnLastOnMaxIterations)
+                    return output;
+                break;
+            }
+        }
+        throw new Error(`Reflection mode exceeded max iterations ${this.reflection.maxIterations}. Please review the feedback and try again.`);
     }
     async *_processIterator(key, input, options) {
         assert(this.iterateOn, "iterateInputKey must be defined for iterator processing");
@@ -127,7 +165,7 @@ export class TeamAgent extends Agent {
             const item = arr[i];
             if (!isRecord(item))
                 throw new TypeError(`Expected ${String(key)} to be an object, got ${typeof item}`);
-            const res = await agentProcessResultToObject(await this._process({ ...input, [key]: arr, ...item }, { ...options, streaming: false }));
+            const res = await agentProcessResultToObject(await this._processNonIterator({ ...input, [key]: arr, ...item }, { ...options, streaming: false }));
             // Merge the item result with the original item used for next iteration
             if (this.iterateWithPreviousOutput) {
                 arr = produce(arr, (draft) => {
@@ -140,7 +178,7 @@ export class TeamAgent extends Agent {
             yield { delta: { json: { [key]: result } } };
         }
     }
-    _process(input, options) {
+    _processNonIterator(input, options) {
         switch (this.mode) {
             case ProcessMode.sequential:
                 return this._processSequential(input, options);

package/lib/esm/loader/agent-js.d.ts

@@ -1,8 +1,2 @@
-import { Agent, type FunctionAgentFn } from "../agents/agent.js";
-export declare function loadAgentFromJsFile(path: string): Promise<Agent<any, any> | {
-    process: FunctionAgentFn;
-    name: string;
-    description?: string | undefined;
-    inputSchema?: any;
-    outputSchema?: any;
-}>;
+import { Agent } from "../agents/agent.js";
+export declare function loadAgentFromJsFile(path: string): Promise<Agent<any, any> | import("./agent-yaml.js").AgentSchema>;

package/lib/esm/loader/agent-js.js

@@ -1,24 +1,16 @@
-import { jsonSchemaToZod } from "@aigne/json-schema-to-zod";
-import { z } from "zod";
 import { Agent } from "../agents/agent.js";
 import { tryOrThrow } from "../utils/type-utils.js";
-import { camelizeSchema, inputOutputSchema, optionalize } from "./schema.js";
+import { parseAgentFile } from "./agent-yaml.js";
 export async function loadAgentFromJsFile(path) {
-    const agentJsFileSchema = camelizeSchema(z.object({
-        name: z.string(),
-        description: optionalize(z.string()),
-        inputSchema: optionalize(inputOutputSchema({ path })).transform((v) => v ? jsonSchemaToZod(v) : undefined),
-        outputSchema: optionalize(inputOutputSchema({ path })).transform((v) => v ? jsonSchemaToZod(v) : undefined),
-        process: z.custom(),
-    }));
     const { default: agent } = await tryOrThrow(() => import(/* @vite-ignore */ path), (error) => new Error(`Failed to load agent definition from ${path}: ${error.message}`));
     if (agent instanceof Agent)
         return agent;
     if (typeof agent !== "function") {
         throw new Error(`Agent file ${path} must export a default function, but got ${typeof agent}`);
     }
-    return tryOrThrow(() => agentJsFileSchema.parseAsync({
+    return tryOrThrow(() => parseAgentFile(path, {
         ...agent,
+        type: "function",
         name: agent.agent_name || agent.agentName || agent.name,
         process: agent,
     }), (error) => new Error(`Failed to parse agent from ${path}: ${error.message}`));

package/lib/esm/loader/agent-yaml.d.ts

@@ -1,4 +1,5 @@
 import { type ZodType } from "zod";
+import type { FunctionAgentFn } from "../agents/agent.js";
 import { AIAgentToolChoice } from "../agents/ai-agent.js";
 import { ProcessMode } from "../agents/team-agent.js";
 export interface HooksSchema {
@@ -15,7 +16,7 @@ export type NestAgentSchema = string | {
     defaultInput?: Record<string, any>;
     hooks?: HooksSchema | HooksSchema[];
 } | AgentSchema;
-interface BaseAgentSchema {
+export interface BaseAgentSchema {
     name?: string;
     description?: string;
     inputSchema?: ZodType<Record<string, any>>;
@@ -28,28 +29,32 @@ interface BaseAgentSchema {
         subscribeTopic?: string[];
     };
 }
-interface AIAgentSchema extends BaseAgentSchema {
+export interface AIAgentSchema extends BaseAgentSchema {
     type: "ai";
     instructions?: string;
     inputKey?: string;
     outputKey?: string;
     toolChoice?: AIAgentToolChoice;
 }
-interface MCPAgentSchema extends BaseAgentSchema {
+export interface MCPAgentSchema extends BaseAgentSchema {
     type: "mcp";
     url?: string;
     command?: string;
     args?: string[];
 }
-interface TeamAgentSchema extends BaseAgentSchema {
+export interface TeamAgentSchema extends BaseAgentSchema {
     type: "team";
     mode?: ProcessMode;
     iterateOn?: string;
 }
-interface TransformAgentSchema extends BaseAgentSchema {
+export interface TransformAgentSchema extends BaseAgentSchema {
     type: "transform";
     jsonata: string;
 }
-type AgentSchema = AIAgentSchema | MCPAgentSchema | TeamAgentSchema | TransformAgentSchema;
+export interface FunctionAgentSchema extends BaseAgentSchema {
+    type: "function";
+    process: FunctionAgentFn;
+}
+export type AgentSchema = AIAgentSchema | MCPAgentSchema | TeamAgentSchema | TransformAgentSchema | FunctionAgentSchema;
+export declare function parseAgentFile(path: string, data: object): Promise<AgentSchema>;
 export declare function loadAgentFromYamlFile(path: string): Promise<AgentSchema>;
-export {};

package/lib/esm/loader/agent-yaml.js

@@ -6,7 +6,7 @@ import { AIAgentToolChoice } from "../agents/ai-agent.js";
 import { ProcessMode } from "../agents/team-agent.js";
 import { tryOrThrow } from "../utils/type-utils.js";
 import { camelizeSchema, defaultInputSchema, inputOutputSchema, optionalize } from "./schema.js";
-export async function loadAgentFromYamlFile(path) {
+export async function parseAgentFile(path, data) {
     const agentSchema = z.lazy(() => {
         const nestAgentSchema = z.lazy(() => z.union([
             agentSchema,
@@ -81,11 +81,20 @@ export async function loadAgentFromYamlFile(path) {
                 jsonata: z.string(),
             })
                 .extend(baseAgentSchema.shape),
+            z
+                .object({
+                type: z.literal("function"),
+                process: z.custom(),
+            })
+                .extend(baseAgentSchema.shape),
         ]));
     });
+    return agentSchema.parseAsync(data);
+}
+export async function loadAgentFromYamlFile(path) {
     const raw = await tryOrThrow(() => nodejs.fs.readFile(path, "utf8"), (error) => new Error(`Failed to load agent definition from ${path}: ${error.message}`));
     const json = tryOrThrow(() => parse(raw), (error) => new Error(`Failed to parse agent definition from ${path}: ${error.message}`));
-    const agent = await tryOrThrow(async () => await agentSchema.parseAsync({
+    const agent = await tryOrThrow(async () => await parseAgentFile(path, {
         ...json,
         type: json.type ?? "ai",
         skills: json.skills ?? json.tools,

package/lib/esm/loader/index.js

@@ -35,7 +35,7 @@ export async function loadAgent(path, options, agentOptions) {
         const agent = await loadAgentFromJsFile(path);
         if (agent instanceof Agent)
             return agent;
-        return FunctionAgent.from(agent);
+        return parseAgent(path, agent, options, agentOptions);
     }
     if ([".yml", ".yaml"].includes(nodejs.path.extname(path))) {
         const agent = await loadAgentFromYamlFile(path);
@@ -124,6 +124,12 @@ async function parseAgent(path, agent, options, agentOptions) {
                 jsonata: agent.jsonata,
             });
         }
+        case "function": {
+            return FunctionAgent.from({
+                ...baseOptions,
+                process: agent.process,
+            });
+        }
     }
 }
 async function loadMemory(memories, provider, options) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aigne/core",
-  "version": "1.36.0",
+  "version": "1.37.0",
   "description": "AIGNE core library for building AI-powered applications",
   "publishConfig": {
     "access": "public"