@aigne/core 1.13.0 → 1.15.0

package/lib/esm/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/esm/agents/ai-agent.js

@@ -1,41 +1,112 @@
 import { z } from "zod";
+import { DefaultMemory } from "../memory/default-memory.js";
+import { MemoryAgent } from "../memory/memory.js";
 import { ChatModel } from "../models/chat-model.js";
 import { MESSAGE_KEY, PromptBuilder } from "../prompt/prompt-builder.js";
 import { AgentMessageTemplate, ToolMessageTemplate } from "../prompt/template.js";
-import { readableStreamToAsyncIterator } from "../utils/stream-utils.js";
-import { isEmpty } from "../utils/type-utils.js";
-import { Agent, } from "./agent.js";
+import { checkArguments, isEmpty } from "../utils/type-utils.js";
+import { Agent, agentOptionsSchema, } from "./agent.js";
 import { isTransferAgentOutput } from "./types.js";
-export const aiAgentToolChoiceSchema = z.union([
-    z.literal("auto"),
-    z.literal("none"),
-    z.literal("required"),
-    z.literal("router"),
-    z.instanceof(Agent),
-], { message: "aiAgentToolChoice must be 'auto', 'none', 'required', 'router', or an Agent" });
-export const aiAgentOptionsSchema = z.object({
+/**
+ * Tool choice options for AI agents
+ *
+ * Controls how the agent decides to use tools during execution
+ */
+export 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 || (AIAgentToolChoice = {}));
+/**
+ * Zod schema for validating AIAgentToolChoice values
+ *
+ * Used to ensure that toolChoice receives valid values
+ *
+ * @hidden
+ */
+export const aiAgentToolChoiceSchema = z.union([z.nativeEnum(AIAgentToolChoice), z.instanceof(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
+ */
+export const aiAgentOptionsSchema = agentOptionsSchema.extend({
     model: z.instanceof(ChatModel).optional(),
     instructions: z.union([z.string(), z.instanceof(PromptBuilder)]).optional(),
     outputKey: z.string().optional(),
     toolChoice: aiAgentToolChoiceSchema.optional(),
-    enableHistory: z.boolean().optional(),
-    maxHistoryMessages: z.number().optional(),
-    includeInputInOutput: z.boolean().optional(),
-    subscribeTopic: z.union([z.string(), z.array(z.string())]).optional(),
-    publishTopic: z.union([z.string(), z.array(z.string()), z.function()]).optional(),
-    name: z.string().optional(),
-    description: z.string().optional(),
-    skills: z.array(z.union([z.instanceof(Agent), z.function()])).optional(),
-    disableLogging: z.boolean().optional(),
-    memory: z.union([z.boolean(), z.any(), z.any()]).optional(),
+    memoryAgentsAsTools: z.boolean().optional(),
+    memoryPromptTemplate: 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}
+ */
 export class AIAgent extends 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) {
-        aiAgentOptionsSchema.parse(options);
-        super(options);
+        super({
+            ...options,
+            memory: !options.memory
+                ? undefined
+                : Array.isArray(options.memory) || options.memory instanceof MemoryAgent
+                    ? options.memory
+                    : new DefaultMemory(options.memory === true ? {} : options.memory),
+        });
+        checkArguments("AIAgent", aiAgentOptionsSchema, options);
         this.model = options.model;
         this.instructions =
             typeof options.instructions === "string"
@@ -43,11 +114,77 @@ export class AIAgent extends Agent {
                 : (options.instructions ?? new 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)
@@ -60,7 +197,7 @@ export class AIAgent extends 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 = [];
@@ -68,7 +205,7 @@ export class AIAgent extends Agent {
         for (;;) {
             const modelOutput = {};
             const stream = await context.invoke(model, { ...modelInput, messages: modelInput.messages.concat(toolCallMessages) }, { streaming: true });
-            for await (const value of readableStreamToAsyncIterator(stream)) {
+            for await (const value of stream) {
                 if (value.delta.text?.text) {
                     yield { delta: { text: { [outputKey]: value.delta.text.text } } };
                 }
@@ -85,7 +222,19 @@ export class AIAgent extends 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 (isTransferAgentOutput(output)) {
                         return output;
@@ -111,7 +260,15 @@ export class AIAgent extends 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");
@@ -120,6 +277,6 @@ export class AIAgent extends 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* readableStreamToAsyncIterator(stream);
+        yield* stream;
     }
 }