@aigne/core 1.70.1 → 1.71.0-beta.1

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## [1.71.0-beta.1](https://github.com/AIGNE-io/aigne-framework/compare/core-v1.71.0-beta...core-v1.71.0-beta.1) (2025-12-08)
+
+
+### Bug Fixes
+
+* correct run example & doc improvements ([#707](https://github.com/AIGNE-io/aigne-framework/issues/707)) ([f98fc5d](https://github.com/AIGNE-io/aigne-framework/commit/f98fc5df28fd6ce6134128c2f0e5395c1554b740))
+
+## [1.71.0-beta](https://github.com/AIGNE-io/aigne-framework/compare/core-v1.70.1...core-v1.71.0-beta) (2025-12-07)
+
+
+### Features
+
+* support define agent by third library & orchestrator agent refactor ([#799](https://github.com/AIGNE-io/aigne-framework/issues/799)) ([7264b11](https://github.com/AIGNE-io/aigne-framework/commit/7264b11ab6eed787e928367f09aa08d254968d40))
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @aigne/afs bumped to 1.3.0-beta
+    * @aigne/afs-history bumped to 1.1.3-beta
+
 ## [1.70.1](https://github.com/AIGNE-io/aigne-framework/compare/core-v1.70.1-beta...core-v1.70.1) (2025-12-06)
 
 

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

@@ -205,6 +205,10 @@ export declare abstract class Agent<I extends Message = any, O extends Message =
      * @returns Agent name
      */
     [nodejs.customInspect]: () => string;
+    static load<I extends Message = any, O extends Message = any>(_options: {
+        filepath: string;
+        parsed: object;
+    }): Promise<Agent<I, O>>;
     constructor(options?: AgentOptions<I, O>);
     /**
      * List of memories this agent can use

package/lib/cjs/agents/agent.js

@@ -125,6 +125,9 @@ exports.agentOptionsSchema = zod_1.z.object({
  * {@includeCode ../../test/agents/agent.test.ts#example-custom-agent}
  */
 class Agent {
+    static async load(_options) {
+        throw new Error("Not implemented");
+    }
     constructor(options = {}) {
         (0, type_utils_js_1.checkArguments)("Agent options", exports.agentOptionsSchema, options);
         const { inputSchema, outputSchema } = options;

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

@@ -37,10 +37,10 @@ class ImageAgent extends agent_js_1.Agent {
         if (!imageModel)
             throw new Error("image model is required to run ImageAgent");
         const modelOptions = await imageModel.getModelOptions(input, options);
-        const { prompt, image } = await this.instructions.buildImagePrompt({
+        const { prompt, image } = await this.instructions.buildPrompt({
             ...options,
             input,
-            agent: this,
+            inputFileKey: this.inputFileKey,
         });
         const n = input.n || modelOptions?.n;
         return (await this.invokeChildAgent(imageModel, {

package/lib/cjs/agents/types.d.ts

@@ -1,5 +1,5 @@
 import z, { type ZodType } from "zod";
-import { type Agent, DEFAULT_INPUT_ACTION_GET, type Message } from "./agent.js";
+import { type Agent, type AgentOptions, DEFAULT_INPUT_ACTION_GET, type Message } from "./agent.js";
 export declare const transferAgentOutputKey = "$transferAgentTo";
 export interface TransferAgentOutput extends Message {
     [transferAgentOutputKey]: {
@@ -21,3 +21,11 @@ export declare function getterSchema<T extends ZodType>(schema: T): z.ZodUnion<[
 }, {
     $get: string;
 }>]>;
+export interface AgentClass {
+    new (...args: any[]): Agent<any, any>;
+    load<I extends Message = any, O extends Message = any>(options: {
+        filepath: string;
+        parsed: AgentOptions;
+        [key: string]: any;
+    }): Promise<Agent<I, O>>;
+}

package/lib/cjs/loader/agent-js.d.ts

@@ -1,2 +1 @@
-import { Agent } from "../agents/agent.js";
-export declare function loadAgentFromJsFile(path: string): Promise<Agent<any, any> | import("./agent-yaml.js").AgentSchema>;
+export declare function loadAgentFromJsFile(path: string): Promise<import("../index.js").Agent<any, any> | import("./agent-yaml.js").AgentSchema>;

package/lib/cjs/loader/agent-js.js

@@ -2,7 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.loadAgentFromJsFile = loadAgentFromJsFile;
 const index_js_1 = require("@aigne/platform-helpers/nodejs/index.js");
-const agent_js_1 = require("../agents/agent.js");
+const agent_utils_js_1 = require("../utils/agent-utils.js");
 const type_utils_js_1 = require("../utils/type-utils.js");
 const agent_yaml_js_1 = require("./agent-yaml.js");
 const error_js_1 = require("./error.js");
@@ -10,7 +10,7 @@ const importFn = new Function("path", "return import(path)");
 async function loadAgentFromJsFile(path) {
     const url = index_js_1.nodejs.path.isAbsolute(path) ? index_js_1.nodejs.url.pathToFileURL(path).toString() : path;
     const { default: agent } = await (0, type_utils_js_1.tryOrThrow)(() => importFn(url), (error) => new error_js_1.LoadJsAgentError(`Failed to load agent definition from ${url}: ${error.message}`));
-    if (agent instanceof agent_js_1.Agent)
+    if ((0, agent_utils_js_1.isAgent)(agent))
         return agent;
     return (0, type_utils_js_1.tryOrThrow)(() => (0, agent_yaml_js_1.parseAgentFile)(path, {
         type: "function",

package/lib/cjs/loader/agent-yaml.d.ts

@@ -1,9 +1,10 @@
 import type { AFSOptions } from "@aigne/afs";
 import { type ZodType, z } from "zod";
-import type { AgentHooks, FunctionAgentFn, TaskRenderMode } from "../agents/agent.js";
+import type { AgentClass, AgentHooks, FunctionAgentFn, TaskRenderMode } from "../agents/agent.js";
 import { AIAgentToolChoice } from "../agents/ai-agent.js";
 import { type Role } from "../agents/chat-model.js";
 import { ProcessMode, type ReflectionMode } from "../agents/team-agent.js";
+import type { LoadOptions } from "./index.js";
 import { chatModelSchema, imageModelSchema } from "./schema.js";
 export interface HooksSchema {
     priority?: AgentHooks["priority"];
@@ -44,6 +45,7 @@ export interface BaseAgentSchema {
     afs?: boolean | (Omit<AFSOptions, "modules"> & {
         modules?: AFSModuleSchema[];
     });
+    shareAFS?: boolean;
 }
 export type Instructions = {
     role: Exclude<Role, "tool">;
@@ -93,6 +95,20 @@ export interface FunctionAgentSchema extends BaseAgentSchema {
     type: "function";
     process: FunctionAgentFn;
 }
-export type AgentSchema = AIAgentSchema | ImageAgentSchema | MCPAgentSchema | TeamAgentSchema | TransformAgentSchema | FunctionAgentSchema;
+export interface ThirdAgentSchema extends BaseAgentSchema {
+    agentClass?: AgentClass;
+    type: "";
+    [key: string]: any;
+}
+export type AgentSchema = AIAgentSchema | ImageAgentSchema | MCPAgentSchema | TeamAgentSchema | TransformAgentSchema | FunctionAgentSchema | ThirdAgentSchema;
 export declare function parseAgentFile(path: string, data: any): Promise<AgentSchema>;
-export declare function loadAgentFromYamlFile(path: string): Promise<AgentSchema>;
+export declare function loadAgentFromYamlFile(path: string, options?: LoadOptions): Promise<AgentSchema>;
+export declare const getInstructionsSchema: ({ filepath }: {
+    filepath: string;
+}) => ZodType<Instructions>;
+export declare const getAgentSchema: ({ filepath }: {
+    filepath: string;
+}) => ZodType<AgentSchema, z.ZodTypeDef, AgentSchema>;
+export declare const getNestAgentSchema: ({ filepath, }: {
+    filepath: string;
+}) => ZodType<NestAgentSchema>;

package/lib/cjs/loader/agent-yaml.js

@@ -1,5 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.getNestAgentSchema = exports.getAgentSchema = exports.getInstructionsSchema = void 0;
 exports.parseAgentFile = parseAgentFile;
 exports.loadAgentFromYamlFile = loadAgentFromYamlFile;
 const json_schema_to_zod_1 = require("@aigne/json-schema-to-zod");
@@ -13,6 +14,69 @@ const type_utils_js_1 = require("../utils/type-utils.js");
 const function_agent_js_1 = require("./function-agent.js");
 const schema_js_1 = require("./schema.js");
 async function parseAgentFile(path, data) {
+    const agentSchema = (0, exports.getAgentSchema)({ filepath: path });
+    return agentSchema.parseAsync({
+        ...data,
+        model: data.model || data.chatModel || data.chat_model,
+    });
+}
+async function loadAgentFromYamlFile(path, options) {
+    const raw = await (0, type_utils_js_1.tryOrThrow)(() => index_js_1.nodejs.fs.readFile(path, "utf8"), (error) => new Error(`Failed to load agent definition from ${path}: ${error.message}`));
+    const json = (0, type_utils_js_1.tryOrThrow)(() => (0, yaml_1.parse)(raw), (error) => new Error(`Failed to parse agent definition from ${path}: ${error.message}`));
+    if (!["ai", "image", "mcp", "team", "transform", "function"].includes(json?.type)) {
+        if (typeof json?.type === "string") {
+            if (!options?.require)
+                throw new Error(`Module loader is not provided to load agent type module ${json.type} from ${path}`);
+            const Mod = await options.require(json.type, { parent: path });
+            if (typeof Mod?.default?.prototype?.constructor !== "function") {
+                throw new Error(`The agent type module ${json.type} does not export a default Agent class`);
+            }
+            json.agentClass = Mod.default;
+        }
+    }
+    const agent = await (0, type_utils_js_1.tryOrThrow)(async () => await parseAgentFile(path, {
+        ...json,
+        type: json.type ?? "ai",
+        skills: json.skills ?? json.tools,
+    }), (error) => new Error(`Failed to validate agent definition from ${path}: ${error.message}`));
+    return agent;
+}
+const instructionItemSchema = zod_1.z.union([
+    zod_1.z.object({
+        role: chat_model_js_1.roleSchema.default("system"),
+        url: zod_1.z.string(),
+    }),
+    zod_1.z.object({
+        role: chat_model_js_1.roleSchema.default("system"),
+        content: zod_1.z.string(),
+    }),
+]);
+const parseInstructionItem = ({ filepath }) => async ({ role, ...v }) => {
+    if (role === "tool")
+        throw new Error(`'tool' role is not allowed in instruction item in agent file ${filepath}`);
+    if ("content" in v && typeof v.content === "string") {
+        return { role, content: v.content, path: filepath };
+    }
+    if ("url" in v && typeof v.url === "string") {
+        const url = index_js_1.nodejs.path.isAbsolute(v.url)
+            ? v.url
+            : index_js_1.nodejs.path.join(index_js_1.nodejs.path.dirname(filepath), v.url);
+        return index_js_1.nodejs.fs.readFile(url, "utf8").then((content) => ({ role, content, path: url }));
+    }
+    throw new Error(`Invalid instruction item in agent file ${filepath}. Expected 'content' or 'url' property`);
+};
+const getInstructionsSchema = ({ filepath }) => zod_1.z
+    .union([zod_1.z.string(), instructionItemSchema, zod_1.z.array(instructionItemSchema)])
+    .transform(async (v) => {
+    if (typeof v === "string")
+        return [{ role: "system", content: v, path: filepath }];
+    if (Array.isArray(v)) {
+        return Promise.all(v.map((item) => parseInstructionItem({ filepath })(item)));
+    }
+    return [await parseInstructionItem({ filepath })(v)];
+});
+exports.getInstructionsSchema = getInstructionsSchema;
+const getAgentSchema = ({ filepath }) => {
     const agentSchema = zod_1.z.lazy(() => {
         const nestAgentSchema = zod_1.z.lazy(() => zod_1.z.union([
             agentSchema,
@@ -41,9 +105,9 @@ async function parseAgentFile(path, data) {
             imageModel: (0, schema_js_1.optionalize)(schema_js_1.imageModelSchema),
             taskTitle: (0, schema_js_1.optionalize)(zod_1.z.string()),
             taskRenderMode: (0, schema_js_1.optionalize)(zod_1.z.union([zod_1.z.literal("hide"), zod_1.z.literal("collapse")])),
-            inputSchema: (0, schema_js_1.optionalize)((0, schema_js_1.inputOutputSchema)({ path })).transform((v) => v ? (0, json_schema_to_zod_1.jsonSchemaToZod)(v) : undefined),
+            inputSchema: (0, schema_js_1.optionalize)((0, schema_js_1.inputOutputSchema)({ path: filepath })).transform((v) => v ? (0, json_schema_to_zod_1.jsonSchemaToZod)(v) : undefined),
             defaultInput: (0, schema_js_1.optionalize)(schema_js_1.defaultInputSchema),
-            outputSchema: (0, schema_js_1.optionalize)((0, schema_js_1.inputOutputSchema)({ path })).transform((v) => v ? (0, json_schema_to_zod_1.jsonSchemaToZod)(v) : undefined),
+            outputSchema: (0, schema_js_1.optionalize)((0, schema_js_1.inputOutputSchema)({ path: filepath })).transform((v) => v ? (0, json_schema_to_zod_1.jsonSchemaToZod)(v) : undefined),
             includeInputInOutput: (0, schema_js_1.optionalize)(zod_1.z.boolean()),
             hooks: (0, schema_js_1.optionalize)(zod_1.z.union([hooksSchema, zod_1.z.array(hooksSchema)])),
             skills: (0, schema_js_1.optionalize)(zod_1.z.array(nestAgentSchema)),
@@ -66,117 +130,94 @@ async function parseAgentFile(path, data) {
                     ]))),
                 })),
             ])),
+            shareAFS: (0, schema_js_1.optionalize)(zod_1.z.boolean()),
         });
-        const instructionItemSchema = zod_1.z.union([
-            zod_1.z.object({
-                role: chat_model_js_1.roleSchema.default("system"),
-                url: zod_1.z.string(),
-            }),
-            zod_1.z.object({
-                role: chat_model_js_1.roleSchema.default("system"),
-                content: zod_1.z.string(),
-            }),
-        ]);
-        const parseInstructionItem = async ({ role, ...v }) => {
-            if (role === "tool")
-                throw new Error(`'tool' role is not allowed in instruction item in agent file ${path}`);
-            if ("content" in v && typeof v.content === "string") {
-                return { role, content: v.content, path };
-            }
-            if ("url" in v && typeof v.url === "string") {
-                const url = index_js_1.nodejs.path.isAbsolute(v.url)
-                    ? v.url
-                    : index_js_1.nodejs.path.join(index_js_1.nodejs.path.dirname(path), v.url);
-                return index_js_1.nodejs.fs.readFile(url, "utf8").then((content) => ({ role, content, path: url }));
-            }
-            throw new Error(`Invalid instruction item in agent file ${path}. Expected 'content' or 'url' property`);
-        };
-        const instructionsSchema = zod_1.z
-            .union([zod_1.z.string(), instructionItemSchema, zod_1.z.array(instructionItemSchema)])
-            .transform(async (v) => {
-            if (typeof v === "string")
-                return [{ role: "system", content: v, path }];
-            if (Array.isArray(v)) {
-                return Promise.all(v.map((item) => parseInstructionItem(item)));
-            }
-            return [await parseInstructionItem(v)];
-        });
-        return (0, schema_js_1.camelizeSchema)(zod_1.z.discriminatedUnion("type", [
-            zod_1.z
-                .object({
-                type: zod_1.z.literal("ai"),
-                instructions: (0, schema_js_1.optionalize)(instructionsSchema),
-                autoReorderSystemMessages: (0, schema_js_1.optionalize)(zod_1.z.boolean()),
-                autoMergeSystemMessages: (0, schema_js_1.optionalize)(zod_1.z.boolean()),
-                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(ai_agent_js_1.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()),
-            })
-                .extend(baseAgentSchema.shape),
-            zod_1.z
-                .object({
-                type: zod_1.z.literal("image"),
-                instructions: instructionsSchema,
-                inputFileKey: (0, schema_js_1.optionalize)(zod_1.z.string()),
-            })
-                .extend(baseAgentSchema.shape),
-            zod_1.z
-                .object({
-                type: zod_1.z.literal("mcp"),
-                url: (0, schema_js_1.optionalize)(zod_1.z.string()),
-                command: (0, schema_js_1.optionalize)(zod_1.z.string()),
-                args: (0, schema_js_1.optionalize)(zod_1.z.array(zod_1.z.string())),
-            })
-                .extend(baseAgentSchema.shape),
-            zod_1.z
-                .object({
-                type: zod_1.z.literal("team"),
-                mode: (0, schema_js_1.optionalize)(zod_1.z.nativeEnum(team_agent_js_1.ProcessMode)),
-                iterateOn: (0, schema_js_1.optionalize)(zod_1.z.string()),
-                concurrency: (0, schema_js_1.optionalize)(zod_1.z.number().int().min(1)),
-                iterateWithPreviousOutput: (0, schema_js_1.optionalize)(zod_1.z.boolean()),
-                includeAllStepsOutput: (0, schema_js_1.optionalize)(zod_1.z.boolean()),
-                reflection: (0, schema_js_1.camelizeSchema)((0, schema_js_1.optionalize)(zod_1.z.object({
-                    reviewer: nestAgentSchema,
-                    isApproved: zod_1.z.string(),
-                    maxIterations: (0, schema_js_1.optionalize)(zod_1.z.number().int().min(1)),
-                    returnLastOnMaxIterations: (0, schema_js_1.optionalize)(zod_1.z.boolean()),
-                    customErrorMessage: (0, schema_js_1.optionalize)(zod_1.z.string()),
-                }))),
-            })
-                .extend(baseAgentSchema.shape),
+        const instructionsSchema = (0, exports.getInstructionsSchema)({ filepath: filepath });
+        return (0, schema_js_1.camelizeSchema)(zod_1.z.union([
             zod_1.z
                 .object({
-                type: zod_1.z.literal("transform"),
-                jsonata: zod_1.z.string(),
+                type: zod_1.z.string(),
+                agentClass: zod_1.z.custom((v) => typeof v?.prototype?.constructor === "function"),
             })
-                .extend(baseAgentSchema.shape),
-            zod_1.z
-                .object({
-                type: zod_1.z.literal("function"),
-                process: zod_1.z.preprocess((v) => (typeof v === "string" ? (0, function_agent_js_1.codeToFunctionAgentFn)(v) : v), zod_1.z.custom()),
-            })
-                .extend(baseAgentSchema.shape),
+                .extend(baseAgentSchema.shape)
+                .passthrough(),
+            zod_1.z.discriminatedUnion("type", [
+                zod_1.z
+                    .object({
+                    type: zod_1.z.literal("ai"),
+                    instructions: (0, schema_js_1.optionalize)(instructionsSchema),
+                    autoReorderSystemMessages: (0, schema_js_1.optionalize)(zod_1.z.boolean()),
+                    autoMergeSystemMessages: (0, schema_js_1.optionalize)(zod_1.z.boolean()),
+                    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(ai_agent_js_1.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()),
+                })
+                    .extend(baseAgentSchema.shape),
+                zod_1.z
+                    .object({
+                    type: zod_1.z.literal("image"),
+                    instructions: instructionsSchema,
+                    inputFileKey: (0, schema_js_1.optionalize)(zod_1.z.string()),
+                })
+                    .extend(baseAgentSchema.shape),
+                zod_1.z
+                    .object({
+                    type: zod_1.z.literal("mcp"),
+                    url: (0, schema_js_1.optionalize)(zod_1.z.string()),
+                    command: (0, schema_js_1.optionalize)(zod_1.z.string()),
+                    args: (0, schema_js_1.optionalize)(zod_1.z.array(zod_1.z.string())),
+                })
+                    .extend(baseAgentSchema.shape),
+                zod_1.z
+                    .object({
+                    type: zod_1.z.literal("team"),
+                    mode: (0, schema_js_1.optionalize)(zod_1.z.nativeEnum(team_agent_js_1.ProcessMode)),
+                    iterateOn: (0, schema_js_1.optionalize)(zod_1.z.string()),
+                    concurrency: (0, schema_js_1.optionalize)(zod_1.z.number().int().min(1)),
+                    iterateWithPreviousOutput: (0, schema_js_1.optionalize)(zod_1.z.boolean()),
+                    includeAllStepsOutput: (0, schema_js_1.optionalize)(zod_1.z.boolean()),
+                    reflection: (0, schema_js_1.camelizeSchema)((0, schema_js_1.optionalize)(zod_1.z.object({
+                        reviewer: nestAgentSchema,
+                        isApproved: zod_1.z.string(),
+                        maxIterations: (0, schema_js_1.optionalize)(zod_1.z.number().int().min(1)),
+                        returnLastOnMaxIterations: (0, schema_js_1.optionalize)(zod_1.z.boolean()),
+                        customErrorMessage: (0, schema_js_1.optionalize)(zod_1.z.string()),
+                    }))),
+                })
+                    .extend(baseAgentSchema.shape),
+                zod_1.z
+                    .object({
+                    type: zod_1.z.literal("transform"),
+                    jsonata: zod_1.z.string(),
+                })
+                    .extend(baseAgentSchema.shape),
+                zod_1.z
+                    .object({
+                    type: zod_1.z.literal("function"),
+                    process: zod_1.z.preprocess((v) => (typeof v === "string" ? (0, function_agent_js_1.codeToFunctionAgentFn)(v) : v), zod_1.z.custom()),
+                })
+                    .extend(baseAgentSchema.shape),
+            ]),
         ]));
     });
-    return agentSchema.parseAsync({
-        ...data,
-        model: data.model || data.chatModel || data.chat_model,
-    });
-}
-async function loadAgentFromYamlFile(path) {
-    const raw = await (0, type_utils_js_1.tryOrThrow)(() => index_js_1.nodejs.fs.readFile(path, "utf8"), (error) => new Error(`Failed to load agent definition from ${path}: ${error.message}`));
-    const json = (0, type_utils_js_1.tryOrThrow)(() => (0, yaml_1.parse)(raw), (error) => new Error(`Failed to parse agent definition from ${path}: ${error.message}`));
-    const agent = await (0, type_utils_js_1.tryOrThrow)(async () => await parseAgentFile(path, {
-        ...json,
-        type: json.type ?? "ai",
-        skills: json.skills ?? json.tools,
-    }), (error) => new Error(`Failed to validate agent definition from ${path}: ${error.message}`));
-    return agent;
-}
+    return agentSchema;
+};
+exports.getAgentSchema = getAgentSchema;
+const getNestAgentSchema = ({ filepath, }) => {
+    const agentSchema = (0, exports.getAgentSchema)({ filepath });
+    return zod_1.z.lazy(() => zod_1.z.union([
+        agentSchema,
+        zod_1.z.string(),
+        (0, schema_js_1.camelizeSchema)(zod_1.z.object({
+            url: zod_1.z.string(),
+            defaultInput: (0, schema_js_1.optionalize)(schema_js_1.defaultInputSchema),
+        })),
+    ]));
+};
+exports.getNestAgentSchema = getNestAgentSchema;

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

@@ -1,11 +1,13 @@
-import { type AFSModule } from "@aigne/afs";
+import { AFS, type AFSModule } from "@aigne/afs";
 import { type ZodType, z } from "zod";
 import { Agent, type AgentOptions } from "../agents/agent.js";
 import type { ChatModel } from "../agents/chat-model.js";
 import type { ImageModel } from "../agents/image-model.js";
 import type { AIGNEOptions } from "../aigne/aigne.js";
 import type { MemoryAgent, MemoryAgentOptions } from "../memory/memory.js";
+import { PromptBuilder } from "../prompt/prompt-builder.js";
 import { type PromiseOrValue } from "../utils/type-utils.js";
+import { type Instructions, loadAgentFromYamlFile, type NestAgentSchema } from "./agent-yaml.js";
 export interface LoadOptions {
     memories?: {
         new (parameters?: MemoryAgentOptions): MemoryAgent;
@@ -13,6 +15,7 @@ export interface LoadOptions {
     model?: ChatModel | ((model?: z.infer<typeof aigneFileSchema>["model"]) => PromiseOrValue<ChatModel | undefined>);
     imageModel?: ImageModel | ((model?: z.infer<typeof aigneFileSchema>["imageModel"]) => PromiseOrValue<ImageModel | undefined>);
     afs?: {
+        sharedAFS?: AFS;
         availableModules?: {
             module: string;
             alias?: string[];
@@ -20,9 +23,14 @@ export interface LoadOptions {
         }[];
     };
     aigne?: z.infer<typeof aigneFileSchema>;
+    require?: (modulePath: string, options: {
+        parent?: string;
+    }) => Promise<any>;
 }
 export declare function load(path: string, options?: LoadOptions): Promise<AIGNEOptions>;
 export declare function loadAgent(path: string, options?: LoadOptions, agentOptions?: AgentOptions): Promise<Agent>;
+export declare function loadNestAgent(path: string, agent: NestAgentSchema, options?: LoadOptions, agentOptions?: AgentOptions & Record<string, unknown>): Promise<Agent>;
+export declare function parseAgent(path: string, agent: Awaited<ReturnType<typeof loadAgentFromYamlFile>>, options?: LoadOptions, agentOptions?: AgentOptions): Promise<Agent>;
 type CliAgent = string | {
     url?: string;
     name?: string;
@@ -230,4 +238,6 @@ export declare function loadAIGNEFile(path: string): Promise<{
     aigne: z.infer<typeof aigneFileSchema>;
     rootDir: string;
 }>;
+export declare function findAIGNEFile(path: string): Promise<string>;
+export declare function instructionsToPromptBuilder(instructions: Instructions): PromptBuilder;
 export {};

package/lib/cjs/loader/index.js

@@ -2,7 +2,11 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.load = load;
 exports.loadAgent = loadAgent;
+exports.loadNestAgent = loadNestAgent;
+exports.parseAgent = parseAgent;
 exports.loadAIGNEFile = loadAIGNEFile;
+exports.findAIGNEFile = findAIGNEFile;
+exports.instructionsToPromptBuilder = instructionsToPromptBuilder;
 const afs_1 = require("@aigne/afs");
 const index_js_1 = require("@aigne/platform-helpers/nodejs/index.js");
 const yaml_1 = require("yaml");
@@ -15,6 +19,7 @@ const team_agent_js_1 = require("../agents/team-agent.js");
 const transform_agent_js_1 = require("../agents/transform-agent.js");
 const prompt_builder_js_1 = require("../prompt/prompt-builder.js");
 const template_js_1 = require("../prompt/template.js");
+const agent_utils_js_1 = require("../utils/agent-utils.js");
 const type_utils_js_1 = require("../utils/type-utils.js");
 const agent_js_js_1 = require("./agent-js.js");
 const agent_yaml_js_1 = require("./agent-yaml.js");
@@ -71,17 +76,18 @@ async function loadAgent(path, options, agentOptions) {
         return parseAgent(path, agent, options, agentOptions);
     }
     if ([".yml", ".yaml"].includes(index_js_1.nodejs.path.extname(path))) {
-        const agent = await (0, agent_yaml_js_1.loadAgentFromYamlFile)(path);
+        const agent = await (0, agent_yaml_js_1.loadAgentFromYamlFile)(path, options);
         return parseAgent(path, agent, options, agentOptions);
     }
     throw new Error(`Unsupported agent file type: ${path}`);
 }
-async function loadNestAgent(path, agent, options) {
+async function loadNestAgent(path, agent, options, agentOptions) {
     return typeof agent === "object" && "type" in agent
-        ? parseAgent(path, agent, options)
+        ? parseAgent(path, agent, options, agentOptions)
         : typeof agent === "string"
-            ? loadAgent(index_js_1.nodejs.path.join(index_js_1.nodejs.path.dirname(path), agent), options)
+            ? loadAgent(index_js_1.nodejs.path.join(index_js_1.nodejs.path.dirname(path), agent), options, agentOptions)
             : loadAgent(index_js_1.nodejs.path.join(index_js_1.nodejs.path.dirname(path), agent.url), options, {
+                ...agentOptions,
                 defaultInput: agent.defaultInput,
                 hooks: await parseHooks(path, agent.hooks, options),
             });
@@ -113,14 +119,17 @@ async function loadSkills(path, skills, options) {
     return loadedSkills;
 }
 async function parseAgent(path, agent, options, agentOptions) {
-    const skills = "skills" in agent && agent.skills ? await loadSkills(path, agent.skills, options) : undefined;
+    if ((0, agent_utils_js_1.isAgent)(agent))
+        return agent;
     const memory = "memory" in agent && options?.memories?.length
         ? await loadMemory(options.memories, typeof agent.memory === "object" ? agent.memory.provider : undefined, typeof agent.memory === "object" ? agent.memory : {})
         : undefined;
     let afs;
-    if (typeof agent.afs === "boolean") {
-        if (agent.afs)
-            afs = new afs_1.AFS();
+    if (agent.afs !== false && (!agent.afs || agent.afs === true) && options?.afs?.sharedAFS) {
+        afs = options.afs.sharedAFS;
+    }
+    else if (agent.afs === true) {
+        afs = new afs_1.AFS();
     }
     else if (agent.afs) {
         afs = new afs_1.AFS();
@@ -133,6 +142,12 @@ async function parseAgent(path, agent, options, agentOptions) {
             afs.mount(module);
         }
     }
+    const skills = "skills" in agent && agent.skills
+        ? await loadSkills(path, agent.skills, {
+            ...options,
+            afs: { ...options?.afs, sharedAFS: (agent.shareAFS && afs) || options?.afs?.sharedAFS },
+        })
+        : [];
     const model = agent.model && typeof options?.model === "function"
         ? await options.model({ ...options.aigne?.model, ...(0, type_utils_js_1.omitBy)(agent.model, (v) => (0, type_utils_js_1.isNil)(v)) })
         : undefined;
@@ -147,22 +162,17 @@ async function parseAgent(path, agent, options, agentOptions) {
         ...agent,
         model,
         imageModel,
-        skills,
         memory,
         hooks: [
             ...((await parseHooks(path, agent.hooks, options)) ?? []),
             ...[agentOptions?.hooks].flat().filter(type_utils_js_1.isNonNullable),
         ],
-        afs,
+        skills: [...(agentOptions?.skills || []), ...skills],
+        afs: afs || agentOptions?.afs,
     };
     let instructions;
-    if ("instructions" in agent && agent.instructions) {
-        instructions = new prompt_builder_js_1.PromptBuilder({
-            instructions: template_js_1.ChatMessagesTemplate.from((0, template_js_1.parseChatMessages)(agent.instructions.map((i) => ({
-                ...i,
-                options: { workingDir: index_js_1.nodejs.path.dirname(i.path) },
-            })))),
-        });
+    if ("instructions" in agent && agent.instructions && ["ai", "image"].includes(agent.type)) {
+        instructions = instructionsToPromptBuilder(agent.instructions);
     }
     switch (agent.type) {
         case "ai": {
@@ -219,6 +229,14 @@ async function parseAgent(path, agent, options, agentOptions) {
             });
         }
     }
+    if ("agentClass" in agent && agent.agentClass) {
+        return await agent.agentClass.load({
+            filepath: path,
+            parsed: baseOptions,
+            options,
+        });
+    }
+    throw new Error(`Unsupported agent type: ${"type" in agent ? agent.type : "unknown"} at path: ${path}`);
 }
 async function loadMemory(memories, provider, options) {
     const M = !provider
@@ -274,3 +292,11 @@ async function findAIGNEFile(path) {
     }
     throw new Error(`aigne.yaml not found in ${path}. Please ensure you are in the correct directory or provide a valid path.`);
 }
+function instructionsToPromptBuilder(instructions) {
+    return new prompt_builder_js_1.PromptBuilder({
+        instructions: template_js_1.ChatMessagesTemplate.from((0, template_js_1.parseChatMessages)(instructions.map((i) => ({
+            ...i,
+            options: { workingDir: index_js_1.nodejs.path.dirname(i.path) },
+        })))),
+    });
+}

package/lib/cjs/prompt/prompt-builder.d.ts

@@ -2,7 +2,6 @@ import type { GetPromptResult } from "@modelcontextprotocol/sdk/types.js";
 import { Agent, type AgentInvokeOptions, type Message } from "../agents/agent.js";
 import { type AIAgent } from "../agents/ai-agent.js";
 import type { ChatModel, ChatModelInput } from "../agents/chat-model.js";
-import type { ImageAgent } from "../agents/image-agent.js";
 import { type FileUnionContent } from "../agents/model.js";
 import { ChatMessagesTemplate } from "./template.js";
 export interface PromptBuilderOptions {
@@ -26,11 +25,12 @@ export declare class PromptBuilder {
     constructor(options?: PromptBuilderOptions);
     instructions?: string | ChatMessagesTemplate;
     workingDir?: string;
+    copy(): PromptBuilder;
     build(options: PromptBuildOptions): Promise<ChatModelInput & {
         toolAgents?: Agent[];
     }>;
-    buildImagePrompt(options: Pick<PromptBuildOptions, "input" | "context"> & {
-        agent: ImageAgent;
+    buildPrompt(options: Pick<PromptBuildOptions, "input" | "context"> & {
+        inputFileKey?: string;
     }): Promise<{
         prompt: string;
         image?: FileUnionContent[];