@aigne/core 1.73.0-beta → 1.74.0-beta

package/dist/agents/team-agent.cjs

@@ -0,0 +1,342 @@
+const require_rolldown_runtime = require('../_virtual/rolldown_runtime.cjs');
+const require_utils_type_utils = require('../utils/type-utils.cjs');
+const require_utils_stream_utils = require('../utils/stream-utils.cjs');
+const require_agent = require('./agent.cjs');
+const require_loader_schema = require('../loader/schema.cjs');
+const require_loader_agent_yaml = require('../loader/agent-yaml.cjs');
+const require_utils_queue = require('../utils/queue.cjs');
+let zod = require("zod");
+let node_assert = require("node:assert");
+node_assert = require_rolldown_runtime.__toESM(node_assert);
+let immer = require("immer");
+
+//#region src/agents/team-agent.ts
+/**
+* Defines the processing modes available for a TeamAgent.
+*
+* The processing mode determines how the agents within a team are executed
+* and how their outputs are combined.
+*/
+let ProcessMode = /* @__PURE__ */ function(ProcessMode) {
+	/**
+	* Process the agents one by one, passing the output of each agent to the next.
+	*
+	* In sequential mode, agents execute in order, with each agent receiving the
+	* combined output from all previous agents as part of its input.
+	*/
+	ProcessMode["sequential"] = "sequential";
+	/**
+	* Process all agents in parallel, merging the output of all agents.
+	*
+	* In parallel mode, all agents execute simultaneously, each receiving the same
+	* initial input. Their outputs are then combined based on output key ownership.
+	*/
+	ProcessMode["parallel"] = "parallel";
+	return ProcessMode;
+}({});
+const DEFAULT_REFLECTION_MAX_ITERATIONS = 3;
+/**
+* TeamAgent coordinates a group of agents working together to accomplish tasks.
+*
+* A TeamAgent manages a collection of agents (its skills) and orchestrates their
+* execution according to a specified processing mode. It provides mechanisms for
+* agents to work either sequentially (one after another) or in parallel (all at once),
+* with appropriate handling of their outputs.
+*
+* TeamAgent is particularly useful for:
+* - Creating agent workflows where output from one agent feeds into another
+* - Executing multiple agents simultaneously and combining their results
+* - Building complex agent systems with specialized components working together
+*
+* @example
+* Here's an example of creating a sequential TeamAgent:
+* {@includeCode ../../test/agents/team-agent.test.ts#example-team-agent-sequential}
+*/
+var TeamAgent = class TeamAgent extends require_agent.Agent {
+	tag = "TeamAgent";
+	static schema({ filepath }) {
+		const nestAgentSchema = require_loader_agent_yaml.getNestAgentSchema({ filepath });
+		return zod.z.object({
+			mode: require_loader_schema.optionalize(zod.z.nativeEnum(ProcessMode)),
+			iterateOn: require_loader_schema.optionalize(zod.z.string()),
+			concurrency: require_loader_schema.optionalize(zod.z.number().int().min(1)),
+			iterateWithPreviousOutput: require_loader_schema.optionalize(zod.z.boolean()),
+			includeAllStepsOutput: require_loader_schema.optionalize(zod.z.boolean()),
+			reflection: require_loader_schema.camelizeSchema(require_loader_schema.optionalize(zod.z.object({
+				reviewer: nestAgentSchema,
+				isApproved: zod.z.string(),
+				maxIterations: require_loader_schema.optionalize(zod.z.number().int().min(1)),
+				returnLastOnMaxIterations: require_loader_schema.optionalize(zod.z.boolean()),
+				customErrorMessage: require_loader_schema.optionalize(zod.z.string())
+			})))
+		});
+	}
+	static async load(options) {
+		const valid = await TeamAgent.schema({ filepath: options.filepath }).parseAsync(options.parsed);
+		return TeamAgent.from({
+			...options.parsed,
+			...valid,
+			reflection: valid.reflection && {
+				...valid.reflection,
+				reviewer: await options.options.loadNestAgent(options.filepath, valid.reflection.reviewer, options.options)
+			}
+		});
+	}
+	/**
+	* Create a TeamAgent from the provided options.
+	*
+	* @param options Configuration options for the TeamAgent
+	* @returns A new TeamAgent instance
+	*
+	* @example
+	* Here's an example of creating a sequential TeamAgent:
+	* {@includeCode ../../test/agents/team-agent.test.ts#example-team-agent-sequential}
+	*
+	* @example
+	* Here's an example of creating a parallel TeamAgent:
+	* {@includeCode ../../test/agents/team-agent.test.ts#example-team-agent-parallel}
+	*/
+	static from(options) {
+		return new TeamAgent(options);
+	}
+	/**
+	* Create a new TeamAgent instance.
+	*
+	* @param options Configuration options for the TeamAgent
+	*/
+	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.concurrency = options.concurrency ?? 1;
+		this.iterateWithPreviousOutput = options.iterateWithPreviousOutput;
+		this.includeAllStepsOutput = options.includeAllStepsOutput;
+		if (this.concurrency !== 1 && this.iterateWithPreviousOutput) throw new Error(`iterateWithPreviousOutput cannot be used with concurrency > 1, concurrency: ${this.concurrency}`);
+	}
+	/**
+	* The processing mode that determines how agents in the team are executed.
+	*
+	* 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.
+	*
+	* 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;
+	/**
+	* The maximum number of concurrent operations when processing array items.
+	*
+	* This property controls the concurrency level for iterative processing when `iterateOn`
+	* is used. It determines how many array elements are processed simultaneously.
+	*
+	* @see TeamAgentOptions.concurrency for detailed documentation
+	* @default 1
+	*/
+	concurrency;
+	/**
+	* 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;
+	/**
+	* Controls whether to include output from all intermediate steps in sequential processing.
+	*
+	* When `true`, yields output chunks from every agent in the sequential chain.
+	* When `false`, only yields output from the final agent.
+	*
+	* Only affects sequential processing mode. Useful for debugging and monitoring
+	* multi-step agent workflows.
+	*
+	* @default false
+	*/
+	includeAllStepsOutput;
+	/**
+	* Process an input message by routing it through the team's agents.
+	*
+	* Depending on the team's processing mode, this will either:
+	* - In sequential mode: Pass input through each agent in sequence, with each agent
+	*   receiving the combined output from previous agents
+	* - In parallel mode: Process input through all agents simultaneously and combine their outputs
+	*
+	* @param input The message to process
+	* @param options The invocation options
+	* @returns A stream of message chunks that collectively form the response
+	*/
+	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._processNonIterator(input, options);
+	}
+	async _processReflection(input, options) {
+		(0, node_assert.default)(this.reflection, "Reflection mode must be defined for reflection processing");
+		let iterations = 0;
+		const previousOutput = { ...input };
+		for (;;) {
+			const output = await require_agent.agentProcessResultToObject(await this._processNonReflection(previousOutput, options));
+			Object.assign(previousOutput, output);
+			const reviewOutput = await this.invokeChildAgent(this.reflection.reviewer, previousOutput, {
+				...options,
+				streaming: false
+			});
+			Object.assign(previousOutput, reviewOutput);
+			const { isApproved } = this.reflection;
+			if (typeof isApproved === "string" ? reviewOutput[isApproved] : await isApproved(reviewOutput)) return output;
+			if (++iterations >= this.reflection.maxIterations) {
+				if (this.reflection.returnLastOnMaxIterations) return output;
+				break;
+			}
+		}
+		throw new Error(this.reflection.customErrorMessage || `Reflection mode exceeded max iterations ${this.reflection.maxIterations}. Please review the feedback and try again.`);
+	}
+	async *_processIterator(key, input, options) {
+		(0, node_assert.default)(this.iterateOn, "iterateInputKey must be defined for iterator processing");
+		let arr = input[this.iterateOn];
+		arr = Array.isArray(arr) ? [...arr] : require_utils_type_utils.isNil(arr) ? [arr] : [];
+		const results = new Array(arr.length);
+		let error;
+		const queue = require_utils_queue.promise(async ({ item, index }) => {
+			try {
+				if (!require_utils_type_utils.isRecord(item)) throw new TypeError(`Expected ${String(key)} to be an object, got ${typeof item}`);
+				const res = require_utils_type_utils.omit(await require_agent.agentProcessResultToObject(await this._processNonIterator({
+					...input,
+					[key]: arr,
+					...item
+				}, {
+					...options,
+					streaming: false
+				})), key);
+				if (this.iterateWithPreviousOutput) arr = (0, immer.produce)(arr, (draft) => {
+					const item$1 = draft[index];
+					(0, node_assert.default)(item$1);
+					Object.assign(item$1, res);
+				});
+				results[index] = res;
+			} catch (e) {
+				error = e;
+				queue.killAndDrain();
+			}
+		}, this.concurrency);
+		for (let index = 0; index < arr.length; index++) queue.push({
+			index,
+			item: arr[index]
+		});
+		await queue.drained();
+		if (error) throw error;
+		yield { delta: { json: { [key]: results } } };
+	}
+	_processNonIterator(input, options) {
+		switch (this.mode) {
+			case ProcessMode.sequential: return this._processSequential(input, options);
+			case ProcessMode.parallel: return this._processParallel(input, options);
+		}
+	}
+	/**
+	* Process input sequentially through each agent in the team.
+	*
+	* This method:
+	* 1. Executes each agent in order
+	* 2. Passes the combined output from previous agents to the next agent
+	* 3. Yields output chunks as they become available
+	* 4. Updates the team's agent list with any changes that occurred during processing
+	*
+	* @param input The message to process
+	* @param options The invocation options
+	* @returns A stream of message chunks from all agents
+	*
+	* @private
+	*/
+	async *_processSequential(input, options) {
+		const output = {};
+		for (const agent of this.skills) {
+			const o = await this.invokeChildAgent(agent, {
+				...input,
+				...output
+			}, {
+				...options,
+				streaming: true
+			});
+			const isLast = agent === this.skills[this.skills.length - 1];
+			for await (const chunk of o) {
+				if (this.includeAllStepsOutput || isLast) yield chunk;
+				require_utils_stream_utils.mergeAgentResponseChunk(output, chunk);
+			}
+		}
+	}
+	/**
+	* Process input in parallel through all agents in the team.
+	*
+	* This method:
+	* 1. Executes all agents simultaneously with the same input
+	* 2. Yields combined output chunks
+	* 3. Updates the team's agent list with any changes that occurred during processing
+	*
+	* @param input The message to process
+	* @param options The invocation options
+	* @returns A stream of combined message chunks from all agents
+	*
+	* @private
+	*/
+	async *_processParallel(input, options) {
+		const streams = await Promise.all(this.skills.map((agent) => this.invokeChildAgent(agent, input, {
+			...options,
+			streaming: true
+		})));
+		const read = async (index, reader) => {
+			return reader.read().then((result) => ({
+				...result,
+				reader,
+				index
+			}));
+		};
+		const tasks = new Map(streams.map((stream, index) => [index, read(index, stream.getReader())]));
+		const outputKeyUsed = /* @__PURE__ */ new Map();
+		while (tasks.size) {
+			const { value, done, reader, index } = await Promise.race(tasks.values());
+			tasks.delete(index);
+			if (!done) tasks.set(index, read(index, reader));
+			if (value && require_agent.isAgentResponseDelta(value)) {
+				let { delta: { text, ...delta } } = value;
+				if (text) {
+					for (const key of Object.keys(text)) if (!outputKeyUsed.has(key)) outputKeyUsed.set(key, index);
+					else if (outputKeyUsed.get(key) !== index) delete text[key];
+					if (require_utils_type_utils.isEmpty(text)) text = void 0;
+				}
+				if (!require_utils_type_utils.isEmpty(delta.json) || !require_utils_type_utils.isEmpty(text)) yield { delta: {
+					...delta,
+					text
+				} };
+			}
+		}
+	}
+};
+
+//#endregion
+exports.DEFAULT_REFLECTION_MAX_ITERATIONS = DEFAULT_REFLECTION_MAX_ITERATIONS;
+exports.ProcessMode = ProcessMode;
+exports.TeamAgent = TeamAgent;