@aigne/core 1.28.1 → 1.29.0

package/CHANGELOG.md

@@ -12,6 +12,27 @@
   * dependencies
     * @aigne/observability bumped to 0.1.0
 
+## [1.29.0](https://github.com/AIGNE-io/aigne-framework/compare/core-v1.28.2...core-v1.29.0) (2025-07-02)
+
+
+### Features
+
+* support iterate special input call skills for TeamAgent ([#188](https://github.com/AIGNE-io/aigne-framework/issues/188)) ([8cf06d3](https://github.com/AIGNE-io/aigne-framework/commit/8cf06d39172ed59ca93f34d893486f2bb7bd2e5a))
+
+## [1.28.2](https://github.com/AIGNE-io/aigne-framework/compare/core-v1.28.1...core-v1.28.2) (2025-07-01)
+
+
+### Bug Fixes
+
+* fix: compatible with node 20.0 & polish example defintions ([#209](https://github.com/AIGNE-io/aigne-framework/issues/209)) ([9752b96](https://github.com/AIGNE-io/aigne-framework/commit/9752b96dc54a44c6f710f056fe9205c0f2b0a73e))
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @aigne/observability-api bumped to 0.3.2
+
 ## [1.28.1](https://github.com/AIGNE-io/aigne-framework/compare/core-v1.28.0...core-v1.28.1) (2025-07-01)
 
 

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

@@ -692,6 +692,7 @@ export type AgentProcessAsyncGenerator<O extends Message> = AsyncGenerator<Agent
  * @template O Agent output message type
  */
 export type AgentProcessResult<O extends Message> = AgentResponse<O> | AgentProcessAsyncGenerator<O> | Agent;
+export declare function agentProcessResultToObject<O extends Message>(response: AgentProcessResult<O>): Promise<O>;
 /**
  * Schema definition type for agent input/output
  *

package/lib/cjs/agents/agent.js

@@ -42,6 +42,7 @@ exports.isAgentResponseDelta = isAgentResponseDelta;
 exports.isAgentResponseProgress = isAgentResponseProgress;
 exports.textDelta = textDelta;
 exports.jsonDelta = jsonDelta;
+exports.agentProcessResultToObject = agentProcessResultToObject;
 const index_js_1 = require("@aigne/platform-helpers/nodejs/index.js");
 const zod_1 = require("zod");
 const logger_js_1 = require("../utils/logger.js");
@@ -370,11 +371,7 @@ class Agent {
                     },
                 }), opts);
             }
-            return await this.checkResponseByGuideRails(input, this.processAgentOutput(parsedInput, response instanceof ReadableStream
-                ? await (0, stream_utils_js_1.agentResponseStreamToObject)(response)
-                : (0, stream_utils_js_1.isAsyncGenerator)(response)
-                    ? await (0, stream_utils_js_1.agentResponseStreamToObject)(response)
-                    : response, opts), opts);
+            return await this.checkResponseByGuideRails(input, this.processAgentOutput(parsedInput, await agentProcessResultToObject(response), opts), opts);
         }
         catch (error) {
             throw await this.processAgentError(input, error, opts);
@@ -623,6 +620,13 @@ function textDelta(textDelta) {
 function jsonDelta(jsonDelta) {
     return { delta: { json: jsonDelta } };
 }
+async function agentProcessResultToObject(response) {
+    return response instanceof ReadableStream
+        ? await (0, stream_utils_js_1.agentResponseStreamToObject)(response)
+        : (0, stream_utils_js_1.isAsyncGenerator)(response)
+            ? await (0, stream_utils_js_1.agentResponseStreamToObject)(response)
+            : response;
+}
 function checkAgentInputOutputSchema(schema) {
     if (!(schema instanceof zod_1.ZodObject) && typeof schema !== "function") {
         throw new Error(`schema must be a zod object or function return a zod object, got: ${typeof schema}`);

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

@@ -33,6 +33,42 @@ export interface TeamAgentOptions<I extends Message, O extends Message> extends
      * @default {ProcessMode.sequential}
      */
     mode?: ProcessMode;
+    /**
+     * Specifies which input field should be treated as an array for iterative processing.
+     *
+     * When this property is set, the TeamAgent will iterate over the array values in the
+     * specified input field, processing each element individually through the team's agents.
+     * The results from each iteration are accumulated and returned as a streaming response.
+     *
+     * This is particularly useful for batch processing scenarios where you need to apply
+     * the same agent workflow to multiple similar data items.
+     *
+     * @remarks
+     * - The specified field must contain an array or array-like value
+     * - Each array element should be an object that can be merged with the base input
+     * - Non-array values will be treated as single-element arrays
+     * - The processing results are streamed incrementally as each iteration completes
+     */
+    iterateOn?: keyof I;
+    /**
+     * Controls whether to merge the output from each iteration back into the array items
+     * for subsequent iterations when using `iterateOn`.
+     *
+     * When set to `true`, the output from processing each array element is merged back
+     * into that element, making it available for the next iteration. This creates a
+     * cumulative effect where each iteration builds upon the results of previous ones.
+     *
+     * When set to `false` or undefined, each array element is processed independently
+     * without any cross-iteration data sharing.
+     *
+     * This is particularly useful for scenarios where:
+     * - You need to progressively enrich data across iterations
+     * - Later iterations depend on the results of earlier ones
+     * - You want to build a chain of transformations on array data
+     *
+     * @default false
+     */
+    iterateWithPreviousOutput?: boolean;
 }
 /**
  * TeamAgent coordinates a group of agents working together to accomplish tasks.
@@ -80,6 +116,25 @@ 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 input field key to iterate over when processing array inputs.
+     *
+     * When set, this property enables the TeamAgent to process array values iteratively,
+     * where each array element is processed individually through the team's agent workflow.
+     * The accumulated results are returned via streaming response chunks.
+     *
+     * @see TeamAgentOptions.iterateOn for detailed documentation
+     */
+    iterateOn?: keyof I;
+    /**
+     * Controls whether to merge the output from each iteration back into the array items
+     * for subsequent iterations when using `iterateOn`.
+     *
+     * @see TeamAgentOptions.iterateWithPreviousOutput for detailed documentation
+     *
+     * @default false
+     */
+    iterateWithPreviousOutput?: boolean;
     /**
      * Process an input message by routing it through the team's agents.
      *
@@ -93,6 +148,8 @@ 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 _processIterator;
+    private _process;
     /**
      * Process input sequentially through each agent in the team.
      *
@@ -108,7 +165,7 @@ export declare class TeamAgent<I extends Message, O extends Message> extends Age
      *
      * @private
      */
-    _processSequential(input: I, options: AgentInvokeOptions): PromiseOrValue<AgentProcessResult<O>>;
+    _processSequential(input: Message, options: AgentInvokeOptions): PromiseOrValue<AgentProcessResult<O>>;
     /**
      * Process input in parallel through all agents in the team.
      *
@@ -123,5 +180,5 @@ export declare class TeamAgent<I extends Message, O extends Message> extends Age
      *
      * @private
      */
-    _processParallel(input: I, options: AgentInvokeOptions): PromiseOrValue<AgentProcessResult<O>>;
+    _processParallel(input: Message, options: AgentInvokeOptions): PromiseOrValue<AgentProcessResult<O>>;
 }

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

@@ -1,6 +1,11 @@
 "use strict";
+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;
+const node_assert_1 = __importDefault(require("node:assert"));
+const immer_1 = require("immer");
 const stream_utils_js_1 = require("../utils/stream-utils.js");
 const type_utils_js_1 = require("../utils/type-utils.js");
 const agent_js_1 = require("./agent.js");
@@ -71,6 +76,8 @@ class TeamAgent extends agent_js_1.Agent {
     constructor(options) {
         super(options);
         this.mode = options.mode ?? ProcessMode.sequential;
+        this.iterateOn = options.iterateOn;
+        this.iterateWithPreviousOutput = options.iterateWithPreviousOutput;
     }
     /**
      * The processing mode that determines how agents in the team are executed.
@@ -78,6 +85,25 @@ class TeamAgent extends agent_js_1.Agent {
      * This can be either sequential (one after another) or parallel (all at once).
      */
     mode;
+    /**
+     * The input field key to iterate over when processing array inputs.
+     *
+     * When set, this property enables the TeamAgent to process array values iteratively,
+     * where each array element is processed individually through the team's agent workflow.
+     * The accumulated results are returned via streaming response chunks.
+     *
+     * @see TeamAgentOptions.iterateOn for detailed documentation
+     */
+    iterateOn;
+    /**
+     * Controls whether to merge the output from each iteration back into the array items
+     * for subsequent iterations when using `iterateOn`.
+     *
+     * @see TeamAgentOptions.iterateWithPreviousOutput for detailed documentation
+     *
+     * @default false
+     */
+    iterateWithPreviousOutput;
     /**
      * Process an input message by routing it through the team's agents.
      *
@@ -91,6 +117,34 @@ class TeamAgent extends agent_js_1.Agent {
      * @returns A stream of message chunks that collectively form the response
      */
     process(input, options) {
+        if (this.iterateOn) {
+            return this._processIterator(this.iterateOn, input, options);
+        }
+        return this._process(input, options);
+    }
+    async *_processIterator(key, input, options) {
+        (0, node_assert_1.default)(this.iterateOn, "iterateInputKey must be defined for iterator processing");
+        let arr = input[this.iterateOn];
+        arr = Array.isArray(arr) ? [...arr] : (0, type_utils_js_1.isNil)(arr) ? [arr] : [];
+        const result = [];
+        for (let i = 0; i < arr.length; i++) {
+            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 }));
+            // Merge the item result with the original item used for next iteration
+            if (this.iterateWithPreviousOutput) {
+                arr = (0, immer_1.produce)(arr, (draft) => {
+                    const item = draft[i];
+                    (0, node_assert_1.default)(item);
+                    Object.assign(item, res);
+                });
+            }
+            result.push((0, type_utils_js_1.omit)(res, key));
+            yield { delta: { json: { [key]: result } } };
+        }
+    }
+    _process(input, options) {
         switch (this.mode) {
             case ProcessMode.sequential:
                 return this._processSequential(input, options);

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

@@ -0,0 +1,82 @@
+import { Agent, type AgentOptions, type Message } from "./agent.js";
+/**
+ * Configuration options for TransformAgent
+ *
+ * TransformAgent is a specialized agent that transforms input data to output data
+ * using [JSONata](https://jsonata.org/) expressions. It's particularly useful for:
+ * - Data format conversion (e.g., snake_case to camelCase)
+ * - Field mapping and renaming
+ * - Data structure transformation
+ * - Simple data processing without complex logic
+ * - API response normalization
+ * - Configuration data transformation
+ */
+export interface TransformAgentOptions<I extends Message, O extends Message> extends AgentOptions<I, O> {
+    /**
+     * JSONata expression string for data transformation
+     *
+     * JSONata is a lightweight query and transformation language for JSON data.
+     * The expression defines how input data should be transformed into output data.
+     *
+     * Common JSONata patterns:
+     * - Field mapping: `{ "newField": oldField }`
+     * - Array transformation: `items.{ "name": product_name, "price": price }`
+     * - Calculations: `$sum(items.price)`, `$count(items)`
+     * - Conditional logic: `condition ? value1 : value2`
+     * - String operations: `$uppercase(name)`, `$substring(text, 0, 10)`
+     *
+     * @see https://jsonata.org/ for complete JSONata syntax documentation
+     * @see https://try.jsonata.org/ for interactive JSONata playground
+     */
+    jsonata: string;
+}
+/**
+ * TransformAgent - A specialized agent for data transformation using JSONata expressions
+ *
+ * This agent provides a declarative way to transform structured data without writing
+ * custom processing logic. It leverages the power of JSONata, a lightweight query and
+ * transformation language, to handle complex data manipulations through simple expressions.
+ *
+ * Common Use Cases:
+ * - API response normalization and field mapping
+ * - Database query result transformation
+ * - Configuration data restructuring
+ * - Data format conversion (snake_case ↔ camelCase)
+ * - Aggregation and calculation operations
+ * - Filtering and conditional data processing
+ */
+export declare class TransformAgent<I extends Message = Message, O extends Message = Message> extends Agent<I, O> {
+    static type: string;
+    /**
+     * Factory method to create a new TransformAgent instance
+     *
+     * Provides a convenient way to create TransformAgent instances with proper typing
+     *
+     * @param options Configuration options for the TransformAgent
+     * @returns A new TransformAgent instance
+     */
+    static from<I extends Message, O extends Message>(options: TransformAgentOptions<I, O>): TransformAgent<I, O>;
+    /**
+     * Create a new TransformAgent instance
+     *
+     * @param options Configuration options including the JSONata expression
+     */
+    constructor(options: TransformAgentOptions<I, O>);
+    /**
+     * The JSONata expression string used for data transformation
+     *
+     * This expression is compiled and executed against input data to produce
+     * the transformed output. The expression is stored as a string and compiled
+     * on each invocation for maximum flexibility.
+     */
+    private jsonata;
+    /**
+     * Process input data using the configured JSONata expression
+     *
+     * This method compiles the JSONata expression and evaluates it against the input data.
+     *
+     * @param input The input message to transform
+     * @returns Promise resolving to the transformed output message
+     */
+    process(input: I): Promise<O>;
+}

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

@@ -0,0 +1,67 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TransformAgent = void 0;
+const jsonata_1 = __importDefault(require("jsonata"));
+const agent_js_1 = require("./agent.js");
+/**
+ * TransformAgent - A specialized agent for data transformation using JSONata expressions
+ *
+ * This agent provides a declarative way to transform structured data without writing
+ * custom processing logic. It leverages the power of JSONata, a lightweight query and
+ * transformation language, to handle complex data manipulations through simple expressions.
+ *
+ * Common Use Cases:
+ * - API response normalization and field mapping
+ * - Database query result transformation
+ * - Configuration data restructuring
+ * - Data format conversion (snake_case ↔ camelCase)
+ * - Aggregation and calculation operations
+ * - Filtering and conditional data processing
+ */
+class TransformAgent extends agent_js_1.Agent {
+    static type = "TransformAgent";
+    /**
+     * Factory method to create a new TransformAgent instance
+     *
+     * Provides a convenient way to create TransformAgent instances with proper typing
+     *
+     * @param options Configuration options for the TransformAgent
+     * @returns A new TransformAgent instance
+     */
+    static from(options) {
+        return new TransformAgent(options);
+    }
+    /**
+     * Create a new TransformAgent instance
+     *
+     * @param options Configuration options including the JSONata expression
+     */
+    constructor(options) {
+        super(options);
+        this.jsonata = options.jsonata;
+    }
+    /**
+     * The JSONata expression string used for data transformation
+     *
+     * This expression is compiled and executed against input data to produce
+     * the transformed output. The expression is stored as a string and compiled
+     * on each invocation for maximum flexibility.
+     */
+    jsonata;
+    /**
+     * Process input data using the configured JSONata expression
+     *
+     * This method compiles the JSONata expression and evaluates it against the input data.
+     *
+     * @param input The input message to transform
+     * @returns Promise resolving to the transformed output message
+     */
+    async process(input) {
+        const expression = (0, jsonata_1.default)(this.jsonata);
+        return await expression.evaluate(input);
+    }
+}
+exports.TransformAgent = TransformAgent;

package/lib/cjs/index.d.ts

@@ -4,6 +4,7 @@ export * from "./agents/chat-model.js";
 export * from "./agents/guide-rail-agent.js";
 export * from "./agents/mcp-agent.js";
 export * from "./agents/team-agent.js";
+export * from "./agents/transform-agent.js";
 export * from "./agents/types.js";
 export * from "./agents/user-agent.js";
 export * from "./aigne/index.js";

package/lib/cjs/index.js

@@ -20,6 +20,7 @@ __exportStar(require("./agents/chat-model.js"), exports);
 __exportStar(require("./agents/guide-rail-agent.js"), exports);
 __exportStar(require("./agents/mcp-agent.js"), exports);
 __exportStar(require("./agents/team-agent.js"), exports);
+__exportStar(require("./agents/transform-agent.js"), exports);
 __exportStar(require("./agents/types.js"), exports);
 __exportStar(require("./agents/user-agent.js"), exports);
 __exportStar(require("./aigne/index.js"), exports);

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

@@ -1,7 +1,7 @@
 import { type ZodObject, type ZodType, z } from "zod";
-import { Agent, type Message } from "../agents/agent.js";
+import { Agent, type FunctionAgentFn } from "../agents/agent.js";
 export declare function loadAgentFromJsFile(path: string): Promise<Agent<any, any> | {
-    process: (args_0: Message) => Message;
+    process: FunctionAgentFn;
     name: string;
     description?: string | undefined;
     inputSchema?: ZodObject<Record<string, ZodType<any, z.ZodTypeDef, any>>, z.UnknownKeysParam, z.ZodTypeAny, {

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

@@ -32,27 +32,23 @@ var __importStar = (this && this.__importStar) || (function () {
         return result;
     };
 })();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.loadAgentFromJsFile = loadAgentFromJsFile;
 const json_schema_to_zod_1 = require("@aigne/json-schema-to-zod");
+const camelize_ts_1 = __importDefault(require("camelize-ts"));
 const zod_1 = require("zod");
 const agent_js_1 = require("../agents/agent.js");
-const camelize_js_1 = require("../utils/camelize.js");
 const type_utils_js_1 = require("../utils/type-utils.js");
 const schema_js_1 = require("./schema.js");
 const agentJsFileSchema = zod_1.z.object({
     name: zod_1.z.string(),
-    description: zod_1.z
-        .string()
-        .nullish()
-        .transform((v) => v ?? undefined),
-    input_schema: schema_js_1.inputOutputSchema
-        .nullish()
-        .transform((v) => (v ? (0, json_schema_to_zod_1.jsonSchemaToZod)(v) : undefined)),
-    output_schema: schema_js_1.inputOutputSchema
-        .nullish()
-        .transform((v) => (v ? (0, json_schema_to_zod_1.jsonSchemaToZod)(v) : undefined)),
-    process: zod_1.z.function(),
+    description: (0, schema_js_1.optionalize)(zod_1.z.string()),
+    inputSchema: (0, schema_js_1.optionalize)(schema_js_1.inputOutputSchema).transform((v) => v ? (0, json_schema_to_zod_1.jsonSchemaToZod)(v) : undefined),
+    outputSchema: (0, schema_js_1.optionalize)(schema_js_1.inputOutputSchema).transform((v) => v ? (0, json_schema_to_zod_1.jsonSchemaToZod)(v) : undefined),
+    process: zod_1.z.custom(),
 });
 async function loadAgentFromJsFile(path) {
     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}`));
@@ -61,9 +57,9 @@ async function loadAgentFromJsFile(path) {
     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)(() => (0, camelize_js_1.customCamelize)(agentJsFileSchema.parse({
+    return (0, type_utils_js_1.tryOrThrow)(() => agentJsFileSchema.parse((0, camelize_ts_1.default)({
         ...agent,
-        name: agent.agent_name || agent.name,
+        name: agent.agent_name || agent.agentName || agent.name,
         process: agent,
-    }), { shallowKeys: ["input_schema", "output_schema"] }), (error) => new Error(`Failed to parse agent from ${path}: ${error.message}`));
+    })), (error) => new Error(`Failed to parse agent from ${path}: ${error.message}`));
 }

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

@@ -1,48 +1,39 @@
-import { type ZodObject, type ZodType, z } from "zod";
+import { type ZodType } from "zod";
 import { AIAgentToolChoice } from "../agents/ai-agent.js";
 import { ProcessMode } from "../agents/team-agent.js";
-export declare function loadAgentFromYamlFile(path: string): Promise<{
+interface BaseAgentSchema {
+    name?: string;
+    description?: string;
+    inputSchema?: ZodType<Record<string, ZodType>>;
+    outputSchema?: ZodType<Record<string, ZodType>>;
+    skills?: (string | AgentSchema)[];
+    memory?: boolean | {
+        provider: string;
+        subscribeTopic?: string[];
+    };
+}
+interface AIAgentSchema extends BaseAgentSchema {
+    type: "ai";
+    instructions?: string;
+    inputKey?: string;
+    outputKey?: string;
+    toolChoice?: AIAgentToolChoice;
+}
+interface MCPAgentSchema {
     type: "mcp";
-    url?: string | undefined;
-    command?: string | undefined;
-    args?: string[] | undefined;
-} | {
+    url?: string;
+    command?: string;
+    args?: string[];
+}
+interface TeamAgentSchema extends BaseAgentSchema {
     type: "team";
-    name: string;
-    description?: string | undefined;
-    skills?: string[] | undefined;
-    mode?: ProcessMode | undefined;
-    inputSchema?: ZodObject<Record<string, ZodType<any, z.ZodTypeDef, any>>, z.UnknownKeysParam, z.ZodTypeAny, {
-        [x: string]: any;
-    }, {
-        [x: string]: any;
-    }> | undefined;
-    outputSchema?: ZodObject<Record<string, ZodType<any, z.ZodTypeDef, any>>, z.UnknownKeysParam, z.ZodTypeAny, {
-        [x: string]: any;
-    }, {
-        [x: string]: any;
-    }> | undefined;
-} | {
-    instructions: string | undefined;
-    type: "ai";
-    name: string;
-    description?: string | undefined;
-    skills?: string[] | undefined;
-    memory?: true | {
-        provider: string;
-        subscribeTopic?: string[] | undefined;
-    } | undefined;
-    inputSchema?: ZodObject<Record<string, ZodType<any, z.ZodTypeDef, any>>, z.UnknownKeysParam, z.ZodTypeAny, {
-        [x: string]: any;
-    }, {
-        [x: string]: any;
-    }> | undefined;
-    outputSchema?: ZodObject<Record<string, ZodType<any, z.ZodTypeDef, any>>, z.UnknownKeysParam, z.ZodTypeAny, {
-        [x: string]: any;
-    }, {
-        [x: string]: any;
-    }> | undefined;
-    inputKey?: string | undefined;
-    outputKey?: string | undefined;
-    toolChoice?: AIAgentToolChoice | undefined;
-}>;
+    mode?: ProcessMode;
+    iterateOn?: string;
+}
+interface TransformAgentSchema extends BaseAgentSchema {
+    type: "transform";
+    jsonata: string;
+}
+type AgentSchema = AIAgentSchema | MCPAgentSchema | TeamAgentSchema | TransformAgentSchema;
+export declare function loadAgentFromYamlFile(path: string): Promise<AgentSchema>;
+export {};