@aigne/agent-library 1.7.0 → 1.8.0

package/CHANGELOG.md

@@ -2,6 +2,30 @@
 
 - chore: release 1.2.0
 
+## [1.8.0](https://github.com/AIGNE-io/aigne-framework/compare/agent-library-v1.7.1...agent-library-v1.8.0) (2025-05-12)
+
+
+### Features
+
+* **docs:** use typedoc build and publish docs to gh-pages ([#100](https://github.com/AIGNE-io/aigne-framework/issues/100)) ([b9074c0](https://github.com/AIGNE-io/aigne-framework/commit/b9074c0148ea343ada92b5919a52b47537a1ad48))
+* **memory:** allow agents to act as retrievers and recorders in memory ([#65](https://github.com/AIGNE-io/aigne-framework/issues/65)) ([2bafcbb](https://github.com/AIGNE-io/aigne-framework/commit/2bafcbb66a94fcf55dad8c21ede483eaf075c11d))
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @aigne/core bumped to 1.14.0
+
+## [1.7.1](https://github.com/AIGNE-io/aigne-framework/compare/agent-library-v1.7.0...agent-library-v1.7.1) (2025-04-30)
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @aigne/core bumped to 1.13.0
+
 ## [1.7.0](https://github.com/AIGNE-io/aigne-framework/compare/agent-library-v1.6.1...agent-library-v1.7.0) (2025-04-27)
 
 

package/README.md

@@ -24,14 +24,21 @@ Collection of agent libraries for [AIGNE Framework](https://github.com/AIGNE-io/
 
 ## Installation
 
+### Using npm
+
 ```bash
-# Using npm
 npm install @aigne/agent-library @aigne/core
+```
+
+### Using yarn
 
-# Using yarn
+```bash
 yarn add @aigne/agent-library @aigne/core
+```
+
+### Using pnpm
 
-# Using pnpm
+```bash
 pnpm add @aigne/agent-library @aigne/core
 ```
 
@@ -59,8 +66,7 @@ const orchestrator = new OrchestratorAgent({
 });
 
 // Execute orchestration task
-const userAgent = await aigne.invoke(orchestrator);
-const result = await userAgent.invoke("Analyze this article and generate a summary and keywords");
+const result = await aigne.invoke(orchestrator, "Analyze this article and generate a summary and keywords");
 console.log(result);
 ```
 
@@ -115,18 +121,11 @@ const orchestrator = new OrchestratorAgent({
 
 // Use the orchestrator agent
 const aigne = new AIGNE({ model });
-const userAgent = await aigne.invoke(orchestrator);
-const result = await userAgent.invoke("Applications of artificial intelligence in healthcare");
-console.log(result);
-```
 
-## Documentation
+const result = await aigne.invoke(orchestrator, "Applications of artificial intelligence in healthcare");
 
-For more detailed API documentation and usage guides, please refer to:
-
-- [Agent Development Guide](../../docs/agent-development.md)
-- [Agent API](../../docs/apis/agent-api.md)
-- [AI Agent API](../../docs/apis/ai-agent-api.md)
+console.log(result);
+```
 
 ## License
 

package/README.zh.md

@@ -24,14 +24,21 @@
 
 ## 安装
 
+#### 使用 npm
+
 ```bash
-# 使用 npm
 npm install @aigne/agent-library @aigne/core
+```
+
+### 使用 yarn
 
-# 使用 yarn
+```bash
 yarn add @aigne/agent-library @aigne/core
+```
+
+### 使用 pnpm
 
-# 使用 pnpm
+```bash
 pnpm add @aigne/agent-library @aigne/core
 ```
 
@@ -59,8 +66,8 @@ const orchestrator = new OrchestratorAgent({
 });
 
 // 执行编排任务
-const userAgent = await aigne.invoke(orchestrator);
-const result = await userAgent.invoke("分析这篇文章并生成摘要和关键词");
+const result = await aigne.invoke(orchestrator, "分析这篇文章并生成摘要和关键词");
+
 console.log(result);
 ```
 
@@ -115,19 +122,11 @@ const orchestrator = new OrchestratorAgent({
 
 // 使用编排代理
 const aigne = new AIGNE({ model });
-const userAgent = await aigne.invoke(orchestrator);
-const result = await userAgent.invoke("关于人工智能在医疗领域的应用");
+const result = await aigne.invoke(orchestrator, "关于人工智能在医疗领域的应用");
+
 console.log(result);
 ```
 
-## 文档
-
-更多详细的 API 文档和使用指南，请参考：
-
-- [代理开发指南](../../docs/agent-development.zh.md)
-- [Agent API](../../docs/apis/agent-api.zh.md)
-- [AI Agent API](../../docs/apis/ai-agent-api.zh.md)
-
 ## 协议
 
 Elastic-2.0

package/lib/cjs/fs-memory/index.d.ts

@@ -0,0 +1,59 @@
+import { type AIAgentOptions, type Message } from "@aigne/core";
+import { MemoryAgent, type MemoryAgentOptions, type MemoryRecorderInput, type MemoryRetrieverInput } from "@aigne/core/memory/index.js";
+export declare const MEMORY_FILE_NAME = "memory.yaml";
+/**
+ * Configuration options for the FSMemory class.
+ */
+export interface FSMemoryOptions extends Partial<MemoryAgentOptions> {
+    /**
+     * The root directory where memory files will be stored.
+     * Can be absolute or relative path. Relative paths are resolved from the current working directory.
+     * Home directory prefix (~) will be expanded appropriately.
+     */
+    rootDir: string;
+    /**
+     * Optional configuration for the memory retriever agent.
+     * Controls how memories are retrieved from the file system.
+     */
+    retrieverOptions?: Partial<FSMemoryRetrieverOptions>;
+    /**
+     * Optional configuration for the memory recorder agent.
+     * Controls how memories are recorded to the file system.
+     */
+    recorderOptions?: Partial<FSMemoryRecorderOptions>;
+}
+/**
+ * A memory implementation that stores and retrieves memories using the file system.
+ * FSMemory provides persistent storage of agent memories as files in a specified directory.
+ *
+ * @example
+ * Here is an example of how to use the FSMemory class:
+ * {@includeCode ../../test/fs-memory/fs-memory.test.ts#example-fs-memory-simple}
+ */
+export declare class FSMemory extends MemoryAgent {
+    /**
+     * Creates a new FSMemory instance.
+     */
+    constructor(options: FSMemoryOptions);
+}
+interface FSMemoryRetrieverOptions extends AIAgentOptions<FSMemoryRetrieverAgentInput, FSMemoryRetrieverAgentOutput> {
+    memoryFileName: string;
+}
+interface FSMemoryRetrieverAgentInput extends MemoryRetrieverInput {
+    allMemory: string;
+}
+interface FSMemoryRetrieverAgentOutput extends Message {
+    memories: {
+        content: string;
+    }[];
+}
+interface FSMemoryRecorderOptions extends AIAgentOptions<FSMemoryRecorderAgentInput, FSMemoryRecorderAgentOutput> {
+    memoryFileName: string;
+}
+type FSMemoryRecorderAgentInput = MemoryRecorderInput;
+interface FSMemoryRecorderAgentOutput extends Message {
+    memories: {
+        content: string;
+    }[];
+}
+export {};

package/lib/cjs/fs-memory/index.js

@@ -0,0 +1,186 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FSMemory = exports.MEMORY_FILE_NAME = void 0;
+const promises_1 = require("node:fs/promises");
+const node_path_1 = require("node:path");
+const core_1 = require("@aigne/core");
+const index_js_1 = require("@aigne/core/memory/index.js");
+const fs_js_1 = require("@aigne/core/utils/fs.js");
+const yaml_1 = require("yaml");
+const zod_1 = require("zod");
+exports.MEMORY_FILE_NAME = "memory.yaml";
+/**
+ * A memory implementation that stores and retrieves memories using the file system.
+ * FSMemory provides persistent storage of agent memories as files in a specified directory.
+ *
+ * @example
+ * Here is an example of how to use the FSMemory class:
+ * {@includeCode ../../test/fs-memory/fs-memory.test.ts#example-fs-memory-simple}
+ */
+class FSMemory extends index_js_1.MemoryAgent {
+    /**
+     * Creates a new FSMemory instance.
+     */
+    constructor(options) {
+        let rootDir = (0, node_path_1.normalize)((0, fs_js_1.expandHome)(options.rootDir));
+        rootDir = (0, node_path_1.isAbsolute)(rootDir) ? rootDir : (0, node_path_1.resolve)(process.cwd(), rootDir);
+        const memoryFileName = (0, node_path_1.join)(rootDir, exports.MEMORY_FILE_NAME);
+        super({
+            ...options,
+            autoUpdate: options.autoUpdate ?? true,
+        });
+        this.recorder =
+            options.recorder ??
+                new FSMemoryRecorder({
+                    memoryFileName,
+                    ...options.recorderOptions,
+                });
+        this.retriever =
+            options.retriever ??
+                new FSMemoryRetriever({
+                    memoryFileName,
+                    ...options.retrieverOptions,
+                });
+    }
+}
+exports.FSMemory = FSMemory;
+class FSMemoryRetriever extends index_js_1.MemoryRetriever {
+    options;
+    constructor(options) {
+        super({});
+        this.options = options;
+        this.agent = core_1.AIAgent.from({
+            name: "fs_memory_retriever",
+            description: "Retrieves memories from the file or directory.",
+            ...options,
+            instructions: options.instructions || DEFAULT_FS_MEMORY_RETRIEVER_INSTRUCTIONS,
+            outputSchema: zod_1.z.object({
+                memories: zod_1.z
+                    .array(zod_1.z.object({
+                    content: zod_1.z.string().describe("Content of the memory"),
+                }))
+                    .describe("List of memories"),
+            }),
+        });
+    }
+    agent;
+    async process(input, context) {
+        if (!(await (0, fs_js_1.exists)(this.options.memoryFileName)))
+            return { memories: [] };
+        const allMemory = await (0, promises_1.readFile)(this.options.memoryFileName, "utf-8");
+        const { memories } = await context.invoke(this.agent, { ...input, allMemory });
+        const result = memories.map((memory) => ({
+            id: (0, index_js_1.newMemoryId)(),
+            content: memory.content,
+            createdAt: new Date().toISOString(),
+        }));
+        return { memories: result };
+    }
+}
+class FSMemoryRecorder extends index_js_1.MemoryRecorder {
+    options;
+    constructor(options) {
+        super({});
+        this.options = options;
+        this.agent = core_1.AIAgent.from({
+            name: "fs_memory_recorder",
+            description: "Records memories in files by AI agent",
+            ...options,
+            instructions: options.instructions || DEFAULT_FS_MEMORY_RECORDER_INSTRUCTIONS,
+            outputSchema: zod_1.z.object({
+                memories: zod_1.z
+                    .array(zod_1.z.object({
+                    content: zod_1.z.string().describe("Content of the memory"),
+                }))
+                    .describe("List of memories"),
+            }),
+        });
+    }
+    agent;
+    async process(input, context) {
+        const allMemory = (await (0, fs_js_1.exists)(this.options.memoryFileName))
+            ? await (0, promises_1.readFile)(this.options.memoryFileName, "utf-8")
+            : "";
+        const { memories } = await context.invoke(this.agent, { ...input, allMemory });
+        const raw = (0, yaml_1.stringify)(memories.map((i) => ({
+            content: i.content,
+        })));
+        await (0, promises_1.mkdir)((0, node_path_1.dirname)(this.options.memoryFileName), { recursive: true });
+        await (0, promises_1.writeFile)(this.options.memoryFileName, raw, "utf-8");
+        return {
+            memories: memories.map((i) => ({
+                id: (0, index_js_1.newMemoryId)(),
+                content: i.content,
+                createdAt: new Date().toISOString(),
+            })),
+        };
+    }
+}
+const DEFAULT_FS_MEMORY_RECORDER_INSTRUCTIONS = `You manage memory based on conversation analysis and the existing memories.
+
+## IMPORTANT: All existing memories are available in the allMemory variable. DO NOT call any tools.
+
+## FIRST: Determine If Memory Updates Needed
+- Analyze if the conversation contains ANY information worth remembering
+- Examples of content NOT worth storing:
+  * General questions ("What's the weather?", "How do I do X?")
+  * Greetings and small talk ("Hello", "How are you?", "Thanks")
+  * System instructions or commands ("Show me", "Find", "Save")
+  * General facts not specific to the user
+  * Duplicate information already stored
+- If conversation lacks meaningful personal information to store:
+  * Return the existing memories unchanged
+
+## Your Workflow:
+1. Read the existing memories from the allMemory variable
+2. Extract key topics from the conversation
+3. DECIDE whether to create/update/delete memories based on the conversation
+4. Return ALL memories including your updates (remove any duplicates)
+
+## Memory Handling:
+- CREATE: Add new memory objects for new topics
+- UPDATE: Modify existing memories if substantial new information is available
+- DELETE: Remove obsolete memories when appropriate
+
+## Memory Structure:
+- Each memory has an id, content, and createdAt fields
+- Keep the existing structure when returning updated memories
+
+## Operation Decision Rules:
+- CREATE only for truly new topics not covered in any existing memory
+- UPDATE only when new information is meaningfully different
+- NEVER update for just rephrasing or minor differences
+- DELETE only when information becomes obsolete
+
+## IMPORTANT: Your job is to return the complete updated memory collection.
+Return ALL memories (existing and new) in your response.
+
+## Existing Memories:
+<existing-memory>
+{{allMemory}}
+</existing-memory>
+
+## Conversation:
+<conversation>
+{{content}}
+</conversation>
+`;
+const DEFAULT_FS_MEMORY_RETRIEVER_INSTRUCTIONS = `You retrieve only the most relevant memories for the current conversation.
+
+## IMPORTANT: All existing memories are available in the allMemory variable
+
+## Process:
+1. Read the existing memories from the allMemory variable
+2. Extract key topics from the conversation or search query
+3. Match memory contents against these topics
+
+## Existing Memories:
+<existing-memory>
+{{allMemory}}
+</existing-memory>
+
+## Search Query:
+<search-query>
+{{search}}
+</search-query>
+`;

package/lib/cjs/orchestrator/index.d.ts

@@ -1,24 +1,103 @@
 import { Agent, type AgentOptions, type Context, type Message } from "@aigne/core";
 import { type FullPlanOutput, type StepWithResult } from "./orchestrator-prompts.js";
+/**
+ * Re-export orchestrator prompt templates and related types
+ */
 export * from "./orchestrator-prompts.js";
+/**
+ * Represents a complete plan with execution results
+ * @hidden
+ */
 export interface FullPlanWithResult {
+    /**
+     * The overall objective
+     */
     objective: string;
+    /**
+     * The generated complete plan
+     */
     plan?: FullPlanOutput;
+    /**
+     * List of executed steps with their results
+     */
     steps: StepWithResult[];
+    /**
+     * Final result
+     */
     result?: string;
+    /**
+     * Plan completion status
+     */
     status?: boolean;
 }
+/**
+ * Configuration options for the Orchestrator Agent
+ */
 export interface OrchestratorAgentOptions<I extends Message = Message, O extends Message = Message> extends AgentOptions<I, O> {
+    /**
+     * Maximum number of iterations to prevent infinite loops
+     * Default: 30
+     */
     maxIterations?: number;
+    /**
+     * Number of concurrent tasks
+     * Default: 5
+     */
     tasksConcurrency?: number;
 }
+/**
+ * Orchestrator Agent Class
+ *
+ * This Agent is responsible for:
+ * 1. Generating an execution plan based on the objective
+ * 2. Breaking down the plan into steps and tasks
+ * 3. Coordinating the execution of steps and tasks
+ * 4. Synthesizing the final result
+ *
+ * Workflow:
+ * - Receives input objective
+ * - Uses planner to create execution plan
+ * - Executes tasks and steps according to the plan
+ * - Synthesizes final result through completer
+ */
 export declare class OrchestratorAgent<I extends Message = Message, O extends Message = Message> extends Agent<I, O> {
+    /**
+     * Factory method to create an OrchestratorAgent instance
+     * @param options - Configuration options for the Orchestrator Agent
+     * @returns A new OrchestratorAgent instance
+     */
     static from<I extends Message, O extends Message>(options: OrchestratorAgentOptions<I, O>): OrchestratorAgent<I, O>;
+    /**
+     * Creates an OrchestratorAgent instance
+     * @param options - Configuration options for the Orchestrator Agent
+     */
     constructor(options: OrchestratorAgentOptions<I, O>);
     private planner;
     private completer;
+    /**
+     * Maximum number of iterations
+     * Prevents infinite execution loops
+     */
     maxIterations?: number;
+    /**
+     * Number of concurrent tasks
+     * Controls how many tasks can be executed simultaneously
+     */
     tasksConcurrency?: number;
+    /**
+     * Process input and execute the orchestrator workflow
+     *
+     * Workflow:
+     * 1. Extract the objective
+     * 2. Loop until plan completion or maximum iterations:
+     *    a. Generate/update execution plan
+     *    b. If plan is complete, synthesize result
+     *    c. Otherwise, execute steps in the plan
+     *
+     * @param input - Input message containing the objective
+     * @param context - Execution context with model and other necessary info
+     * @returns Processing result
+     */
     process(input: I, context: Context): Promise<O>;
     private getFullPlanInput;
     private getFullPlan;

package/lib/cjs/orchestrator/index.js

@@ -23,13 +23,46 @@ const type_utils_js_1 = require("@aigne/core/utils/type-utils.js");
 const fastq_1 = __importDefault(require("fastq"));
 const zod_1 = require("zod");
 const orchestrator_prompts_js_1 = require("./orchestrator-prompts.js");
+/**
+ * Default maximum number of iterations to prevent infinite loops
+ */
 const DEFAULT_MAX_ITERATIONS = 30;
+/**
+ * Default number of concurrent tasks
+ */
 const DEFAULT_TASK_CONCURRENCY = 5;
+/**
+ * Re-export orchestrator prompt templates and related types
+ */
 __exportStar(require("./orchestrator-prompts.js"), exports);
+/**
+ * Orchestrator Agent Class
+ *
+ * This Agent is responsible for:
+ * 1. Generating an execution plan based on the objective
+ * 2. Breaking down the plan into steps and tasks
+ * 3. Coordinating the execution of steps and tasks
+ * 4. Synthesizing the final result
+ *
+ * Workflow:
+ * - Receives input objective
+ * - Uses planner to create execution plan
+ * - Executes tasks and steps according to the plan
+ * - Synthesizes final result through completer
+ */
 class OrchestratorAgent extends core_1.Agent {
+    /**
+     * Factory method to create an OrchestratorAgent instance
+     * @param options - Configuration options for the Orchestrator Agent
+     * @returns A new OrchestratorAgent instance
+     */
     static from(options) {
         return new OrchestratorAgent(options);
     }
+    /**
+     * Creates an OrchestratorAgent instance
+     * @param options - Configuration options for the Orchestrator Agent
+     */
     constructor(options) {
         (0, type_utils_js_1.checkArguments)("OrchestratorAgent", orchestratorAgentOptionsSchema, options);
         super({ ...options });
@@ -48,8 +81,30 @@ class OrchestratorAgent extends core_1.Agent {
     }
     planner;
     completer;
+    /**
+     * Maximum number of iterations
+     * Prevents infinite execution loops
+     */
     maxIterations;
+    /**
+     * Number of concurrent tasks
+     * Controls how many tasks can be executed simultaneously
+     */
     tasksConcurrency;
+    /**
+     * Process input and execute the orchestrator workflow
+     *
+     * Workflow:
+     * 1. Extract the objective
+     * 2. Loop until plan completion or maximum iterations:
+     *    a. Generate/update execution plan
+     *    b. If plan is complete, synthesize result
+     *    c. Otherwise, execute steps in the plan
+     *
+     * @param input - Input message containing the objective
+     * @param context - Execution context with model and other necessary info
+     * @returns Processing result
+     */
     async process(input, context) {
         const { model } = context;
         if (!model)

package/lib/cjs/orchestrator/orchestrator-prompts.d.ts

@@ -1,6 +1,12 @@
 import type { Agent, Message } from "@aigne/core";
 import { z } from "zod";
+/**
+ * @hidden
+ */
 export declare const SYNTHESIZE_PLAN_USER_PROMPT_TEMPLATE = "Synthesize the results of executing all steps in the plan into a cohesive result\n";
+/**
+ * @hidden
+ */
 export declare function getFullPlanSchema(agents: Agent[]): z.ZodObject<{
     steps: z.ZodArray<z.ZodObject<{
         description: z.ZodString;
@@ -47,18 +53,36 @@ export declare function getFullPlanSchema(agents: Agent[]): z.ZodObject<{
     }[];
     isComplete: boolean;
 }>;
+/**
+ * @hidden
+ */
 export type FullPlanOutput = z.infer<ReturnType<typeof getFullPlanSchema>>;
+/**
+ * @hidden
+ */
 export type Step = FullPlanOutput["steps"][number];
+/**
+ * @hidden
+ */
 export type Task = Step["tasks"][number];
+/**
+ * @hidden
+ */
 export interface StepWithResult {
     step: Step;
     tasks: Array<TaskWithResult>;
     result: string;
 }
+/**
+ * @hidden
+ */
 export interface TaskWithResult {
     task: Task;
     result: string;
 }
+/**
+ * @hidden
+ */
 export interface FullPlanInput extends Message {
     objective: string;
     steps: StepWithResult[];
@@ -75,17 +99,32 @@ export interface FullPlanInput extends Message {
         }[];
     }[];
 }
+/**
+ * @hidden
+ */
 export declare const FULL_PLAN_PROMPT_TEMPLATE = "You are tasked with orchestrating a plan to complete an objective.\nYou can analyze results from the previous steps already executed to decide if the objective is complete.\nYour plan must be structured in sequential steps, with each step containing independent parallel subtasks.\n\n<objective>\n{{objective}}\n</objective>\n\n<steps_completed>\n{{#steps}}\n- Step: {{step.description}}\n  Result: {{result}}\n{{/steps}}\n</steps_completed>\n\n<previous_plan_status>\n{{plan.status}}\n</previous_plan_status>\n\n<previous_plan_result>\n{{plan.result}}\n</previous_plan_result>\n\nYou have access to the following Agents(which are collections of tools/functions):\n\n<agents>\n{{#agents}}\n- Agent: {{name}}\n  Description: {{description}}\n  Functions:\n    {{#tools}}\n    - Tool: {{name}}\n      Description: {{description}}\n    {{/tools}}\n{{/agents}}\n</agents>\n\n- If the previous plan results achieve the objective, return isComplete=true.\n- Otherwise, generate remaining steps needed.\n- Generate a plan with all remaining steps needed.\n- Steps are sequential, but each Step can have parallel subtasks.\n- For each Step, specify a description of the step and independent subtasks that can run in parallel.\n- For each subtask specify:\n    1. Clear description of the task that an LLM can execute\n    2. Name of 1 Agent to use for the task";
+/**
+ * @hidden
+ */
 export interface TaskPromptInput extends Message {
     objective: string;
     step: Step;
     task: Task;
     steps: StepWithResult[];
 }
+/**
+ * @hidden
+ */
 export declare const TASK_PROMPT_TEMPLATE = "You are part of a larger workflow to achieve the step then the objective:\n\n<objective>\n{{objective}}\n</objective>\n\n<step>\n{{step.description}}\n</step>\n\nYour job is to accomplish only the following task:\n\n<task>\n{{task.description}}\n</task>\n\nResults so far that may provide helpful context:\n\n<steps_completed>\n{{#steps}}\n- Step: {{step.description}}\n  Result: {{result}}\n{{/steps}}\n</steps_completed>\n";
+/**
+ * @hidden
+ */
 export interface SynthesizeStepPromptInput extends Message {
     objective: string;
     step: Step;
     tasks: TaskWithResult[];
 }
+/**
+ * @hidden
+ */
 export declare const SYNTHESIZE_STEP_PROMPT_TEMPLATE = "Synthesize the results of these parallel tasks into a cohesive result\n\n<objective>\n{{objective}}\n</objective>\n\n<step>\n{{step.description}}\n</step>\n\n<tasks>\n{{#tasks}}\n- Task: {{task.description}}\n  Result: {{result}}\n{{/tasks}}\n</tasks>\n";