@aigne/core 1.13.0 → 1.15.0

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

@@ -1,70 +1,228 @@
-import { z } from "zod";
+import { type ZodObject, type ZodType, z } from "zod";
 import type { Context } from "../aigne/context.js";
+import { type DefaultMemoryOptions } from "../memory/default-memory.js";
 import { ChatModel } from "../models/chat-model.js";
 import type { ChatModelInput } from "../models/chat-model.js";
 import { PromptBuilder } from "../prompt/prompt-builder.js";
 import { Agent, type AgentOptions, type AgentProcessAsyncGenerator, type Message } from "./agent.js";
-export interface AIAgentOptions<I extends Message = Message, O extends Message = Message> extends AgentOptions<I, O> {
+/**
+ * Configuration options for an AI Agent
+ *
+ * These options extend the base agent options with AI-specific parameters
+ * like model configuration, prompt instructions, and tool choice.
+ *
+ * @template I The input message type the agent accepts
+ * @template O The output message type the agent returns
+ */
+export interface AIAgentOptions<I extends Message = Message, O extends Message = Message> extends Omit<AgentOptions<I, O>, "memory"> {
+    /**
+     * The language model to use for this agent
+     *
+     * If not provided, the agent will use the model from the context
+     */
     model?: ChatModel;
+    /**
+     * Instructions to guide the AI model's behavior
+     *
+     * Can be a simple string or a full PromptBuilder instance for
+     * more complex prompt templates
+     */
     instructions?: string | PromptBuilder;
+    /**
+     * Custom key to use for text output in the response
+     *
+     * Defaults to $message if not specified
+     */
     outputKey?: string;
-    toolChoice?: AIAgentToolChoice;
+    /**
+     * Controls how the agent uses tools during execution
+     *
+     * @default AIAgentToolChoice.auto
+     */
+    toolChoice?: AIAgentToolChoice | Agent;
+    /**
+     * Whether to catch errors from tool execution and continue processing.
+     * If set to false, the agent will throw an error if a tool fails.
+     *
+     * @default true
+     */
+    catchToolsError?: boolean;
+    /**
+     * 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.
+     *
+     * @default false
+     */
+    memoryAgentsAsTools?: boolean;
+    /**
+     * 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?: string;
+    memory?: AgentOptions<I, O>["memory"] | DefaultMemoryOptions | true;
 }
-export type AIAgentToolChoice = "auto" | "none" | "required" | "router" | Agent;
-export declare const aiAgentToolChoiceSchema: z.ZodUnion<[z.ZodLiteral<"auto">, z.ZodLiteral<"none">, z.ZodLiteral<"required">, z.ZodLiteral<"router">, z.ZodType<Agent<Message, Message>, z.ZodTypeDef, Agent<Message, Message>>]>;
-export declare const aiAgentOptionsSchema: z.ZodObject<{
-    model: z.ZodOptional<z.ZodType<ChatModel, z.ZodTypeDef, ChatModel>>;
-    instructions: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodType<PromptBuilder, z.ZodTypeDef, PromptBuilder>]>>;
-    outputKey: z.ZodOptional<z.ZodString>;
-    toolChoice: z.ZodOptional<z.ZodUnion<[z.ZodLiteral<"auto">, z.ZodLiteral<"none">, z.ZodLiteral<"required">, z.ZodLiteral<"router">, z.ZodType<Agent<Message, Message>, z.ZodTypeDef, Agent<Message, Message>>]>>;
-    enableHistory: z.ZodOptional<z.ZodBoolean>;
-    maxHistoryMessages: z.ZodOptional<z.ZodNumber>;
-    includeInputInOutput: z.ZodOptional<z.ZodBoolean>;
-    subscribeTopic: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodArray<z.ZodString, "many">]>>;
-    publishTopic: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodArray<z.ZodString, "many">, z.ZodFunction<z.ZodTuple<[], z.ZodUnknown>, z.ZodUnknown>]>>;
-    name: z.ZodOptional<z.ZodString>;
-    description: z.ZodOptional<z.ZodString>;
-    skills: z.ZodOptional<z.ZodArray<z.ZodUnion<[z.ZodType<Agent<Message, Message>, z.ZodTypeDef, Agent<Message, Message>>, z.ZodFunction<z.ZodTuple<[], z.ZodUnknown>, z.ZodUnknown>]>, "many">>;
-    disableLogging: z.ZodOptional<z.ZodBoolean>;
-    memory: z.ZodOptional<z.ZodUnion<[z.ZodBoolean, z.ZodAny, z.ZodAny]>>;
-}, "strip", z.ZodTypeAny, {
-    description?: string | undefined;
-    memory?: any;
-    name?: string | undefined;
-    includeInputInOutput?: boolean | undefined;
-    subscribeTopic?: string | string[] | undefined;
-    publishTopic?: string | string[] | ((...args: unknown[]) => unknown) | undefined;
-    skills?: (Agent<Message, Message> | ((...args: unknown[]) => unknown))[] | undefined;
-    toolChoice?: Agent<Message, Message> | "auto" | "none" | "required" | "router" | undefined;
-    model?: ChatModel | undefined;
-    instructions?: string | PromptBuilder | undefined;
-    outputKey?: string | undefined;
-    enableHistory?: boolean | undefined;
-    maxHistoryMessages?: number | undefined;
-    disableLogging?: boolean | undefined;
-}, {
-    description?: string | undefined;
-    memory?: any;
-    name?: string | undefined;
-    includeInputInOutput?: boolean | undefined;
-    subscribeTopic?: string | string[] | undefined;
-    publishTopic?: string | string[] | ((...args: unknown[]) => unknown) | undefined;
-    skills?: (Agent<Message, Message> | ((...args: unknown[]) => unknown))[] | undefined;
-    toolChoice?: Agent<Message, Message> | "auto" | "none" | "required" | "router" | undefined;
-    model?: ChatModel | undefined;
-    instructions?: string | PromptBuilder | undefined;
-    outputKey?: string | undefined;
-    enableHistory?: boolean | undefined;
-    maxHistoryMessages?: number | undefined;
-    disableLogging?: boolean | undefined;
+/**
+ * Tool choice options for AI agents
+ *
+ * Controls how the agent decides to use tools during execution
+ */
+export declare enum AIAgentToolChoice {
+    /**
+     * Let the model decide when to use tools
+     */
+    auto = "auto",
+    /**
+     * Disable tool usage
+     */
+    none = "none",
+    /**
+     * Force tool usage
+     */
+    required = "required",
+    /**
+     * Choose exactly one tool and route directly to it
+     */
+    router = "router"
+}
+/**
+ * Zod schema for validating AIAgentToolChoice values
+ *
+ * Used to ensure that toolChoice receives valid values
+ *
+ * @hidden
+ */
+export declare const aiAgentToolChoiceSchema: z.ZodUnion<[z.ZodNativeEnum<typeof AIAgentToolChoice>, ZodType<Agent<Message, Message>, z.ZodTypeDef, Agent<Message, Message>>]>;
+/**
+ * Zod schema for validating AIAgentOptions
+ *
+ * Extends the base agent options schema with AI-specific parameters
+ *
+ * @hidden
+ */
+export declare const aiAgentOptionsSchema: ZodObject<{
+    [key in keyof AIAgentOptions]: ZodType<AIAgentOptions[key]>;
 }>;
+/**
+ * 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}
+ */
 export declare class AIAgent<I extends Message = Message, O extends Message = Message> extends Agent<I, O> {
+    /**
+     * 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<I extends Message, O extends Message>(options: AIAgentOptions<I, O>): AIAgent<I, O>;
+    /**
+     * Create an AIAgent instance
+     *
+     * @param options Configuration options for the AI agent
+     */
     constructor(options: AIAgentOptions<I, O>);
+    /**
+     * The language model used by this agent
+     *
+     * If not set on the agent, the model from the context will be used
+     */
     model?: ChatModel;
+    /**
+     * 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: PromptBuilder;
+    /**
+     * 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?: string;
-    toolChoice?: AIAgentToolChoice;
+    /**
+     * 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?: AIAgentToolChoice | Agent;
+    /**
+     * 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?: boolean;
+    /**
+     * 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?: string;
+    /**
+     * 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: boolean;
+    /**
+     * Process an input message and generate a response
+     *
+     * @protected
+     */
     process(input: I, context: Context): AgentProcessAsyncGenerator<O>;
-    processRouter(input: I, model: ChatModel, modelInput: ChatModelInput, context: Context, toolsMap: Map<string, Agent>): AgentProcessAsyncGenerator<O>;
+    /**
+     * 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
+     */
+    _processRouter(input: I, model: ChatModel, modelInput: ChatModelInput, context: Context, toolsMap: Map<string, Agent>): AgentProcessAsyncGenerator<O>;
 }

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

@@ -1,44 +1,115 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.AIAgent = exports.aiAgentOptionsSchema = exports.aiAgentToolChoiceSchema = void 0;
+exports.AIAgent = exports.aiAgentOptionsSchema = exports.aiAgentToolChoiceSchema = exports.AIAgentToolChoice = void 0;
 const zod_1 = require("zod");
+const default_memory_js_1 = require("../memory/default-memory.js");
+const memory_js_1 = require("../memory/memory.js");
 const chat_model_js_1 = require("../models/chat-model.js");
 const prompt_builder_js_1 = require("../prompt/prompt-builder.js");
 const template_js_1 = require("../prompt/template.js");
-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");
 const types_js_1 = require("./types.js");
-exports.aiAgentToolChoiceSchema = zod_1.z.union([
-    zod_1.z.literal("auto"),
-    zod_1.z.literal("none"),
-    zod_1.z.literal("required"),
-    zod_1.z.literal("router"),
-    zod_1.z.instanceof(agent_js_1.Agent),
-], { message: "aiAgentToolChoice must be 'auto', 'none', 'required', 'router', or an Agent" });
-exports.aiAgentOptionsSchema = zod_1.z.object({
+/**
+ * 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.instanceof(agent_js_1.Agent)], {
+    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.instanceof(chat_model_js_1.ChatModel).optional(),
     instructions: zod_1.z.union([zod_1.z.string(), zod_1.z.instanceof(prompt_builder_js_1.PromptBuilder)]).optional(),
     outputKey: zod_1.z.string().optional(),
     toolChoice: exports.aiAgentToolChoiceSchema.optional(),
-    enableHistory: zod_1.z.boolean().optional(),
-    maxHistoryMessages: zod_1.z.number().optional(),
-    includeInputInOutput: zod_1.z.boolean().optional(),
-    subscribeTopic: zod_1.z.union([zod_1.z.string(), zod_1.z.array(zod_1.z.string())]).optional(),
-    publishTopic: zod_1.z.union([zod_1.z.string(), zod_1.z.array(zod_1.z.string()), zod_1.z.function()]).optional(),
-    name: zod_1.z.string().optional(),
-    description: zod_1.z.string().optional(),
-    skills: zod_1.z.array(zod_1.z.union([zod_1.z.instanceof(agent_js_1.Agent), zod_1.z.function()])).optional(),
-    disableLogging: zod_1.z.boolean().optional(),
-    memory: zod_1.z.union([zod_1.z.boolean(), zod_1.z.any(), zod_1.z.any()]).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 {
+    /**
+     * 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) {
-        exports.aiAgentOptionsSchema.parse(options);
-        super(options);
+        super({
+            ...options,
+            memory: !options.memory
+                ? undefined
+                : Array.isArray(options.memory) || options.memory instanceof memory_js_1.MemoryAgent
+                    ? options.memory
+                    : new default_memory_js_1.DefaultMemory(options.memory === true ? {} : options.memory),
+        });
+        (0, type_utils_js_1.checkArguments)("AIAgent", exports.aiAgentOptionsSchema, options);
         this.model = options.model;
         this.instructions =
             typeof options.instructions === "string"
@@ -46,11 +117,77 @@ class AIAgent extends agent_js_1.Agent {
                 : (options.instructions ?? new prompt_builder_js_1.PromptBuilder());
         this.outputKey = options.outputKey;
         this.toolChoice = options.toolChoice;
+        this.memoryAgentsAsTools = options.memoryAgentsAsTools;
+        this.memoryPromptTemplate = options.memoryPromptTemplate;
+        if (typeof options.catchToolsError === "boolean")
+            this.catchToolsError = options.catchToolsError;
     }
+    /**
+     * The language model used by this agent
+     *
+     * If not set on the agent, the model from the context will be used
+     */
     model;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * Process an input message and generate a response
+     *
+     * @protected
+     */
     async *process(input, context) {
         const model = this.model ?? context.model;
         if (!model)
@@ -63,7 +200,7 @@ class AIAgent extends agent_js_1.Agent {
         });
         const toolsMap = new Map(toolAgents?.map((i) => [i.name, i]));
         if (this.toolChoice === "router") {
-            yield* this.processRouter(input, model, modelInput, context, toolsMap);
+            yield* this._processRouter(input, model, modelInput, context, toolsMap);
             return;
         }
         const toolCallMessages = [];
@@ -71,7 +208,7 @@ class AIAgent extends agent_js_1.Agent {
         for (;;) {
             const modelOutput = {};
             const stream = await context.invoke(model, { ...modelInput, messages: modelInput.messages.concat(toolCallMessages) }, { streaming: true });
-            for await (const value of (0, stream_utils_js_1.readableStreamToAsyncIterator)(stream)) {
+            for await (const value of stream) {
                 if (value.delta.text?.text) {
                     yield { delta: { text: { [outputKey]: value.delta.text.text } } };
                 }
@@ -88,7 +225,19 @@ class AIAgent extends agent_js_1.Agent {
                     if (!tool)
                         throw new Error(`Tool not found: ${call.function.name}`);
                     // NOTE: should pass both arguments (model generated) and input (user provided) to the tool
-                    const output = await context.invoke(tool, { ...call.function.arguments, ...input }, { disableTransfer: true });
+                    const output = await context
+                        .invoke(tool, { ...input, ...call.function.arguments }, { disableTransfer: true })
+                        .catch((error) => {
+                        if (!this.catchToolsError) {
+                            return Promise.reject(error);
+                        }
+                        return {
+                            isError: true,
+                            error: {
+                                message: error.message,
+                            },
+                        };
+                    });
                     // NOTE: Return transfer output immediately
                     if ((0, types_js_1.isTransferAgentOutput)(output)) {
                         return output;
@@ -114,7 +263,15 @@ class AIAgent extends agent_js_1.Agent {
             return;
         }
     }
-    async *processRouter(input, model, modelInput, context, toolsMap) {
+    /**
+     * 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, context, toolsMap) {
         const { toolCalls: [call] = [], } = await context.invoke(model, modelInput);
         if (!call) {
             throw new Error("Router toolChoice requires exactly one tool to be executed");
@@ -123,7 +280,7 @@ class AIAgent extends agent_js_1.Agent {
         if (!tool)
             throw new Error(`Tool not found: ${call.function.name}`);
         const stream = await context.invoke(tool, { ...call.function.arguments, ...input }, { streaming: true });
-        yield* (0, stream_utils_js_1.readableStreamToAsyncIterator)(stream);
+        yield* stream;
     }
 }
 exports.AIAgent = AIAgent;