@aigne/core 1.34.0 → 1.37.0

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

@@ -1,39 +1,60 @@
 import { type ZodType } from "zod";
+import type { FunctionAgentFn } from "../agents/agent.js";
 import { AIAgentToolChoice } from "../agents/ai-agent.js";
 import { ProcessMode } from "../agents/team-agent.js";
-interface BaseAgentSchema {
+export interface HooksSchema {
+    onStart?: NestAgentSchema;
+    onSuccess?: NestAgentSchema;
+    onError?: NestAgentSchema;
+    onEnd?: NestAgentSchema;
+    onSkillStart?: NestAgentSchema;
+    onSkillEnd?: NestAgentSchema;
+    onHandoff?: NestAgentSchema;
+}
+export type NestAgentSchema = string | {
+    url: string;
+    defaultInput?: Record<string, any>;
+    hooks?: HooksSchema | HooksSchema[];
+} | AgentSchema;
+export interface BaseAgentSchema {
     name?: string;
     description?: string;
     inputSchema?: ZodType<Record<string, any>>;
+    defaultInput?: Record<string, any>;
     outputSchema?: ZodType<Record<string, any>>;
-    skills?: (string | AgentSchema)[];
+    skills?: NestAgentSchema[];
+    hooks?: HooksSchema | HooksSchema[];
     memory?: boolean | {
         provider: string;
         subscribeTopic?: string[];
     };
 }
-interface AIAgentSchema extends BaseAgentSchema {
+export interface AIAgentSchema extends BaseAgentSchema {
     type: "ai";
     instructions?: string;
     inputKey?: string;
     outputKey?: string;
     toolChoice?: AIAgentToolChoice;
 }
-interface MCPAgentSchema {
+export interface MCPAgentSchema extends BaseAgentSchema {
     type: "mcp";
     url?: string;
     command?: string;
     args?: string[];
 }
-interface TeamAgentSchema extends BaseAgentSchema {
+export interface TeamAgentSchema extends BaseAgentSchema {
     type: "team";
     mode?: ProcessMode;
     iterateOn?: string;
 }
-interface TransformAgentSchema extends BaseAgentSchema {
+export interface TransformAgentSchema extends BaseAgentSchema {
     type: "transform";
     jsonata: string;
 }
-type AgentSchema = AIAgentSchema | MCPAgentSchema | TeamAgentSchema | TransformAgentSchema;
+export interface FunctionAgentSchema extends BaseAgentSchema {
+    type: "function";
+    process: FunctionAgentFn;
+}
+export type AgentSchema = AIAgentSchema | MCPAgentSchema | TeamAgentSchema | TransformAgentSchema | FunctionAgentSchema;
+export declare function parseAgentFile(path: string, data: object): Promise<AgentSchema>;
 export declare function loadAgentFromYamlFile(path: string): Promise<AgentSchema>;
-export {};

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

@@ -1,29 +1,48 @@
 import { jsonSchemaToZod } from "@aigne/json-schema-to-zod";
 import { nodejs } from "@aigne/platform-helpers/nodejs/index.js";
-import camelize from "camelize-ts";
 import { parse } from "yaml";
 import { z } from "zod";
 import { AIAgentToolChoice } from "../agents/ai-agent.js";
 import { ProcessMode } from "../agents/team-agent.js";
 import { tryOrThrow } from "../utils/type-utils.js";
-import { inputOutputSchema, optionalize } from "./schema.js";
-export async function loadAgentFromYamlFile(path) {
+import { camelizeSchema, defaultInputSchema, inputOutputSchema, optionalize } from "./schema.js";
+export async function parseAgentFile(path, data) {
     const agentSchema = z.lazy(() => {
+        const nestAgentSchema = z.lazy(() => z.union([
+            agentSchema,
+            z.string(),
+            camelizeSchema(z.object({
+                url: z.string(),
+                defaultInput: optionalize(defaultInputSchema),
+                hooks: optionalize(z.union([hooksSchema, z.array(hooksSchema)])),
+            })),
+        ]));
+        const hooksSchema = camelizeSchema(z.object({
+            onStart: optionalize(nestAgentSchema),
+            onSuccess: optionalize(nestAgentSchema),
+            onError: optionalize(nestAgentSchema),
+            onEnd: optionalize(nestAgentSchema),
+            onSkillStart: optionalize(nestAgentSchema),
+            onSkillEnd: optionalize(nestAgentSchema),
+            onHandoff: optionalize(nestAgentSchema),
+        }));
         const baseAgentSchema = z.object({
             name: optionalize(z.string()),
             description: optionalize(z.string()),
             inputSchema: optionalize(inputOutputSchema({ path })).transform((v) => v ? jsonSchemaToZod(v) : undefined),
+            defaultInput: optionalize(defaultInputSchema),
             outputSchema: optionalize(inputOutputSchema({ path })).transform((v) => v ? jsonSchemaToZod(v) : undefined),
-            skills: optionalize(z.array(z.union([z.string(), agentSchema]))),
+            hooks: optionalize(z.union([hooksSchema, z.array(hooksSchema)])),
+            skills: optionalize(z.array(nestAgentSchema)),
             memory: optionalize(z.union([
                 z.boolean(),
-                z.object({
+                camelizeSchema(z.object({
                     provider: z.string(),
                     subscribeTopic: optionalize(z.array(z.string())),
-                }),
+                })),
             ])),
         });
-        return z.discriminatedUnion("type", [
+        return camelizeSchema(z.discriminatedUnion("type", [
             z
                 .object({
                 type: z.literal("ai"),
@@ -34,18 +53,21 @@ export async function loadAgentFromYamlFile(path) {
                     }),
                 ])).transform((v) => typeof v === "string"
                     ? v
-                    : v && nodejs.fs.readFile(nodejs.path.join(nodejs.path.dirname(path), v.url), "utf8")),
+                    : v &&
+                        nodejs.fs.readFile(nodejs.path.join(nodejs.path.dirname(path), v.url), "utf8")),
                 inputKey: optionalize(z.string()),
                 outputKey: optionalize(z.string()),
                 toolChoice: optionalize(z.nativeEnum(AIAgentToolChoice)),
             })
                 .extend(baseAgentSchema.shape),
-            z.object({
+            z
+                .object({
                 type: z.literal("mcp"),
                 url: optionalize(z.string()),
                 command: optionalize(z.string()),
                 args: optionalize(z.array(z.string())),
-            }),
+            })
+                .extend(baseAgentSchema.shape),
             z
                 .object({
                 type: z.literal("team"),
@@ -59,11 +81,20 @@ export async function loadAgentFromYamlFile(path) {
                 jsonata: z.string(),
             })
                 .extend(baseAgentSchema.shape),
-        ]);
+            z
+                .object({
+                type: z.literal("function"),
+                process: z.custom(),
+            })
+                .extend(baseAgentSchema.shape),
+        ]));
     });
+    return agentSchema.parseAsync(data);
+}
+export async function loadAgentFromYamlFile(path) {
     const raw = await tryOrThrow(() => nodejs.fs.readFile(path, "utf8"), (error) => new Error(`Failed to load agent definition from ${path}: ${error.message}`));
-    const json = tryOrThrow(() => camelize(parse(raw)), (error) => new Error(`Failed to parse agent definition from ${path}: ${error.message}`));
-    const agent = await tryOrThrow(async () => await agentSchema.parseAsync({
+    const json = tryOrThrow(() => parse(raw), (error) => new Error(`Failed to parse agent definition from ${path}: ${error.message}`));
+    const agent = await tryOrThrow(async () => await parseAgentFile(path, {
         ...json,
         type: json.type ?? "ai",
         skills: json.skills ?? json.tools,

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

@@ -1,6 +1,6 @@
 import type { Camelize } from "camelize-ts";
 import { z } from "zod";
-import { Agent } from "../agents/agent.js";
+import { Agent, type AgentOptions } from "../agents/agent.js";
 import type { ChatModel, ChatModelOptions } from "../agents/chat-model.js";
 import type { AIGNEOptions } from "../aigne/aigne.js";
 import type { MemoryAgent, MemoryAgentOptions } from "../memory/memory.js";
@@ -25,7 +25,7 @@ export interface LoadOptions {
     path: string;
 }
 export declare function load(options: LoadOptions): Promise<AIGNEOptions>;
-export declare function loadAgent(path: string, options?: LoadOptions): Promise<Agent>;
+export declare function loadAgent(path: string, options?: LoadOptions, agentOptions?: AgentOptions): Promise<Agent>;
 export declare function loadModel(models: LoadableModel[], model?: Camelize<z.infer<typeof aigneFileSchema>["model"]>, modelOptions?: ChatModelOptions): Promise<ChatModel | undefined>;
 declare const aigneFileSchema: z.ZodObject<{
     name: z.ZodType<string | undefined, z.ZodTypeDef, string | undefined>;

package/lib/esm/loader/index.js

@@ -8,7 +8,7 @@ import { MCPAgent } from "../agents/mcp-agent.js";
 import { TeamAgent } from "../agents/team-agent.js";
 import { TransformAgent } from "../agents/transform-agent.js";
 import { PromptBuilder } from "../prompt/prompt-builder.js";
-import { tryOrThrow } from "../utils/type-utils.js";
+import { isNonNullable, tryOrThrow } from "../utils/type-utils.js";
 import { loadAgentFromJsFile } from "./agent-js.js";
 import { loadAgentFromYamlFile } from "./agent-yaml.js";
 import { optionalize } from "./schema.js";
@@ -30,47 +30,83 @@ export async function load(options) {
         skills,
     };
 }
-export async function loadAgent(path, options) {
+export async function loadAgent(path, options, agentOptions) {
     if ([".js", ".mjs", ".ts", ".mts"].includes(nodejs.path.extname(path))) {
         const agent = await loadAgentFromJsFile(path);
         if (agent instanceof Agent)
             return agent;
-        return FunctionAgent.from(agent);
+        return parseAgent(path, agent, options, agentOptions);
     }
     if ([".yml", ".yaml"].includes(nodejs.path.extname(path))) {
         const agent = await loadAgentFromYamlFile(path);
-        return parseAgent(path, agent, options);
+        return parseAgent(path, agent, options, agentOptions);
     }
     throw new Error(`Unsupported agent file type: ${path}`);
 }
-async function parseAgent(path, agent, options) {
+async function loadNestAgent(path, agent, options) {
+    return typeof agent === "object" && "type" in agent
+        ? parseAgent(path, agent, options)
+        : typeof agent === "string"
+            ? loadAgent(nodejs.path.join(nodejs.path.dirname(path), agent), options)
+            : loadAgent(nodejs.path.join(nodejs.path.dirname(path), agent.url), options, {
+                defaultInput: agent.defaultInput,
+                hooks: await parseHooks(path, agent.hooks, options),
+            });
+}
+async function parseHooks(path, hooks, options) {
+    hooks = [hooks].flat().filter(isNonNullable);
+    if (!hooks.length)
+        return undefined;
+    return await Promise.all(hooks.map(async (hook) => ({
+        onStart: hook.onStart ? await loadNestAgent(path, hook.onStart, options) : undefined,
+        onSuccess: hook.onSuccess ? await loadNestAgent(path, hook.onSuccess, options) : undefined,
+        onError: hook.onError ? await loadNestAgent(path, hook.onError, options) : undefined,
+        onEnd: hook.onEnd ? await loadNestAgent(path, hook.onEnd, options) : undefined,
+        onSkillStart: hook.onSkillStart
+            ? await loadNestAgent(path, hook.onSkillStart, options)
+            : undefined,
+        onSkillEnd: hook.onSkillEnd
+            ? await loadNestAgent(path, hook.onSkillEnd, options)
+            : undefined,
+        onHandoff: hook.onHandoff ? await loadNestAgent(path, hook.onHandoff, options) : undefined,
+    })));
+}
+async function parseAgent(path, agent, options, agentOptions) {
     const skills = "skills" in agent
         ? agent.skills &&
-            (await Promise.all(agent.skills.map((skill) => typeof skill === "string"
-                ? loadAgent(nodejs.path.join(nodejs.path.dirname(path), skill), options)
-                : parseAgent(path, skill, options))))
+            (await Promise.all(agent.skills.map((skill) => loadNestAgent(path, skill, options))))
         : undefined;
     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;
+    const baseOptions = {
+        ...agentOptions,
+        ...agent,
+        skills,
+        memory,
+        hooks: [
+            ...((await parseHooks(path, agent.hooks, options)) ?? []),
+            ...[agentOptions?.hooks].flat().filter(isNonNullable),
+        ],
+    };
     switch (agent.type) {
         case "ai": {
             return AIAgent.from({
-                ...agent,
+                ...baseOptions,
                 instructions: agent.instructions &&
                     PromptBuilder.from(agent.instructions, { workingDir: nodejs.path.dirname(path) }),
-                memory,
-                skills,
             });
         }
         case "mcp": {
             if (agent.url) {
                 return MCPAgent.from({
+                    ...baseOptions,
                     url: agent.url,
                 });
             }
             if (agent.command) {
                 return MCPAgent.from({
+                    ...baseOptions,
                     command: agent.command,
                     args: agent.args,
                 });
@@ -79,16 +115,19 @@ async function parseAgent(path, agent, options) {
         }
         case "team": {
             return TeamAgent.from({
-                ...agent,
-                memory,
-                skills,
+                ...baseOptions,
             });
         }
         case "transform": {
             return TransformAgent.from({
-                ...agent,
-                memory,
-                skills,
+                ...baseOptions,
+                jsonata: agent.jsonata,
+            });
+        }
+        case "function": {
+            return FunctionAgent.from({
+                ...baseOptions,
+                process: agent.process,
             });
         }
     }

package/lib/esm/loader/schema.d.ts

@@ -22,4 +22,14 @@ export declare const inputOutputSchema: ({ path }: {
     required?: string[] | undefined;
     additionalProperties?: boolean | undefined;
 }>]>;
+export declare const defaultInputSchema: z.ZodRecord<z.ZodString, z.ZodUnion<[z.ZodObject<{
+    $get: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    $get: string;
+}, {
+    $get: string;
+}>, z.ZodUnknown]>>;
 export declare function optionalize<T>(schema: ZodType<T>): ZodType<T | undefined>;
+export declare function camelizeSchema<T>(schema: ZodType<T>, { shallow }?: {
+    shallow?: boolean;
+}): ZodType<T>;

package/lib/esm/loader/schema.js

@@ -1,6 +1,9 @@
 import { nodejs } from "@aigne/platform-helpers/nodejs/index.js";
+import camelize from "camelize-ts";
 import { parse } from "yaml";
 import { z } from "zod";
+import { DEFAULT_INPUT_ACTION_GET } from "../agents/agent.js";
+import { isRecord } from "../utils/type-utils.js";
 export const inputOutputSchema = ({ path }) => {
     const includeExternalSchema = async (schema) => {
         if (schema?.type === "object" && schema.properties) {
@@ -45,6 +48,15 @@ export const inputOutputSchema = ({ path }) => {
         jsonSchemaSchema,
     ]);
 };
+export const defaultInputSchema = z.record(z.string(), z.union([
+    z.object({
+        [DEFAULT_INPUT_ACTION_GET]: z.string(),
+    }),
+    z.unknown(),
+]));
 export function optionalize(schema) {
     return schema.nullish().transform((v) => v ?? undefined);
 }
+export function camelizeSchema(schema, { shallow = true } = {}) {
+    return z.preprocess((v) => (isRecord(v) ? camelize(v, shallow) : v), schema);
+}

package/lib/esm/utils/type-utils.d.ts

@@ -19,7 +19,7 @@ export declare function pick<T extends object, K extends keyof T>(obj: T, ...key
 export declare function omit<T extends object, K extends keyof T>(obj: T, ...keys: (K | K[])[]): Omit<T, K>;
 export declare function omitDeep<T, K>(obj: T, ...keys: (K | K[])[]): unknown;
 export declare function omitBy<T extends Record<string, unknown>, K extends keyof T>(obj: T, predicate: (value: T[K], key: K) => boolean): Partial<T>;
-export declare function flat<T>(value?: T | T[]): T[];
+export declare function flat<T>(...value: (T | T[])[]): NonNullable<T>[];
 export declare function createAccessorArray<T>(array: T[], accessor: (array: T[], name: string) => T | undefined): T[] & {
     [key: string]: T;
 };

package/lib/esm/utils/type-utils.js

@@ -84,10 +84,8 @@ export function omitBy(obj, predicate) {
         return !predicate(value, k);
     }));
 }
-export function flat(value) {
-    if (isNil(value))
-        return [];
-    return Array.isArray(value) ? value : [value];
+export function flat(...value) {
+    return value.flat().filter(isNonNullable);
 }
 export function createAccessorArray(array, accessor) {
     return new Proxy(array, {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aigne/core",
-  "version": "1.34.0",
+  "version": "1.37.0",
   "description": "AIGNE core library for building AI-powered applications",
   "publishConfig": {
     "access": "public"
@@ -83,8 +83,8 @@
     "yaml": "^2.8.0",
     "zod": "^3.25.67",
     "zod-to-json-schema": "^3.24.6",
-    "@aigne/platform-helpers": "^0.4.0",
-    "@aigne/observability-api": "^0.8.0"
+    "@aigne/observability-api": "^0.8.0",
+    "@aigne/platform-helpers": "^0.4.0"
   },
   "devDependencies": {
     "@types/bun": "^1.2.18",