@aigne/core 1.72.0 → 1.74.0-beta

package/dist/agents/agent.cjs

@@ -0,0 +1,874 @@
+const require_rolldown_runtime = require('../_virtual/rolldown_runtime.cjs');
+const require_loader_function_agent = require('../loader/function-agent.cjs');
+const require_utils_agent_utils = require('../utils/agent-utils.cjs');
+const require_utils_logger = require('../utils/logger.cjs');
+const require_utils_type_utils = require('../utils/type-utils.cjs');
+const require_utils_json_schema = require('../utils/json-schema.cjs');
+const require_utils_stream_utils = require('../utils/stream-utils.cjs');
+const require_types = require('./types.cjs');
+let _aigne_afs = require("@aigne/afs");
+let _aigne_utils_nodejs = require("@aigne/utils/nodejs");
+let fast_deep_equal = require("fast-deep-equal");
+fast_deep_equal = require_rolldown_runtime.__toESM(fast_deep_equal);
+let nunjucks = require("nunjucks");
+nunjucks = require_rolldown_runtime.__toESM(nunjucks);
+let ufo = require("ufo");
+let yaml = require("yaml");
+let zod = require("zod");
+let zod_to_json_schema = require("zod-to-json-schema");
+
+//#region src/agents/agent.ts
+const DEFAULT_INPUT_ACTION_GET = "$get";
+const DEFAULT_RETRIES = 3;
+const DEFAULT_RETRY_MIN_TIMEOUT = 1e3;
+const DEFAULT_RETRY_FACTOR = 2;
+const hooksSchema = zod.z.object({
+	onStart: zod.z.custom().optional(),
+	onEnd: zod.z.custom().optional(),
+	onSkillStart: zod.z.custom().optional(),
+	onSkillEnd: zod.z.custom().optional(),
+	onHandoff: zod.z.custom().optional()
+});
+const agentOptionsSchema = zod.z.object({
+	subscribeTopic: zod.z.union([zod.z.string(), zod.z.array(zod.z.string())]).optional(),
+	publishTopic: zod.z.union([
+		zod.z.string(),
+		zod.z.array(zod.z.string()),
+		zod.z.custom()
+	]).optional(),
+	name: zod.z.string().optional(),
+	description: zod.z.string().optional(),
+	inputSchema: zod.z.custom().optional(),
+	defaultInput: zod.z.record(zod.z.any()).optional(),
+	outputSchema: zod.z.custom().optional(),
+	includeInputInOutput: zod.z.boolean().optional(),
+	skills: zod.z.array(zod.z.union([zod.z.custom(), zod.z.custom()])).optional(),
+	disableEvents: zod.z.boolean().optional(),
+	memory: zod.z.union([zod.z.custom(), zod.z.array(zod.z.custom())]).optional(),
+	asyncMemoryRecord: zod.z.boolean().optional(),
+	maxRetrieveMemoryCount: zod.z.number().optional(),
+	hooks: zod.z.union([zod.z.array(hooksSchema), hooksSchema]).optional(),
+	guideRails: zod.z.array(zod.z.custom()).optional(),
+	retryOnError: zod.z.union([zod.z.boolean(), zod.z.object({
+		retries: zod.z.number().int().min(0),
+		minTimeout: zod.z.number().min(0).optional(),
+		factor: zod.z.number().min(1).optional(),
+		randomize: zod.z.boolean().optional(),
+		shouldRetry: zod.z.custom().optional()
+	})]).optional()
+});
+/**
+* Agent is the base class for all agents.
+* It provides a mechanism for defining input/output schemas and implementing processing logic,
+* serving as the foundation of the entire agent system.
+*
+* By extending the Agent class and implementing the process method, you can create custom agents
+* with various capabilities:
+* - Process structured input and output data
+* - Validate data formats using schemas
+* - Communicate between agents through contexts
+* - Support streaming or non-streaming responses
+* - Maintain memory of past interactions
+* - Output in multiple formats (JSON/text)
+* - Forward tasks to other agents
+*
+* @template I The input message type the agent accepts
+* @template O The output message type the agent returns
+*
+* @example
+* Here's an example of how to create a custom agent:
+* {@includeCode ../../test/agents/agent.test.ts#example-custom-agent}
+*/
+var Agent = class Agent {
+	static async load(_options) {
+		throw new Error("Not implemented");
+	}
+	constructor(options = {}) {
+		require_utils_type_utils.checkArguments("Agent options", agentOptionsSchema, options);
+		const { inputSchema, outputSchema } = options;
+		this.name = options.name || this.constructor.name;
+		this.alias = options.alias;
+		this.description = options.description;
+		this.model = options.model;
+		this.imageModel = options.imageModel;
+		this.taskTitle = options.taskTitle;
+		this.taskRenderMode = options.taskRenderMode;
+		if (inputSchema) checkAgentInputOutputSchema(inputSchema);
+		if (outputSchema) checkAgentInputOutputSchema(outputSchema);
+		this._inputSchema = inputSchema;
+		this.defaultInput = options.defaultInput;
+		this._outputSchema = outputSchema;
+		this.includeInputInOutput = options.includeInputInOutput;
+		this.subscribeTopic = options.subscribeTopic;
+		this.publishTopic = options.publishTopic;
+		if (options.skills?.length) this.skills.push(...options.skills.map(functionToAgent));
+		this.disableEvents = options.disableEvents;
+		if (Array.isArray(options.memory)) this.memories.push(...options.memory);
+		else if (options.memory) this.memories.push(options.memory);
+		this.afs = !options.afs ? void 0 : options.afs === true ? new _aigne_afs.AFS() : typeof options.afs === "function" ? options.afs(new _aigne_afs.AFS()) : options.afs instanceof _aigne_afs.AFS ? options.afs : new _aigne_afs.AFS(options.afs);
+		this.asyncMemoryRecord = options.asyncMemoryRecord;
+		this.maxRetrieveMemoryCount = options.maxRetrieveMemoryCount;
+		this.hooks = require_utils_type_utils.flat(options.hooks);
+		this.retryOnError = options.retryOnError === false ? void 0 : options.retryOnError === true ? { retries: DEFAULT_RETRIES } : options.retryOnError;
+		this.guideRails = options.guideRails;
+	}
+	afs;
+	tag;
+	/**
+	* List of memories this agent can use
+	*
+	* @deprecated use afs instead
+	*/
+	memories = [];
+	asyncMemoryRecord;
+	/**
+	* Maximum number of memory items to retrieve
+	*/
+	maxRetrieveMemoryCount;
+	/**
+	* Lifecycle hooks for agent processing.
+	*
+	* Hooks enable tracing, logging, monitoring, and custom behavior
+	* without modifying the core agent implementation
+	*
+	* @example
+	* Here's an example of using hooks:
+	* {@includeCode ../../test/agents/agent.test.ts#example-agent-hooks}
+	*/
+	hooks;
+	retryOnError;
+	/**
+	* List of GuideRail agents applied to this agent
+	*
+	* GuideRail agents validate, transform, or control the message flow by:
+	* - Enforcing rules and safety policies
+	* - Validating inputs/outputs against specific criteria
+	* - Implementing business logic validations
+	* - Monitoring and auditing agent behavior
+	*
+	* Each GuideRail agent can examine both input and expected output,
+	* and has the ability to abort the process with an explanation
+	*
+	* @example
+	* Here's an example of using GuideRail agents:
+	*
+	* {@includeCode ../../test/agents/agent.test.ts#example-agent-guide-rails}
+	*/
+	guideRails;
+	/**
+	* Name of the agent, used for identification and logging
+	*
+	* Defaults to the class constructor name if not specified in options
+	*/
+	name;
+	/**
+	* Alias for the agent, can be used to refer to the agent by multiple names, especially in AIGNE CLI
+	*/
+	alias;
+	/**
+	* Default topic this agent subscribes to
+	*
+	* Each agent has a default topic in the format "$agent_[agent name]"
+	* The agent automatically subscribes to this topic to receive messages
+	*
+	* @returns The default topic string
+	*/
+	get topic() {
+		return `$agent_${this.name}`;
+	}
+	/**
+	* Description of the agent's purpose and capabilities
+	*
+	* Useful for documentation and when agents need to understand
+	* each other's roles in a multi-agent system
+	*/
+	description;
+	model;
+	imageModel;
+	taskTitle;
+	async renderTaskTitle(input) {
+		if (!this.taskTitle) return;
+		const s = typeof this.taskTitle === "function" ? await this.taskTitle(input) : this.taskTitle;
+		if (!s) return;
+		return nunjucks.default.renderString(s, { ...input });
+	}
+	taskRenderMode;
+	_inputSchema;
+	defaultInput;
+	_outputSchema;
+	/**
+	* Get the input data schema for this agent
+	*
+	* Used to validate that input messages conform to required format
+	* If no input schema is set, returns an empty object schema by default
+	*
+	* @returns The Zod type definition for input data
+	*/
+	get inputSchema() {
+		const s = this._inputSchema;
+		const schema = typeof s === "function" ? s(this) : s || zod.z.object({});
+		checkAgentInputOutputSchema(schema);
+		return schema.passthrough();
+	}
+	get inputKeys() {
+		return require_utils_json_schema.getZodObjectKeys(this.inputSchema);
+	}
+	/**
+	* Get the output data schema for this agent
+	*
+	* Used to validate that output messages conform to required format
+	* If no output schema is set, returns an empty object schema by default
+	*
+	* @returns The Zod type definition for output data
+	*/
+	get outputSchema() {
+		const s = this._outputSchema;
+		const schema = typeof s === "function" ? s(this) : s || zod.z.object({});
+		checkAgentInputOutputSchema(schema);
+		return schema.passthrough();
+	}
+	get outputKeys() {
+		return require_utils_json_schema.getZodObjectKeys(this.outputSchema);
+	}
+	/**
+	* Whether to include the original input in the output
+	*
+	* When true, the agent will merge input fields into the output object
+	*/
+	includeInputInOutput;
+	/**
+	* Topics the agent subscribes to for receiving messages
+	*
+	* Can be a single topic string or an array of topic strings
+	*/
+	subscribeTopic;
+	/**
+	* Topics the agent publishes to for sending messages
+	*
+	* Can be a string, array of strings, or a function that determines
+	* topics based on the output
+	*/
+	publishTopic;
+	/**
+	* Collection of skills (other agents) this agent can use
+	*
+	* Skills can be accessed by name or by array index, allowing
+	* the agent to delegate tasks to specialized sub-agents
+	*/
+	skills = require_utils_type_utils.createAccessorArray([], (arr, name) => arr.find((t) => t.name === name));
+	/**
+	* Whether to disable emitting events for agent actions
+	*
+	* When true, the agent won't emit events like agentStarted,
+	* agentSucceed, or agentFailed
+	*/
+	disableEvents;
+	subscriptions = [];
+	/**
+	* Attach agent to context:
+	* - Subscribe to topics and invoke process method when messages are received
+	* - Subscribe to memory topics if memory is enabled
+	*
+	* Agents can receive messages and respond through the topic subscription system,
+	* enabling inter-agent communication.
+	*
+	* @param context Context to attach to
+	*/
+	attach(context) {
+		for (const memory of this.memories) memory.attach(context);
+		this.subscribeToTopics(context);
+	}
+	subscribeToTopics(context) {
+		for (const topic of require_utils_type_utils.flat(this.subscribeTopic).concat(this.topic)) this.subscriptions.push(context.subscribe(topic, (payload) => this.onMessage(payload)));
+	}
+	async onMessage({ message, context }) {
+		try {
+			await context.invoke(this, message, { newContext: false });
+		} catch (error) {
+			context.emit("agentFailed", {
+				agent: this,
+				error
+			});
+		}
+	}
+	/**
+	* Add skills (other agents or functions) to this agent
+	*
+	* Skills allow agents to reuse functionality from other agents,
+	* building more complex behaviors.
+	*
+	* @param skills List of skills to add, can be Agent instances or functions
+	*/
+	addSkill(...skills) {
+		this.skills.push(...skills.map((skill) => typeof skill === "function" ? functionToAgent(skill) : skill));
+	}
+	/**
+	* Check if the agent is invokable
+	*
+	* An agent is invokable if it has implemented the process method
+	*/
+	get isInvokable() {
+		return !!this.process;
+	}
+	/**
+	* Check context status to ensure it hasn't timed out
+	*
+	* @param options Invocation options containing context
+	* @throws Error if the context has timed out
+	*/
+	checkContextStatus(options) {
+		const { status } = options.context;
+		if (status === "timeout") throw new Error(`AIGNE for agent ${this.name} has timed out`);
+	}
+	async newDefaultContext() {
+		return Promise.resolve().then(() => require("../aigne/context.cjs")).then((m) => new m.AIGNEContext());
+	}
+	async retrieveMemories(input, options) {
+		const memories = [];
+		for (const memory of this.memories) {
+			const ms = (await memory.retrieve({
+				...input,
+				limit: input.limit ?? this.maxRetrieveMemoryCount
+			}, options.context)).memories;
+			memories.push(...ms);
+		}
+		return memories;
+	}
+	async recordMemories(input, options) {
+		for (const memory of this.memories) if (memory.autoUpdate) await memory.record(input, options.context);
+	}
+	async invoke(input, options = {}) {
+		const opts = {
+			...options,
+			context: options.context ?? await this.newDefaultContext()
+		};
+		input = this.mergeDefaultInput(input);
+		require_utils_logger.logger.debug("Invoke agent %s started with input: %O", this.name, input);
+		if (!this.disableEvents) opts.context.emit("agentStarted", {
+			agent: this,
+			input,
+			taskTitle: await this.renderTaskTitle(input)
+		});
+		try {
+			const s = await this.callHooks("onStart", { input }, opts);
+			if (s?.input) input = s.input;
+			if (s?.options) Object.assign(opts, s.options);
+			input = require_utils_type_utils.checkArguments(`Agent ${this.name} input`, this.inputSchema, input);
+			await this.preprocess(input, opts);
+			this.checkContextStatus(opts);
+			const response = require_utils_stream_utils.asyncGeneratorToReadableStream(this.processStreamingAndRetry(input, opts));
+			return await this.checkResponseByGuideRails(input, options.streaming ? response : await agentProcessResultToObject(response), opts);
+		} catch (error) {
+			throw (await this.processAgentError(input, error, opts)).error ?? error;
+		}
+	}
+	async *processStreamingAndRetry(input, options) {
+		let output = {};
+		let attempt = 0;
+		for (;;) {
+			const resetOutput = Object.fromEntries(Object.entries(output).map(([key]) => [key, null]));
+			if (!require_utils_type_utils.isEmpty(resetOutput)) {
+				yield { delta: { json: resetOutput } };
+				output = {};
+			}
+			try {
+				let response = await this.process(input, options);
+				if (response instanceof Agent) response = require_types.transferToAgentOutput(response);
+				const stream = response instanceof ReadableStream ? response : require_utils_stream_utils.isAsyncGenerator(response) ? require_utils_stream_utils.asyncGeneratorToReadableStream(response) : require_utils_stream_utils.objectToAgentResponseStream(response);
+				const messages = [];
+				for await (const chunk of stream) {
+					require_utils_stream_utils.mergeAgentResponseChunk(output, chunk);
+					yield chunk;
+					if (isAgentResponseProgress(chunk) && chunk.progress.event === "message") messages.push(chunk.progress.message);
+				}
+				let result = await this.processAgentOutput(input, output, {
+					...options,
+					messages
+				});
+				if (attempt > 0) result = {
+					...result,
+					$meta: {
+						...result.$meta,
+						retries: attempt
+					}
+				};
+				if (result && !(0, fast_deep_equal.default)(result, output)) yield { delta: { json: result } };
+				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))) {
+						attempt++;
+						const timeout = minTimeout * factor ** (attempt - 1) * (randomize ? 1 + Math.random() : 1);
+						require_utils_logger.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) {
+					const e = res.error ?? error;
+					if (attempt > 0) e.message += ` (after ${attempt + 1} retries)`;
+					throw e;
+				}
+			}
+		}
+	}
+	async callHooks(hook, input, options) {
+		const { context } = options;
+		const result = {};
+		const hs = require_utils_type_utils.flat(hook);
+		const hooks = require_utils_agent_utils.sortHooks(require_utils_type_utils.flat(options.hooks, options.context.hooks, this.hooks)).flatMap((hooks$1) => hs.map((h) => hooks$1[h])).filter(require_utils_type_utils.isNonNullable);
+		for (const h of hooks) {
+			if (typeof h === "function") Object.assign(result, await h({
+				...input,
+				context,
+				agent: this
+			}));
+			else Object.assign(result, await context.invoke(h, {
+				...input,
+				agent: this
+			}));
+			if ("retry" in result && result.retry) return result;
+		}
+		return result;
+	}
+	mergeDefaultInput(input) {
+		input = {
+			...Object.fromEntries(Object.entries(this.defaultInput ?? {}).filter(([, v]) => !(typeof v === "object" && DEFAULT_INPUT_ACTION_GET in v))),
+			...input
+		};
+		for (const key of Object.keys(this.defaultInput ?? {})) {
+			const v = this.defaultInput?.[key];
+			if (v && typeof v === "object" && DEFAULT_INPUT_ACTION_GET in v && typeof v[DEFAULT_INPUT_ACTION_GET] === "string" && require_utils_type_utils.isNil(input[key])) {
+				const value = input[v[DEFAULT_INPUT_ACTION_GET]];
+				if (!require_utils_type_utils.isNil(value)) Object.assign(input, { [key]: value });
+			}
+		}
+		return input;
+	}
+	async invokeSkill(skill, input, options) {
+		await this.callHooks("onSkillStart", {
+			skill,
+			input
+		}, options);
+		try {
+			const output = await this.invokeChildAgent(skill, input, {
+				...options,
+				streaming: false
+			});
+			await this.callHooks("onSkillEnd", {
+				skill,
+				input,
+				output
+			}, options);
+			return output;
+		} catch (error) {
+			await this.callHooks("onSkillEnd", {
+				skill,
+				input,
+				error
+			}, options);
+			throw error;
+		}
+	}
+	invokeChildAgent = ((agent, input, options) => {
+		return options.context.invoke(agent, input, {
+			...options,
+			model: this.model || options.model,
+			imageModel: this.imageModel || options.imageModel,
+			caller: this
+		});
+	});
+	/**
+	* Process agent output
+	*
+	* Validates output format, applies post-processing operations, and triggers success events
+	*
+	* @param input Original input message
+	* @param output Raw output produced by the agent
+	* @param options Invocation options
+	* @returns Final processed output
+	*/
+	async processAgentOutput(input, output, { messages, ...options }) {
+		const { context } = options;
+		if (!require_utils_type_utils.isRecord(output)) throw new Error(`expect to return a record type such as {result: ...}, but got (${typeof output}): ${output}`);
+		const parsedOutput = require_utils_type_utils.checkArguments(`Agent ${this.name} output`, this.outputSchema, output);
+		let finalOutput = this.includeInputInOutput ? {
+			...input,
+			...parsedOutput
+		} : parsedOutput;
+		await this.postprocess(input, finalOutput, options);
+		require_utils_logger.logger.debug("Invoke agent %s succeed with output: %O", this.name, finalOutput);
+		const o = await this.callHooks(["onSuccess", "onEnd"], {
+			input,
+			output: finalOutput
+		}, options);
+		if (o?.output) finalOutput = o.output;
+		this.afs?.emit("agentSucceed", {
+			agentId: this.name,
+			userId: context.userContext.userId,
+			sessionId: context.userContext.sessionId,
+			input,
+			output: finalOutput,
+			messages
+		});
+		if (!this.disableEvents) context.emit("agentSucceed", {
+			agent: this,
+			output: finalOutput
+		});
+		return finalOutput;
+	}
+	/**
+	* Process errors that occur during agent execution
+	*
+	* Logs error information, triggers failure events, and re-throws the error
+	*
+	* @param error Caught error
+	* @param options Invocation options
+	*/
+	async processAgentError(input, error, options) {
+		require_utils_logger.logger.error("Invoke agent %s failed with error: %O", this.name, error);
+		const res = await this.callHooks(["onError", "onEnd"], {
+			input,
+			error
+		}, options) ?? {};
+		if (!res.retry) {
+			if (!this.disableEvents) options.context.emit("agentFailed", {
+				agent: this,
+				error
+			});
+		}
+		return { ...res };
+	}
+	/**
+	* Check agent invocation usage to prevent exceeding limits
+	*
+	* If the context has a maximum invocation limit set, checks if the limit
+	* has been exceeded and increments the invocation counter
+	*
+	* @param options Invocation options containing context and limits
+	* @throws Error if maximum invocation limit is exceeded
+	*/
+	checkAgentInvokesUsage(options) {
+		const { limits, usage } = options.context;
+		if (limits?.maxAgentInvokes && usage.agentCalls >= limits.maxAgentInvokes) throw new Error(`Exceeded max agent invokes ${usage.agentCalls}/${limits.maxAgentInvokes}`);
+		usage.agentCalls++;
+	}
+	/**
+	* Pre-processing operations before handling input
+	*
+	* Preparatory work done before executing the agent's main processing logic, including:
+	* - Checking context status
+	* - Verifying invocation limits
+	*
+	* @param _ Input message (unused)
+	* @param options Options for agent invocation
+	*/
+	async preprocess(_, options) {
+		this.checkContextStatus(options);
+		this.checkAgentInvokesUsage(options);
+	}
+	async checkResponseByGuideRails(input, output, options) {
+		if (!this.guideRails?.length) return output;
+		const result = await output;
+		if (result instanceof ReadableStream) return require_utils_stream_utils.onAgentResponseStreamEnd(result, { onResult: async (result$1) => {
+			const error$1 = await this.runGuideRails(input, result$1, options);
+			if (error$1) return {
+				...await this.onGuideRailError(error$1),
+				$status: "GuideRailError"
+			};
+		} });
+		const error = await this.runGuideRails(input, result, options);
+		if (!error) return output;
+		return {
+			...await this.onGuideRailError(error),
+			$status: "GuideRailError"
+		};
+	}
+	async runGuideRails(input, output, options) {
+		return (await Promise.all((this.guideRails ?? []).map((i) => this.invokeChildAgent(i, {
+			input,
+			output
+		}, {
+			...options,
+			streaming: false
+		})))).find((i) => !!i.abort);
+	}
+	/**
+	* Handle errors detected by GuideRail agents
+	*
+	* This method is called when a GuideRail agent aborts the process, providing
+	* a way for agents to customize error handling behavior. By default, it simply
+	* returns the original error, but subclasses can override this method to:
+	* - Transform the error into a more specific response
+	* - Apply recovery strategies
+	* - Log or report the error in a custom format
+	* - Return a fallback output instead of an error
+	*
+	* @param error The GuideRail agent output containing abort=true and a reason
+	* @returns Either the original/modified error or a substitute output object
+	*          which will be tagged with $status: "GuideRailError"
+	*/
+	async onGuideRailError(error) {
+		return error;
+	}
+	/**
+	* Post-processing operations after handling output
+	*
+	* Operations performed after the agent produces output, including:
+	* - Checking context status
+	* - Adding interaction records to memory
+	*
+	* @param input Input message
+	* @param output Output message
+	* @param options Options for agent invocation
+	*/
+	async postprocess(input, output, options) {
+		this.checkContextStatus(options);
+		this.publishToTopics(output, options);
+		const memory = this.recordMemories({ content: [{
+			input,
+			output: require_types.replaceTransferAgentToName(output),
+			source: this.name
+		}] }, options).catch((error) => {
+			require_utils_logger.logger.error(`Agent ${this.name} failed to record memories:`, error);
+		});
+		if (!this.asyncMemoryRecord) await memory;
+	}
+	async publishToTopics(output, options) {
+		const publishTopics = typeof this.publishTopic === "function" ? await this.publishTopic(output) : this.publishTopic;
+		const role = this.constructor.name === "UserAgent" ? "user" : "agent";
+		if (publishTopics?.length) (role === "user" ? options.context.newContext({ reset: true }) : options.context).publish(publishTopics, {
+			role,
+			source: this.name,
+			message: output
+		}, { newContext: role !== "user" });
+	}
+	formatOutput(output) {
+		return (0, yaml.stringify)(output);
+	}
+	/**
+	* Shut down the agent and clean up resources
+	*
+	* Primarily used to clean up memory and other resources to prevent memory leaks
+	*
+	* @example
+	* Here's an example of shutting down an agent:
+	* {@includeCode ../../test/agents/agent.test.ts#example-agent-shutdown}
+	*
+	* @example
+	* Here's an example of shutting down an agent by using statement:
+	* {@includeCode ../../test/agents/agent.test.ts#example-agent-shutdown-by-using}
+	*/
+	async shutdown() {
+		for (const sub of this.subscriptions) sub();
+		this.subscriptions = [];
+		for (const m of this.memories) m.shutdown();
+	}
+	/**
+	* Custom object inspection behavior
+	*
+	* When using Node.js's util.inspect function to inspect an agent,
+	* only the agent's name will be shown, making output more concise
+	*
+	* @returns Agent name
+	*/
+	[_aigne_utils_nodejs.nodejs.customInspect]() {
+		return this.name;
+	}
+	/**
+	* Async dispose method for shutdown the agent
+	*
+	* @example
+	* Here's an example of shutting down an agent by using statement:
+	* {@includeCode ../../test/agents/agent.test.ts#example-agent-shutdown-by-using}
+	*/
+	async [Symbol.asyncDispose]() {
+		await this.shutdown();
+	}
+	/** For AFSModule interface **/
+	agentToAFSEntry(agent) {
+		return {
+			id: `/${this.name}/${agent.name}`,
+			path: agent === this ? "/" : (0, ufo.joinURL)("/", agent.name),
+			summary: agent.description,
+			metadata: { execute: agent.isInvokable ? {
+				name: agent.name,
+				description: agent.description,
+				inputSchema: (0, zod_to_json_schema.zodToJsonSchema)(agent.inputSchema),
+				outputSchema: (0, zod_to_json_schema.zodToJsonSchema)(agent.outputSchema)
+			} : void 0 }
+		};
+	}
+	findAgentByAFSPath(path) {
+		let agent;
+		if (path === "/") agent = this;
+		else {
+			const name = path.split("/")[1];
+			agent = this.skills.find((s) => s.name === name);
+		}
+		return agent;
+	}
+	async list(_path, _options) {
+		return { data: [this, ...this.skills].map((agent) => this.agentToAFSEntry(agent)) };
+	}
+	async read(path) {
+		const agent = this.findAgentByAFSPath(path);
+		if (!agent) return { message: `Agent not found at path: ${path}` };
+		return { data: this.agentToAFSEntry(agent) };
+	}
+	async search(path, _query, options) {
+		return this.list(path, options);
+	}
+	async exec(path, args, options) {
+		const agent = this.findAgentByAFSPath(path);
+		if (!agent) throw new Error(`Agent not found at path: ${path}`);
+		return { data: await options.context.invoke(agent, args) };
+	}
+};
+/**
+* Check if a response chunk is empty
+*
+* @template T Response data type
+* @param chunk The response chunk to check
+* @returns True if the chunk is empty
+*/
+function isEmptyChunk(chunk) {
+	return isAgentResponseDelta(chunk) && require_utils_type_utils.isEmpty(chunk.delta.json) && require_utils_type_utils.isEmpty(chunk.delta.text);
+}
+function isAgentResponseDelta(chunk) {
+	return "delta" in chunk;
+}
+function isAgentResponseProgress(chunk) {
+	return "progress" in chunk;
+}
+/**
+* Creates a text delta for streaming responses
+*
+* This utility function creates an AgentResponseDelta object with only the text part,
+* useful for incrementally building streaming text responses in agents.
+*
+* @template T Agent message type extending Message
+* @param textDelta The text content to include in the delta update
+* @returns An AgentResponseDelta with the text delta wrapped in the expected structure
+*/
+function textDelta(textDelta) {
+	return { delta: { text: textDelta } };
+}
+/**
+* Creates a JSON delta for streaming responses
+*
+* This utility function creates an AgentResponseDelta object with only the JSON part,
+* useful for incrementally building structured data responses in streaming mode.
+*
+* @template T Agent message type extending Message
+* @param jsonDelta The JSON data to include in the delta update
+* @returns An AgentResponseDelta with the JSON delta wrapped in the expected structure
+*/
+function jsonDelta(jsonDelta) {
+	return { delta: { json: jsonDelta } };
+}
+async function agentProcessResultToObject(response) {
+	return response instanceof ReadableStream ? await require_utils_stream_utils.agentResponseStreamToObject(response) : require_utils_stream_utils.isAsyncGenerator(response) ? await require_utils_stream_utils.agentResponseStreamToObject(response) : response;
+}
+function checkAgentInputOutputSchema(schema) {
+	if (typeof schema !== "function" && !require_utils_json_schema.isZodSchema(schema)) throw new Error(`schema must be a zod object or function return a zod object, got: ${typeof schema}`);
+}
+/**
+* Function agent class, implements agent logic through a function
+*
+* Provides a convenient way to create agents using functions without
+* needing to extend the Agent class
+*
+* @template I Agent input message type
+* @template O Agent output message type
+*
+* @example
+* Here's an example of creating a function agent:
+* {@includeCode ../../test/agents/agent.test.ts#example-function-agent}
+*/
+var FunctionAgent = class FunctionAgent extends Agent {
+	tag = "FunctionAgent";
+	static schema() {
+		return zod.z.object({ process: zod.z.preprocess((v) => typeof v === "string" ? require_loader_function_agent.codeToFunctionAgentFn(v) : v, zod.z.custom()) });
+	}
+	static async load(options) {
+		const valid = await FunctionAgent.schema().parseAsync(options.parsed);
+		return new FunctionAgent({
+			...options.parsed,
+			process: valid.process
+		});
+	}
+	/**
+	* Create a function agent from a function or options
+	*
+	* Provides a convenient factory method to create an agent directly from a function
+	*
+	* @param options Function agent options or function
+	* @returns New function agent instance
+	*
+	* @example
+	* Here's an example of creating a function agent from a function:
+	* {@includeCode ../../test/agents/agent.test.ts#example-function-agent-from-function}
+	*
+	* @example
+	* Here's an example of creating a function agent without basic agent options:
+	* {@includeCode ../../test/agents/agent.test.ts#example-function-agent}
+	*
+	* @example
+	* Here's an example of creating a function agent from a function returning a stream:
+	* {@includeCode ../../test/agents/agent.test.ts#example-function-agent-stream}
+	*
+	* @example
+	* Here's an example of creating a function agent from a function returning an async generator:
+	* {@includeCode ../../test/agents/agent.test.ts#example-function-agent-async-generator}
+	*/
+	static from(options) {
+		return typeof options === "function" ? functionToAgent(options) : new FunctionAgent(options);
+	}
+	/**
+	* Create a function agent instance
+	*
+	* @param options Function agent configuration options
+	*/
+	constructor(options) {
+		super(options);
+		this._process = options.process;
+	}
+	/**
+	* Stores the function used to process agent input and generate output
+	*
+	* @private
+	*/
+	_process;
+	/**
+	* Process input implementation, calls the configured processing function
+	*
+	* @param input Input message
+	* @param options Invocation options
+	* @returns Processing result
+	*/
+	process(input, options) {
+		return this._process.apply(this, [input, options]);
+	}
+};
+function functionToAgent(agent) {
+	if (typeof agent === "function") return FunctionAgent.from({
+		name: agent.name,
+		process: agent
+	});
+	return agent;
+}
+
+//#endregion
+exports.Agent = Agent;
+exports.DEFAULT_INPUT_ACTION_GET = DEFAULT_INPUT_ACTION_GET;
+exports.FunctionAgent = FunctionAgent;
+exports.agentOptionsSchema = agentOptionsSchema;
+exports.agentProcessResultToObject = agentProcessResultToObject;
+exports.isAgentResponseDelta = isAgentResponseDelta;
+exports.isAgentResponseProgress = isAgentResponseProgress;
+exports.isEmptyChunk = isEmptyChunk;
+exports.jsonDelta = jsonDelta;
+exports.textDelta = textDelta;