@aigne/core 1.13.0 → 1.14.0

package/lib/esm/agents/agent.js

@@ -4,10 +4,47 @@ import { createMessage } from "../prompt/prompt-builder.js";
 import { logger } from "../utils/logger.js";
 import { agentResponseStreamToObject, asyncGeneratorToReadableStream, isAsyncGenerator, objectToAgentResponseStream, onAgentResponseStreamEnd, } from "../utils/stream-utils.js";
 import { checkArguments, createAccessorArray, isEmpty, orArrayToArray, } from "../utils/type-utils.js";
-import { AgentMemory } from "./memory.js";
 import { replaceTransferAgentToName, transferToAgentOutput, } from "./types.js";
+export * from "./types.js";
+export const agentOptionsSchema = z.object({
+    subscribeTopic: z.union([z.string(), z.array(z.string())]).optional(),
+    publishTopic: z
+        .union([z.string(), z.array(z.string()), z.custom()])
+        .optional(),
+    name: z.string().optional(),
+    description: z.string().optional(),
+    inputSchema: z.custom().optional(),
+    outputSchema: z.custom().optional(),
+    includeInputInOutput: z.boolean().optional(),
+    skills: z.array(z.union([z.custom(), z.custom()])).optional(),
+    disableEvents: z.boolean().optional(),
+    memory: z.union([z.custom(), z.array(z.custom())]).optional(),
+});
+/**
+ * Agent is the base class for all agents.
+ * It provides a mechanism for defining input/output schemas and implementing processing logic,
+ * serving as the foundation of the entire agent system.
+ *
+ * By extending the Agent class and implementing the process method, you can create custom agents
+ * with various capabilities:
+ * - Process structured input and output data
+ * - Validate data formats using schemas
+ * - Communicate between agents through contexts
+ * - Support streaming or non-streaming responses
+ * - Maintain memory of past interactions
+ * - Output in multiple formats (JSON/text)
+ * - Forward tasks to other agents
+ *
+ * @template I The input message type the agent accepts
+ * @template O The output message type the agent returns
+ *
+ * @example
+ * Here's an example of how to create a custom agent:
+ * {@includeCode ../../test/agents/agent.test.ts#example-custom-agent}
+ */
 export class Agent {
-    constructor({ inputSchema, outputSchema, ...options }) {
+    constructor(options = {}) {
+        const { inputSchema, outputSchema } = options;
         this.name = options.name || this.constructor.name;
         this.description = options.description;
         if (inputSchema)
@@ -22,68 +59,159 @@ export class Agent {
         if (options.skills?.length)
             this.skills.push(...options.skills.map(functionToAgent));
         this.disableEvents = options.disableEvents;
-        if (options.memory) {
-            this.memory =
-                options.memory instanceof AgentMemory
-                    ? options.memory
-                    : typeof options.memory === "boolean"
-                        ? new AgentMemory({ enabled: options.memory })
-                        : new AgentMemory(options.memory);
+        if (Array.isArray(options.memory)) {
+            this.memories.push(...options.memory);
+        }
+        else if (options.memory) {
+            this.memories.push(options.memory);
         }
     }
-    memory;
+    /**
+     * List of memories this agent can use
+     */
+    memories = [];
+    /**
+     * Name of the agent, used for identification and logging
+     *
+     * Defaults to the class constructor name if not specified in options
+     */
     name;
     /**
-     * Default topic this agent will subscribe to
+     * Default topic this agent subscribes to
+     *
+     * Each agent has a default topic in the format "$agent_[agent name]"
+     * The agent automatically subscribes to this topic to receive messages
+     *
+     * @returns The default topic string
      */
     get topic() {
         return `$agent_${this.name}`;
     }
+    /**
+     * Description of the agent's purpose and capabilities
+     *
+     * Useful for documentation and when agents need to understand
+     * each other's roles in a multi-agent system
+     */
     description;
     _inputSchema;
     _outputSchema;
+    /**
+     * Get the input data schema for this agent
+     *
+     * Used to validate that input messages conform to required format
+     * If no input schema is set, returns an empty object schema by default
+     *
+     * @returns The Zod type definition for input data
+     */
     get inputSchema() {
         const s = this._inputSchema;
         const schema = typeof s === "function" ? s(this) : s || z.object({});
         checkAgentInputOutputSchema(schema);
         return schema.passthrough();
     }
+    /**
+     * Get the output data schema for this agent
+     *
+     * Used to validate that output messages conform to required format
+     * If no output schema is set, returns an empty object schema by default
+     *
+     * @returns The Zod type definition for output data
+     */
     get outputSchema() {
         const s = this._outputSchema;
         const schema = typeof s === "function" ? s(this) : s || z.object({});
         checkAgentInputOutputSchema(schema);
         return schema.passthrough();
     }
+    /**
+     * Whether to include the original input in the output
+     *
+     * When true, the agent will merge input fields into the output object
+     */
     includeInputInOutput;
+    /**
+     * Topics the agent subscribes to for receiving messages
+     *
+     * Can be a single topic string or an array of topic strings
+     */
     subscribeTopic;
+    /**
+     * Topics the agent publishes to for sending messages
+     *
+     * Can be a string, array of strings, or a function that determines
+     * topics based on the output
+     */
     publishTopic;
+    /**
+     * Collection of skills (other agents) this agent can use
+     *
+     * Skills can be accessed by name or by array index, allowing
+     * the agent to delegate tasks to specialized sub-agents
+     */
     skills = createAccessorArray([], (arr, name) => arr.find((t) => t.name === name));
+    /**
+     * Whether to disable emitting events for agent actions
+     *
+     * When true, the agent won't emit events like agentStarted,
+     * agentSucceed, or agentFailed
+     */
     disableEvents;
+    subscriptions = [];
     /**
      * Attach agent to context:
-     * - subscribe to topic and invoke process method when message received
-     * - subscribe to memory topic if memory is enabled
-     * @param context Context to attach
+     * - Subscribe to topics and invoke process method when messages are received
+     * - Subscribe to memory topics if memory is enabled
+     *
+     * Agents can receive messages and respond through the topic subscription system,
+     * enabling inter-agent communication.
+     *
+     * @param context Context to attach to
      */
     attach(context) {
-        this.memory?.attach(context);
+        for (const memory of this.memories) {
+            memory.attach(context);
+        }
+        this.subscribeToTopics(context);
+    }
+    subscribeToTopics(context) {
         for (const topic of orArrayToArray(this.subscribeTopic).concat(this.topic)) {
-            context.subscribe(topic, async ({ message, context }) => {
-                try {
-                    await context.invoke(this, message);
-                }
-                catch (error) {
-                    context.emit("agentFailed", { agent: this, error });
-                }
-            });
+            this.subscriptions.push(context.subscribe(topic, (payload) => this.onMessage(payload)));
         }
     }
+    async onMessage({ message, context }) {
+        try {
+            await context.invoke(this, message);
+        }
+        catch (error) {
+            context.emit("agentFailed", { agent: this, error });
+        }
+    }
+    /**
+     * Add skills (other agents or functions) to this agent
+     *
+     * Skills allow agents to reuse functionality from other agents,
+     * building more complex behaviors.
+     *
+     * @param skills List of skills to add, can be Agent instances or functions
+     */
     addSkill(...skills) {
         this.skills.push(...skills.map((skill) => (typeof skill === "function" ? functionToAgent(skill) : skill)));
     }
+    /**
+     * Check if the agent is invokable
+     *
+     * An agent is invokable if it has implemented the process method
+     */
     get isInvokable() {
         return !!this.process;
     }
+    /**
+     * Check context status to ensure it hasn't timed out
+     *
+     * @param context The context to check
+     * @throws Error if the context has timed out
+     */
     checkContextStatus(context) {
         if (context) {
             const { status } = context;
@@ -105,7 +233,7 @@ export class Agent {
             const parsedInput = checkArguments(`Agent ${this.name} input`, this.inputSchema, message);
             this.preprocess(parsedInput, ctx);
             this.checkContextStatus(ctx);
-            let response = await this.process(parsedInput, ctx, options);
+            let response = await this.process(parsedInput, ctx);
             if (response instanceof Agent) {
                 response = transferToAgentOutput(response);
             }
@@ -138,6 +266,16 @@ export class Agent {
             this.processAgentError(error, ctx);
         }
     }
+    /**
+     * Process agent output
+     *
+     * Validates output format, applies post-processing operations, and triggers success events
+     *
+     * @param input Original input message
+     * @param output Raw output produced by the agent
+     * @param context Execution context
+     * @returns Final processed output
+     */
     async processAgentOutput(input, output, context) {
         const parsedOutput = checkArguments(`Agent ${this.name} output`, this.outputSchema, output);
         const finalOutput = this.includeInputInOutput ? { ...input, ...parsedOutput } : parsedOutput;
@@ -147,12 +285,30 @@ export class Agent {
             context.emit("agentSucceed", { agent: this, output: finalOutput });
         return finalOutput;
     }
+    /**
+     * Process errors that occur during agent execution
+     *
+     * Logs error information, triggers failure events, and re-throws the error
+     *
+     * @param error Caught error
+     * @param context Execution context
+     * @throws Always throws the received error
+     */
     processAgentError(error, context) {
         logger.core("Invoke agent %s failed with error: %O", this.name, error);
         if (!this.disableEvents)
             context.emit("agentFailed", { agent: this, error });
         throw error;
     }
+    /**
+     * Check agent invocation usage to prevent exceeding limits
+     *
+     * If the context has a maximum invocation limit set, checks if the limit
+     * has been exceeded and increments the invocation counter
+     *
+     * @param context Execution context
+     * @throws Error if maximum invocation limit is exceeded
+     */
     checkAgentInvokesUsage(context) {
         const { limits, usage } = context;
         if (limits?.maxAgentInvokes && usage.agentCalls >= limits.maxAgentInvokes) {
@@ -160,50 +316,210 @@ export class Agent {
         }
         usage.agentCalls++;
     }
+    /**
+     * Pre-processing operations before handling input
+     *
+     * Preparatory work done before executing the agent's main processing logic, including:
+     * - Checking context status
+     * - Verifying invocation limits
+     *
+     * @param _ Input message (unused)
+     * @param context Execution context
+     */
     preprocess(_, context) {
         this.checkContextStatus(context);
         this.checkAgentInvokesUsage(context);
     }
+    /**
+     * Post-processing operations after handling output
+     *
+     * Operations performed after the agent produces output, including:
+     * - Checking context status
+     * - Adding interaction records to memory
+     *
+     * @param input Input message
+     * @param output Output message
+     * @param context Execution context
+     */
     postprocess(input, output, context) {
         this.checkContextStatus(context);
-        this.memory?.addMemory({ role: "user", content: input });
-        this.memory?.addMemory({
-            role: "agent",
-            content: replaceTransferAgentToName(output),
-            source: this.name,
-        });
+        this.publishToTopics(output, context);
+        for (const memory of this.memories) {
+            if (memory.autoUpdate) {
+                memory.record({
+                    content: [
+                        { role: "user", content: input },
+                        { role: "agent", content: replaceTransferAgentToName(output), source: this.name },
+                    ],
+                }, context);
+            }
+        }
     }
+    async publishToTopics(output, context) {
+        const publishTopics = typeof this.publishTopic === "function" ? await this.publishTopic(output) : this.publishTopic;
+        if (publishTopics?.length) {
+            context.publish(publishTopics, {
+                role: this.constructor.name === "UserAgent" ? "user" : "agent",
+                source: this.name,
+                message: output,
+            });
+        }
+    }
+    /**
+     * Shut down the agent and clean up resources
+     *
+     * Primarily used to clean up memory and other resources to prevent memory leaks
+     *
+     * @example
+     * Here's an example of shutting down an agent:
+     * {@includeCode ../../test/agents/agent.test.ts#example-agent-shutdown}
+     *
+     * @example
+     * Here's an example of shutting down an agent by using statement:
+     * {@includeCode ../../test/agents/agent.test.ts#example-agent-shutdown-by-using}
+     */
     async shutdown() {
-        this.memory?.detach();
+        for (const sub of this.subscriptions) {
+            sub();
+        }
+        this.subscriptions = [];
+        for (const m of this.memories) {
+            m.shutdown();
+        }
     }
+    /**
+     * Custom object inspection behavior
+     *
+     * When using Node.js's util.inspect function to inspect an agent,
+     * only the agent's name will be shown, making output more concise
+     *
+     * @returns Agent name
+     */
     [inspect.custom]() {
         return this.name;
     }
+    /**
+     * Async dispose method for shutdown the agent
+     *
+     * @example
+     * Here's an example of shutting down an agent by using statement:
+     * {@includeCode ../../test/agents/agent.test.ts#example-agent-shutdown-by-using}
+     */
+    async [Symbol.asyncDispose]() {
+        await this.shutdown();
+    }
 }
+/**
+ * Check if a response chunk is empty
+ *
+ * @template T Response data type
+ * @param chunk The response chunk to check
+ * @returns True if the chunk is empty
+ */
 export function isEmptyChunk(chunk) {
     return isEmpty(chunk.delta.json) && isEmpty(chunk.delta.text);
 }
+/**
+ * Creates a text delta for streaming responses
+ *
+ * This utility function creates an AgentResponseDelta object with only the text part,
+ * useful for incrementally building streaming text responses in agents.
+ *
+ * @template T Agent message type extending Message
+ * @param textDelta The text content to include in the delta update
+ * @returns An AgentResponseDelta with the text delta wrapped in the expected structure
+ */
+export function textDelta(textDelta) {
+    return { delta: { text: textDelta } };
+}
+/**
+ * Creates a JSON delta for streaming responses
+ *
+ * This utility function creates an AgentResponseDelta object with only the JSON part,
+ * useful for incrementally building structured data responses in streaming mode.
+ *
+ * @template T Agent message type extending Message
+ * @param jsonDelta The JSON data to include in the delta update
+ * @returns An AgentResponseDelta with the JSON delta wrapped in the expected structure
+ */
+export function jsonDelta(jsonDelta) {
+    return { delta: { json: jsonDelta } };
+}
 function checkAgentInputOutputSchema(schema) {
     if (!(schema instanceof ZodObject) && typeof schema !== "function") {
         throw new Error(`schema must be a zod object or function return a zod object, got: ${typeof schema}`);
     }
 }
+/**
+ * Function agent class, implements agent logic through a function
+ *
+ * Provides a convenient way to create agents using functions without
+ * needing to extend the Agent class
+ *
+ * @template I Agent input message type
+ * @template O Agent output message type
+ *
+ * @example
+ * Here's an example of creating a function agent:
+ * {@includeCode ../../test/agents/agent.test.ts#example-function-agent}
+ */
 export class FunctionAgent extends Agent {
+    /**
+     * Create a function agent from a function or options
+     *
+     * Provides a convenient factory method to create an agent directly from a function
+     *
+     * @param options Function agent options or function
+     * @returns New function agent instance
+     *
+     * @example
+     * Here's an example of creating a function agent from a function:
+     * {@includeCode ../../test/agents/agent.test.ts#example-function-agent-from-function}
+     *
+     * @example
+     * Here's an example of creating a function agent without basic agent options:
+     * {@includeCode ../../test/agents/agent.test.ts#example-function-agent}
+     *
+     * @example
+     * Here's an example of creating a function agent from a function returning a stream:
+     * {@includeCode ../../test/agents/agent.test.ts#example-function-agent-stream}
+     *
+     * @example
+     * Here's an example of creating a function agent from a function returning an async generator:
+     * {@includeCode ../../test/agents/agent.test.ts#example-function-agent-async-generator}
+     */
     static from(options) {
         return typeof options === "function" ? functionToAgent(options) : new FunctionAgent(options);
     }
+    /**
+     * Create a function agent instance
+     *
+     * @param options Function agent configuration options
+     */
     constructor(options) {
         super(options);
-        this.fn = options.fn ?? (() => ({}));
+        this._process = options.process;
     }
-    fn;
+    /**
+     * Stores the function used to process agent input and generate output
+     *
+     * @private
+     */
+    _process;
+    /**
+     * Process input implementation, calls the configured processing function
+     *
+     * @param input Input message
+     * @param context Execution context
+     * @returns Processing result
+     */
     process(input, context) {
-        return this.fn(input, context);
+        return this._process(input, context);
     }
 }
 function functionToAgent(agent) {
     if (typeof agent === "function") {
-        return FunctionAgent.from({ name: agent.name, fn: agent });
+        return FunctionAgent.from({ name: agent.name, process: agent });
     }
     return agent;
 }