@aigne/core 1.73.0-beta → 1.74.0-beta

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

@@ -1,572 +0,0 @@
-"use strict";
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
-    Object.defineProperty(o, "default", { enumerable: true, value: v });
-}) : function(o, v) {
-    o["default"] = v;
-});
-var __importStar = (this && this.__importStar) || (function () {
-    var ownKeys = function(o) {
-        ownKeys = Object.getOwnPropertyNames || function (o) {
-            var ar = [];
-            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
-            return ar;
-        };
-        return ownKeys(o);
-    };
-    return function (mod) {
-        if (mod && mod.__esModule) return mod;
-        var result = {};
-        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
-        __setModuleDefault(result, mod);
-        return result;
-    };
-})();
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.AIAgent = exports.aiAgentOptionsSchema = exports.aiAgentToolChoiceSchema = exports.AIAgentToolChoice = exports.DEFAULT_OUTPUT_FILE_KEY = exports.DEFAULT_OUTPUT_KEY = void 0;
-const zod_1 = require("zod");
-const agent_yaml_js_1 = require("../loader/agent-yaml.js");
-const schema_js_1 = require("../loader/schema.js");
-const prompt_builder_js_1 = require("../prompt/prompt-builder.js");
-const structured_stream_instructions_js_1 = require("../prompt/prompts/structured-stream-instructions.js");
-const agent_skill_js_1 = require("../prompt/skills/afs/agent-skill/agent-skill.js");
-const fastq = __importStar(require("../utils/queue.js"));
-const stream_utils_js_1 = require("../utils/stream-utils.js");
-const structured_stream_extractor_js_1 = require("../utils/structured-stream-extractor.js");
-const type_utils_js_1 = require("../utils/type-utils.js");
-const agent_js_1 = require("./agent.js");
-const model_js_1 = require("./model.js");
-const types_js_1 = require("./types.js");
-exports.DEFAULT_OUTPUT_KEY = "message";
-exports.DEFAULT_OUTPUT_FILE_KEY = "files";
-/**
- * Tool choice options for AI agents
- *
- * Controls how the agent decides to use tools during execution
- */
-var AIAgentToolChoice;
-(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";
-})(AIAgentToolChoice || (exports.AIAgentToolChoice = AIAgentToolChoice = {}));
-/**
- * Zod schema for validating AIAgentToolChoice values
- *
- * Used to ensure that toolChoice receives valid values
- *
- * @hidden
- */
-exports.aiAgentToolChoiceSchema = zod_1.z.union([zod_1.z.nativeEnum(AIAgentToolChoice), zod_1.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
- */
-exports.aiAgentOptionsSchema = agent_js_1.agentOptionsSchema.extend({
-    model: zod_1.z.custom().optional(),
-    instructions: zod_1.z.union([zod_1.z.string(), zod_1.z.custom()]).optional(),
-    inputKey: zod_1.z.string().optional(),
-    outputKey: zod_1.z.string().optional(),
-    toolChoice: exports.aiAgentToolChoiceSchema.optional(),
-    toolCallsConcurrency: zod_1.z.number().int().min(0).optional(),
-    keepTextInToolUses: zod_1.z.boolean().optional(),
-    memoryAgentsAsTools: zod_1.z.boolean().optional(),
-    memoryPromptTemplate: zod_1.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}
- */
-class AIAgent extends agent_js_1.Agent {
-    tag = "AIAgent";
-    static schema({ filepath }) {
-        const instructionsSchema = (0, schema_js_1.getInstructionsSchema)({ filepath });
-        const nestAgentSchema = (0, agent_yaml_js_1.getNestAgentSchema)({ filepath });
-        const schema = (0, schema_js_1.camelizeSchema)(zod_1.z.object({
-            instructions: (0, schema_js_1.optionalize)(instructionsSchema),
-            inputKey: (0, schema_js_1.optionalize)(zod_1.z.string()),
-            outputKey: (0, schema_js_1.optionalize)(zod_1.z.string()),
-            inputFileKey: (0, schema_js_1.optionalize)(zod_1.z.string()),
-            outputFileKey: (0, schema_js_1.optionalize)(zod_1.z.string()),
-            toolChoice: (0, schema_js_1.optionalize)(zod_1.z.nativeEnum(AIAgentToolChoice)),
-            toolCallsConcurrency: (0, schema_js_1.optionalize)(zod_1.z.number().int().min(0)),
-            keepTextInToolUses: (0, schema_js_1.optionalize)(zod_1.z.boolean()),
-            catchToolsError: (0, schema_js_1.optionalize)(zod_1.z.boolean()),
-            structuredStreamMode: (0, schema_js_1.optionalize)(zod_1.z.boolean()),
-            session: (0, schema_js_1.optionalize)((0, schema_js_1.camelizeSchema)(zod_1.z.object({
-                mode: (0, schema_js_1.optionalize)(zod_1.z.enum(["auto", "disabled"])),
-                sessionMemory: (0, schema_js_1.optionalize)((0, schema_js_1.camelizeSchema)(zod_1.z.object({
-                    mode: (0, schema_js_1.optionalize)(zod_1.z.enum(["auto", "disabled"])),
-                    memoryRatio: (0, schema_js_1.optionalize)(zod_1.z.number().min(0).max(1)),
-                    queryLimit: (0, schema_js_1.optionalize)(zod_1.z.number().int().min(0)),
-                    async: (0, schema_js_1.optionalize)(zod_1.z.boolean()),
-                    extractor: (0, schema_js_1.optionalize)(nestAgentSchema),
-                }))),
-                userMemory: (0, schema_js_1.optionalize)((0, schema_js_1.camelizeSchema)(zod_1.z.object({
-                    mode: (0, schema_js_1.optionalize)(zod_1.z.enum(["auto", "disabled"])),
-                    memoryRatio: (0, schema_js_1.optionalize)(zod_1.z.number().min(0).max(1)),
-                    queryLimit: (0, schema_js_1.optionalize)(zod_1.z.number().int().min(0)),
-                    async: (0, schema_js_1.optionalize)(zod_1.z.boolean()),
-                    extractor: (0, schema_js_1.optionalize)(nestAgentSchema),
-                }))),
-                compact: (0, schema_js_1.optionalize)((0, schema_js_1.camelizeSchema)(zod_1.z.object({
-                    mode: (0, schema_js_1.optionalize)(zod_1.z.enum(["auto", "disabled"])),
-                    maxTokens: zod_1.z.number().int().min(0).optional(),
-                    keepRecentRatio: (0, schema_js_1.optionalize)(zod_1.z.number().min(0).max(1)),
-                    async: (0, schema_js_1.optionalize)(zod_1.z.boolean()),
-                    compactor: (0, schema_js_1.optionalize)(nestAgentSchema),
-                }))),
-            }))),
-        }));
-        return schema;
-    }
-    static async load(options) {
-        const schema = AIAgent.schema(options);
-        const valid = await schema.parseAsync(options.parsed);
-        // Load nested agents from session config if present
-        const sessionCompactor = valid.session?.compact?.compactor
-            ? await options.options?.loadNestAgent(options.filepath, valid.session.compact.compactor, options.options)
-            : undefined;
-        const sessionMemoryExtractor = valid.session?.sessionMemory?.extractor
-            ? await options.options?.loadNestAgent(options.filepath, valid.session.sessionMemory.extractor, options.options)
-            : undefined;
-        const userMemoryExtractor = valid.session?.userMemory?.extractor
-            ? await options.options?.loadNestAgent(options.filepath, valid.session.userMemory.extractor, options.options)
-            : undefined;
-        // Build session configuration with loaded agents
-        const sessionConfig = valid.session
-            ? {
-                ...valid.session,
-                compact: valid.session.compact
-                    ? {
-                        ...valid.session.compact,
-                        compactor: sessionCompactor,
-                    }
-                    : undefined,
-                sessionMemory: valid.session.sessionMemory
-                    ? {
-                        ...valid.session.sessionMemory,
-                        extractor: sessionMemoryExtractor,
-                    }
-                    : undefined,
-                userMemory: valid.session.userMemory
-                    ? {
-                        ...valid.session.userMemory,
-                        extractor: userMemoryExtractor,
-                    }
-                    : undefined,
-            }
-            : undefined;
-        return new AIAgent({
-            ...options.parsed,
-            ...valid,
-            instructions: valid.instructions && (0, schema_js_1.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);
-        (0, type_utils_js_1.checkArguments)("AIAgent", exports.aiAgentOptionsSchema, options);
-        this.instructions =
-            typeof options.instructions === "string"
-                ? prompt_builder_js_1.PromptBuilder.from(options.instructions)
-                : (options.instructions ?? new prompt_builder_js_1.PromptBuilder());
-        this.inputKey = options.inputKey;
-        this.inputFileKey = options.inputFileKey;
-        this.outputKey = options.outputKey || exports.DEFAULT_OUTPUT_KEY;
-        this.outputFileKey = options.outputFileKey || exports.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"
-                ? prompt_builder_js_1.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_1.z.string().nullish(),
-            });
-        }
-        if (this.inputFileKey) {
-            schema = schema.extend({
-                [this.inputFileKey]: model_js_1.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] : undefined;
-        if (inputMessage) {
-            yield {
-                progress: {
-                    event: "message",
-                    message: { role: "user", content: [{ type: "text", text: inputMessage }] },
-                },
-            };
-        }
-        await session.startMessage(input, userMessage, options);
-        // const toolCallMessages: ChatModelInputMessage[] = [];
-        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 || structured_stream_instructions_js_1.STRUCTURED_STREAM_INSTRUCTIONS;
-                stream = stream.pipeThrough(new structured_stream_extractor_js_1.ExtractMetadataTransform({ start: metadataStart, end: metadataEnd, parse }));
-            }
-            let isTextIgnored = false;
-            for await (const value of stream) {
-                (0, stream_utils_js_1.mergeAgentResponseChunk)(modelOutput, value);
-                if ((0, agent_js_1.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 = fastq.promise(async ({ tool, call }) => {
-                    try {
-                        // NOTE: should pass both arguments (model generated) and input (user provided) to the tool
-                        const output = await this.invokeSkill(tool, { ...input, ...call.function.arguments }, options).catch((error) => {
-                            if (!this.catchToolsError) {
-                                return Promise.reject(error);
-                            }
-                            return {
-                                isError: true,
-                                error: {
-                                    message: error.message,
-                                },
-                            };
-                        });
-                        executedToolCalls.push({ call, tool, output });
-                    }
-                    catch (e) {
-                        error = e;
-                        queue.killAndDrain();
-                    }
-                }, this.toolCallsConcurrency || 1);
-                // Execute tools
-                for (const call of toolCallsWithTools) {
-                    queue.push({ tool: call.tool, call });
-                }
-                await queue.drained();
-                if (error)
-                    throw error;
-                const toolResultMessages = [];
-                // Continue LLM function calling loop if any tools were executed
-                if (executedToolCalls.length) {
-                    for (const { call, tool, output } of executedToolCalls) {
-                        const isAgentSkill = !output.isError && tool instanceof agent_skill_js_1.AgentSkill ? true : undefined;
-                        const text = await tool.formatOutput(output);
-                        const message = {
-                            role: "tool",
-                            toolCallId: call.id,
-                            content: [{ type: "text", text, isAgentSkill }],
-                        };
-                        yield { progress: { event: "message", message: message } };
-                        toolResultMessages.push(message);
-                    }
-                    const transferOutput = executedToolCalls.find((i) => (0, types_js_1.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 (!(0, type_utils_js_1.isEmpty)(result)) {
-                yield { delta: { json: result } };
-            }
-            await session.endMessage(result, undefined, options);
-            return;
-        }
-    }
-    async onGuideRailError(error) {
-        const outputKey = this.outputKey || exports.DEFAULT_OUTPUT_KEY;
-        return {
-            [outputKey]: 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}`);
-        const stream = await this.invokeChildAgent(tool, { ...call.function.arguments, ...input }, { ...options, streaming: true, sourceAgent: this });
-        return yield* stream;
-    }
-}
-exports.AIAgent = AIAgent;