@aigne/core 1.73.0-beta → 1.74.0-beta

package/dist/agents/ai-agent.cjs

@@ -0,0 +1,524 @@
+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_types = require('./types.cjs');
+const require_agent = require('./agent.cjs');
+const require_model = require('./model.cjs');
+const require_agent_skill = require('../prompt/skills/afs/agent-skill/agent-skill.cjs');
+const require_structured_stream_instructions = require('../prompt/prompts/structured-stream-instructions.cjs');
+const require_prompt_builder = require('../prompt/prompt-builder.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');
+const require_utils_structured_stream_extractor = require('../utils/structured-stream-extractor.cjs');
+let zod = require("zod");
+
+//#region src/agents/ai-agent.ts
+const DEFAULT_OUTPUT_KEY = "message";
+const DEFAULT_OUTPUT_FILE_KEY = "files";
+/**
+* Tool choice options for AI agents
+*
+* Controls how the agent decides to use tools during execution
+*/
+let AIAgentToolChoice = /* @__PURE__ */ function(AIAgentToolChoice) {
+	/**
+	* Let the model decide when to use tools
+	*/
+	AIAgentToolChoice["auto"] = "auto";
+	/**
+	* Disable tool usage
+	*/
+	AIAgentToolChoice["none"] = "none";
+	/**
+	* Force tool usage
+	*/
+	AIAgentToolChoice["required"] = "required";
+	/**
+	* Choose exactly one tool and route directly to it
+	*/
+	AIAgentToolChoice["router"] = "router";
+	return AIAgentToolChoice;
+}({});
+/**
+* Zod schema for validating AIAgentToolChoice values
+*
+* Used to ensure that toolChoice receives valid values
+*
+* @hidden
+*/
+const aiAgentToolChoiceSchema = zod.z.union([zod.z.nativeEnum(AIAgentToolChoice), zod.z.custom()], { message: `aiAgentToolChoice must be ${Object.values(AIAgentToolChoice).join(", ")}, or an Agent` });
+/**
+* Zod schema for validating AIAgentOptions
+*
+* Extends the base agent options schema with AI-specific parameters
+*
+* @hidden
+*/
+const aiAgentOptionsSchema = require_agent.agentOptionsSchema.extend({
+	model: zod.z.custom().optional(),
+	instructions: zod.z.union([zod.z.string(), zod.z.custom()]).optional(),
+	inputKey: zod.z.string().optional(),
+	outputKey: zod.z.string().optional(),
+	toolChoice: aiAgentToolChoiceSchema.optional(),
+	toolCallsConcurrency: zod.z.number().int().min(0).optional(),
+	keepTextInToolUses: zod.z.boolean().optional(),
+	memoryAgentsAsTools: zod.z.boolean().optional(),
+	memoryPromptTemplate: zod.z.string().optional()
+});
+/**
+* AI-powered agent that leverages language models
+*
+* AIAgent connects to language models to process inputs and generate responses,
+* with support for streaming, function calling, and tool usage.
+*
+* Key features:
+* - Connect to any language model
+* - Use customizable instructions and prompts
+* - Execute tools/function calls
+* - Support streaming responses
+* - Router mode for specialized agents
+*
+* @template I The input message type the agent accepts
+* @template O The output message type the agent returns
+*
+* @example
+* Basic AIAgent creation:
+* {@includeCode ../../test/agents/ai-agent.test.ts#example-ai-agent-basic}
+*/
+var AIAgent = class AIAgent extends require_agent.Agent {
+	tag = "AIAgent";
+	static schema({ filepath }) {
+		const instructionsSchema = require_loader_schema.getInstructionsSchema({ filepath });
+		const nestAgentSchema = require_loader_agent_yaml.getNestAgentSchema({ filepath });
+		return require_loader_schema.camelizeSchema(zod.z.object({
+			instructions: require_loader_schema.optionalize(instructionsSchema),
+			inputKey: require_loader_schema.optionalize(zod.z.string()),
+			outputKey: require_loader_schema.optionalize(zod.z.string()),
+			inputFileKey: require_loader_schema.optionalize(zod.z.string()),
+			outputFileKey: require_loader_schema.optionalize(zod.z.string()),
+			toolChoice: require_loader_schema.optionalize(zod.z.nativeEnum(AIAgentToolChoice)),
+			toolCallsConcurrency: require_loader_schema.optionalize(zod.z.number().int().min(0)),
+			keepTextInToolUses: require_loader_schema.optionalize(zod.z.boolean()),
+			catchToolsError: require_loader_schema.optionalize(zod.z.boolean()),
+			structuredStreamMode: require_loader_schema.optionalize(zod.z.boolean()),
+			session: require_loader_schema.optionalize(require_loader_schema.camelizeSchema(zod.z.object({
+				mode: require_loader_schema.optionalize(zod.z.enum(["auto", "disabled"])),
+				sessionMemory: require_loader_schema.optionalize(require_loader_schema.camelizeSchema(zod.z.object({
+					mode: require_loader_schema.optionalize(zod.z.enum(["auto", "disabled"])),
+					memoryRatio: require_loader_schema.optionalize(zod.z.number().min(0).max(1)),
+					queryLimit: require_loader_schema.optionalize(zod.z.number().int().min(0)),
+					async: require_loader_schema.optionalize(zod.z.boolean()),
+					extractor: require_loader_schema.optionalize(nestAgentSchema)
+				}))),
+				userMemory: require_loader_schema.optionalize(require_loader_schema.camelizeSchema(zod.z.object({
+					mode: require_loader_schema.optionalize(zod.z.enum(["auto", "disabled"])),
+					memoryRatio: require_loader_schema.optionalize(zod.z.number().min(0).max(1)),
+					queryLimit: require_loader_schema.optionalize(zod.z.number().int().min(0)),
+					async: require_loader_schema.optionalize(zod.z.boolean()),
+					extractor: require_loader_schema.optionalize(nestAgentSchema)
+				}))),
+				compact: require_loader_schema.optionalize(require_loader_schema.camelizeSchema(zod.z.object({
+					mode: require_loader_schema.optionalize(zod.z.enum(["auto", "disabled"])),
+					maxTokens: zod.z.number().int().min(0).optional(),
+					keepRecentRatio: require_loader_schema.optionalize(zod.z.number().min(0).max(1)),
+					async: require_loader_schema.optionalize(zod.z.boolean()),
+					compactor: require_loader_schema.optionalize(nestAgentSchema)
+				})))
+			})))
+		}));
+	}
+	static async load(options) {
+		const valid = await AIAgent.schema(options).parseAsync(options.parsed);
+		const sessionCompactor = valid.session?.compact?.compactor ? await options.options?.loadNestAgent(options.filepath, valid.session.compact.compactor, options.options) : void 0;
+		const sessionMemoryExtractor = valid.session?.sessionMemory?.extractor ? await options.options?.loadNestAgent(options.filepath, valid.session.sessionMemory.extractor, options.options) : void 0;
+		const userMemoryExtractor = valid.session?.userMemory?.extractor ? await options.options?.loadNestAgent(options.filepath, valid.session.userMemory.extractor, options.options) : void 0;
+		const sessionConfig = valid.session ? {
+			...valid.session,
+			compact: valid.session.compact ? {
+				...valid.session.compact,
+				compactor: sessionCompactor
+			} : void 0,
+			sessionMemory: valid.session.sessionMemory ? {
+				...valid.session.sessionMemory,
+				extractor: sessionMemoryExtractor
+			} : void 0,
+			userMemory: valid.session.userMemory ? {
+				...valid.session.userMemory,
+				extractor: userMemoryExtractor
+			} : void 0
+		} : void 0;
+		return new AIAgent({
+			...options.parsed,
+			...valid,
+			instructions: valid.instructions && require_loader_schema.instructionsToPromptBuilder(valid.instructions),
+			session: sessionConfig
+		});
+	}
+	/**
+	* Create an AIAgent with the specified options
+	*
+	* Factory method that provides a convenient way to create new AI agents
+	*
+	* @param options Configuration options for the AI agent
+	* @returns A new AIAgent instance
+	*
+	* @example
+	* AI agent with custom instructions:
+	* {@includeCode ../../test/agents/ai-agent.test.ts#example-ai-agent-instructions}
+	*/
+	static from(options) {
+		return new AIAgent(options);
+	}
+	/**
+	* Create an AIAgent instance
+	*
+	* @param options Configuration options for the AI agent
+	*/
+	constructor(options) {
+		super(options);
+		require_utils_type_utils.checkArguments("AIAgent", aiAgentOptionsSchema, options);
+		this.instructions = typeof options.instructions === "string" ? require_prompt_builder.PromptBuilder.from(options.instructions) : options.instructions ?? new require_prompt_builder.PromptBuilder();
+		this.inputKey = options.inputKey;
+		this.inputFileKey = options.inputFileKey;
+		this.outputKey = options.outputKey || DEFAULT_OUTPUT_KEY;
+		this.outputFileKey = options.outputFileKey || DEFAULT_OUTPUT_FILE_KEY;
+		this.outputFileType = options.outputFileType;
+		this.toolChoice = options.toolChoice;
+		this.toolCallsConcurrency = options.toolCallsConcurrency || 1;
+		this.keepTextInToolUses = options.keepTextInToolUses;
+		this.memoryAgentsAsTools = options.memoryAgentsAsTools;
+		this.memoryPromptTemplate = options.memoryPromptTemplate;
+		this.useMemoriesFromContext = options.useMemoriesFromContext;
+		this.session = options.session;
+		if (typeof options.catchToolsError === "boolean") this.catchToolsError = options.catchToolsError;
+		this.structuredStreamMode = options.structuredStreamMode;
+		this.ignoreTextOfStructuredStreamMode = options.ignoreTextOfStructuredStreamMode;
+		this.customStructuredStreamInstructions = options.customStructuredStreamInstructions && {
+			...options.customStructuredStreamInstructions,
+			instructions: typeof options.customStructuredStreamInstructions.instructions === "string" ? require_prompt_builder.PromptBuilder.from(options.customStructuredStreamInstructions.instructions) : options.customStructuredStreamInstructions.instructions
+		};
+		if (!this.inputKey && !this.instructions) throw new Error("AIAgent requires either inputKey or instructions to be set");
+	}
+	/**
+	* Instructions for the language model
+	*
+	* Contains system messages, user templates, and other prompt elements
+	* that guide the model's behavior
+	*
+	* @example
+	* Custom prompt builder:
+	* {@includeCode ../../test/agents/ai-agent.test.ts#example-ai-agent-prompt-builder}
+	*/
+	instructions;
+	/**
+	* Pick a message from input to use as the user's message
+	*/
+	inputKey;
+	inputFileKey;
+	/**
+	* Custom key to use for text output in the response
+	*
+	* @example
+	* Setting a custom output key:
+	* {@includeCode ../../test/agents/ai-agent.test.ts#example-ai-agent-custom-output-key}
+	*/
+	outputKey;
+	outputFileKey;
+	outputFileType;
+	/**
+	* Controls how the agent uses tools during execution
+	*
+	* @example
+	* Automatic tool choice:
+	* {@includeCode ../../test/agents/ai-agent.test.ts#example-ai-agent-tool-choice-auto}
+	*
+	* @example
+	* Router tool choice:
+	* {@includeCode ../../test/agents/ai-agent.test.ts#example-ai-agent-router}
+	*/
+	toolChoice;
+	/**
+	* Maximum number of tool calls to execute concurrently
+	*
+	* @default 1
+	*/
+	toolCallsConcurrency;
+	/**
+	* Whether to preserve text generated during tool usage in the final output
+	*/
+	keepTextInToolUses;
+	/**
+	* Whether to include memory agents as tools for the AI model
+	*
+	* When set to true, memory agents will be made available as tools
+	* that the model can call directly to retrieve or store information.
+	* This enables the agent to explicitly interact with its memories.
+	*/
+	memoryAgentsAsTools;
+	/**
+	* Custom prompt template for formatting memory content
+	*
+	* Allows customization of how memories are presented to the AI model.
+	* If not provided, the default template from MEMORY_MESSAGE_TEMPLATE will be used.
+	*
+	* The template receives a {{memories}} variable containing serialized memory content.
+	*/
+	memoryPromptTemplate;
+	useMemoriesFromContext;
+	/**
+	* Whether to catch error from tool execution and continue processing.
+	* If set to false, the agent will throw an error if a tool fails
+	*
+	* @default true
+	*/
+	catchToolsError = true;
+	/**
+	* Whether to enable structured stream mode
+	*
+	* When enabled, the AI model's streaming response will be processed to extract
+	* structured metadata. The model needs to include specific format metadata tags
+	* (like <metadata></metadata>) in its response, which will be parsed as JSON
+	* objects and passed through the stream.
+	*
+	* This is useful for scenarios that need to extract structured information
+	* (like classifications, scores, tags, etc.) from AI responses.
+	*
+	* @default false
+	*/
+	structuredStreamMode;
+	ignoreTextOfStructuredStreamMode;
+	/**
+	* Custom structured stream instructions configuration
+	*
+	* Allows customization of structured stream mode behavior, including:
+	* - instructions: Prompt instructions to guide the AI model on how to output structured data
+	* - metadataStart: Metadata start marker (e.g., "<metadata>")
+	* - metadataEnd: Metadata end marker (e.g., "</metadata>")
+	* - parse: Function to parse metadata content, converting raw string to object
+	*
+	* If not provided, the default STRUCTURED_STREAM_INSTRUCTIONS configuration will be used,
+	* which outputs structured data in YAML format within <metadata> tags.
+	*/
+	customStructuredStreamInstructions;
+	/**
+	* Agent session configuration
+	*/
+	session;
+	get inputSchema() {
+		let schema = super.inputSchema;
+		if (this.inputKey) schema = schema.extend({ [this.inputKey]: zod.z.string().nullish() });
+		if (this.inputFileKey) schema = schema.extend({ [this.inputFileKey]: require_model.fileUnionContentsSchema.nullish() });
+		return schema;
+	}
+	/**
+	* Process an input message and generate a response
+	*
+	* @protected
+	*/
+	process(input, options) {
+		return this._process(input, options);
+	}
+	async *_process(input, options) {
+		const model = this.model || options.model || options.context.model;
+		if (!model) throw new Error("model is required to run AIAgent");
+		const { toolAgents, session, userMessage, ...modelInput } = await this.instructions.build({
+			...options,
+			agent: this,
+			input,
+			model
+		});
+		modelInput.modelOptions = await model.getModelOptions(input, options);
+		const toolsMap = new Map(toolAgents?.map((i) => [i.name, i]));
+		if (this.toolChoice === "router") return yield* this._processRouter(input, model, {
+			messages: [...await session.getMessages(), userMessage],
+			...modelInput
+		}, options, toolsMap);
+		const inputMessage = this.inputKey ? input[this.inputKey] : void 0;
+		if (inputMessage) yield { progress: {
+			event: "message",
+			message: {
+				role: "user",
+				content: [{
+					type: "text",
+					text: inputMessage
+				}]
+			}
+		} };
+		await session.startMessage(input, userMessage, options);
+		const outputKey = this.outputKey;
+		for (;;) {
+			const modelOutput = {};
+			let stream = await this.invokeChildAgent(model, {
+				messages: await session.getMessages(),
+				...modelInput
+			}, {
+				...options,
+				streaming: true
+			});
+			if (this.structuredStreamMode) {
+				const { metadataStart, metadataEnd, parse } = this.customStructuredStreamInstructions || require_structured_stream_instructions.STRUCTURED_STREAM_INSTRUCTIONS;
+				stream = stream.pipeThrough(new require_utils_structured_stream_extractor.ExtractMetadataTransform({
+					start: metadataStart,
+					end: metadataEnd,
+					parse
+				}));
+			}
+			let isTextIgnored = false;
+			for await (const value of stream) {
+				require_utils_stream_utils.mergeAgentResponseChunk(modelOutput, value);
+				if (require_agent.isAgentResponseDelta(value)) {
+					if (!isTextIgnored && value.delta.text?.text) yield { delta: { text: { [outputKey]: value.delta.text.text } } };
+					if (value.delta.json) {
+						if (this.structuredStreamMode) {
+							yield { delta: { json: value.delta.json.json } };
+							if (!isTextIgnored && modelOutput.json && this.ignoreTextOfStructuredStreamMode) isTextIgnored = this.ignoreTextOfStructuredStreamMode(modelOutput.json);
+						}
+					}
+				}
+			}
+			const { toolCalls, json, text, thoughts, files } = modelOutput;
+			if (text || thoughts) {
+				const content = [];
+				if (thoughts) content.push({
+					type: "text",
+					text: thoughts,
+					isThinking: true
+				});
+				if (text) content.push({
+					type: "text",
+					text
+				});
+				if (content.length) {
+					const message = {
+						role: "agent",
+						content
+					};
+					yield { progress: {
+						event: "message",
+						message
+					} };
+					await session.appendCurrentMessages(message, options);
+				}
+			}
+			const toolCallsWithTools = toolCalls?.map((call) => {
+				const tool = toolsMap.get(call.function.name);
+				if (!tool) throw new Error(`Tool not found: ${call.function.name}`);
+				return {
+					...call,
+					tool
+				};
+			});
+			if (toolCallsWithTools?.length) {
+				if (this.keepTextInToolUses !== true) yield { delta: { json: { [outputKey]: "" } } };
+				else yield { delta: { text: { [outputKey]: "\n\n" } } };
+				const toolCallMessage = {
+					role: "agent",
+					toolCalls
+				};
+				yield { progress: {
+					event: "message",
+					message: toolCallMessage
+				} };
+				const executedToolCalls = [];
+				let error;
+				const queue = require_utils_queue.promise(async ({ tool, call }) => {
+					try {
+						const output = await this.invokeSkill(tool, {
+							...input,
+							...call.function.arguments
+						}, options).catch((error$1) => {
+							if (!this.catchToolsError) return Promise.reject(error$1);
+							return {
+								isError: true,
+								error: { message: error$1.message }
+							};
+						});
+						executedToolCalls.push({
+							call,
+							tool,
+							output
+						});
+					} catch (e) {
+						error = e;
+						queue.killAndDrain();
+					}
+				}, this.toolCallsConcurrency || 1);
+				for (const call of toolCallsWithTools) queue.push({
+					tool: call.tool,
+					call
+				});
+				await queue.drained();
+				if (error) throw error;
+				const toolResultMessages = [];
+				if (executedToolCalls.length) {
+					for (const { call, tool, output } of executedToolCalls) {
+						const isAgentSkill = !output.isError && tool instanceof require_agent_skill.AgentSkill ? true : void 0;
+						const text$1 = await tool.formatOutput(output);
+						const message = {
+							role: "tool",
+							toolCallId: call.id,
+							content: [{
+								type: "text",
+								text: text$1,
+								isAgentSkill
+							}]
+						};
+						yield { progress: {
+							event: "message",
+							message
+						} };
+						toolResultMessages.push(message);
+					}
+					const transferOutput = executedToolCalls.find((i) => require_types.isTransferAgentOutput(i.output))?.output;
+					if (transferOutput) return transferOutput;
+					await session.appendCurrentMessages([toolCallMessage, ...toolResultMessages], options);
+					continue;
+				}
+			}
+			const result = {};
+			if (json) Object.assign(result, json);
+			if (text) Object.assign(result, { [outputKey]: text });
+			if (files) Object.assign(result, { [this.outputFileKey]: files });
+			if (!require_utils_type_utils.isEmpty(result)) yield { delta: { json: result } };
+			await session.endMessage(result, void 0, options);
+			return;
+		}
+	}
+	async onGuideRailError(error) {
+		return { [this.outputKey || DEFAULT_OUTPUT_KEY]: error.reason };
+	}
+	/**
+	* Process router mode requests
+	*
+	* In router mode, the agent sends a single request to the model to determine
+	* which tool to use, then routes the request directly to that tool
+	*
+	* @protected
+	*/
+	async *_processRouter(input, model, modelInput, options, toolsMap) {
+		const { toolCalls: [call] = [] } = await this.invokeChildAgent(model, modelInput, {
+			...options,
+			streaming: false
+		});
+		if (!call) throw new Error("Router toolChoice requires exactly one tool to be executed");
+		const tool = toolsMap.get(call.function.name);
+		if (!tool) throw new Error(`Tool not found: ${call.function.name}`);
+		return yield* await this.invokeChildAgent(tool, {
+			...call.function.arguments,
+			...input
+		}, {
+			...options,
+			streaming: true,
+			sourceAgent: this
+		});
+	}
+};
+
+//#endregion
+exports.AIAgent = AIAgent;
+exports.AIAgentToolChoice = AIAgentToolChoice;
+exports.DEFAULT_OUTPUT_FILE_KEY = DEFAULT_OUTPUT_FILE_KEY;
+exports.DEFAULT_OUTPUT_KEY = DEFAULT_OUTPUT_KEY;
+exports.aiAgentOptionsSchema = aiAgentOptionsSchema;
+exports.aiAgentToolChoiceSchema = aiAgentToolChoiceSchema;