@aigne/core 1.61.0 → 1.62.0-beta

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## [1.62.0-beta](https://github.com/AIGNE-io/aigne-framework/compare/core-v1.61.1-beta...core-v1.62.0-beta) (2025-09-30)
+
+
+### Features
+
+* **cli:** support define nested commands for sub apps ([#568](https://github.com/AIGNE-io/aigne-framework/issues/568)) ([0693b80](https://github.com/AIGNE-io/aigne-framework/commit/0693b807e0f8d335010e6ad00763b07cf095e65b))
+
+## [1.61.1-beta](https://github.com/AIGNE-io/aigne-framework/compare/core-v1.61.0...core-v1.61.1-beta) (2025-09-29)
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @aigne/observability-api bumped to 0.11.1-beta
+
 ## [1.61.0](https://github.com/AIGNE-io/aigne-framework/compare/core-v1.61.0-beta.8...core-v1.61.0) (2025-09-27)
 
 

package/lib/cjs/aigne/aigne.d.ts

@@ -6,6 +6,7 @@ import type { UserAgent } from "../agents/user-agent.js";
 import { type LoadOptions } from "../loader/index.js";
 import { AIGNEContext, type Context, type InvokeOptions, type UserContext } from "./context.js";
 import { type MessagePayload, MessageQueue, type MessageQueueListener, type Unsubscribe } from "./message-queue.js";
+import type { AIGNECLIAgents } from "./type.js";
 import type { ContextLimits } from "./usage.js";
 /**
  * Options for the AIGNE class.
@@ -43,10 +44,7 @@ export interface AIGNEOptions {
     mcpServer?: {
         agents?: Agent[];
     };
-    cli?: {
-        chat?: Agent;
-        agents?: Agent[];
-    };
+    cli?: AIGNECLIAgents;
     /**
      * Limits for the AIGNE instance, such as timeout, max tokens, max invocations, etc.
      */
@@ -133,12 +131,7 @@ export declare class AIGNE<U extends UserContext = UserContext> {
             [key: string]: Agent<any, any>;
         };
     };
-    readonly cli: {
-        chat: Agent | undefined;
-        agents: Agent<any, any>[] & {
-            [key: string]: Agent<any, any>;
-        };
-    };
+    readonly cli: AIGNECLIAgents;
     /**
      * Observer for the AIGNE instance.
      */

package/lib/cjs/aigne/aigne.js

@@ -63,10 +63,7 @@ class AIGNE {
             this.addAgent(...options.agents);
         if (options?.mcpServer?.agents?.length)
             this.mcpServer.agents.push(...options.mcpServer.agents);
-        if (options?.cli?.agents?.length)
-            this.cli.agents.push(...options.cli.agents);
-        if (options?.cli?.chat)
-            this.cli.chat = options.cli.chat;
+        this.cli = options?.cli ?? {};
         this.observer?.serve();
         this.initProcessExitHandler();
     }
@@ -113,10 +110,7 @@ class AIGNE {
     mcpServer = {
         agents: (0, type_utils_js_1.createAccessorArray)([], (arr, name) => arr.find((i) => i.name === name)),
     };
-    cli = {
-        chat: undefined,
-        agents: (0, type_utils_js_1.createAccessorArray)([], (arr, name) => arr.find((i) => i.name === name)),
-    };
+    cli = {};
     /**
      * Observer for the AIGNE instance.
      */

package/lib/cjs/aigne/type.d.ts

@@ -0,0 +1,12 @@
+import type { Agent } from "../agents/agent.ts";
+export interface AIGNECLIAgents {
+    chat?: Agent;
+    agents?: AIGNECLIAgent[];
+}
+export interface AIGNECLIAgent {
+    agent?: Agent;
+    name?: string;
+    alias?: string[];
+    description?: string;
+    agents?: AIGNECLIAgent[];
+}

package/lib/cjs/aigne/type.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

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

@@ -1,4 +1,4 @@
-import { z } from "zod";
+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";
@@ -14,10 +14,17 @@ export interface LoadOptions {
 }
 export declare function load(path: string, options?: LoadOptions): Promise<AIGNEOptions>;
 export declare function loadAgent(path: string, options?: LoadOptions, agentOptions?: AgentOptions): Promise<Agent>;
+type CliAgent = string | {
+    url?: string;
+    name?: string;
+    alias?: string[];
+    description?: string;
+    agents?: CliAgent[];
+};
 declare const aigneFileSchema: z.ZodObject<{
-    name: z.ZodType<string | undefined, z.ZodTypeDef, string | undefined>;
-    description: z.ZodType<string | undefined, z.ZodTypeDef, string | undefined>;
-    model: z.ZodType<{
+    name: ZodType<string | undefined, z.ZodTypeDef, string | undefined>;
+    description: ZodType<string | undefined, z.ZodTypeDef, string | undefined>;
+    model: ZodType<{
         model?: string | undefined;
         temperature?: number | undefined;
         topP?: number | undefined;
@@ -30,23 +37,23 @@ declare const aigneFileSchema: z.ZodObject<{
         frequencyPenalty?: number | undefined;
         presencePenalty?: number | undefined;
     } | undefined>;
-    imageModel: z.ZodType<{
+    imageModel: ZodType<{
         model?: string | undefined;
     } | undefined, z.ZodTypeDef, {
         model?: string | undefined;
     } | undefined>;
-    agents: z.ZodType<string[] | undefined, z.ZodTypeDef, string[] | undefined>;
-    skills: z.ZodType<string[] | undefined, z.ZodTypeDef, string[] | undefined>;
-    mcpServer: z.ZodType<{
+    agents: ZodType<string[] | undefined, z.ZodTypeDef, string[] | undefined>;
+    skills: ZodType<string[] | undefined, z.ZodTypeDef, string[] | undefined>;
+    mcpServer: ZodType<{
         agents?: string[] | undefined;
     } | undefined, z.ZodTypeDef, {
         agents?: string[] | undefined;
     } | undefined>;
-    cli: z.ZodType<{
-        agents?: string[] | undefined;
+    cli: ZodType<{
+        agents?: CliAgent[] | undefined;
         chat?: string | undefined;
     } | undefined, z.ZodTypeDef, {
-        agents?: string[] | undefined;
+        agents?: CliAgent[] | undefined;
         chat?: string | undefined;
     } | undefined>;
 }, "strip", z.ZodTypeAny, {
@@ -68,7 +75,7 @@ declare const aigneFileSchema: z.ZodObject<{
         agents?: string[] | undefined;
     } | undefined;
     cli?: {
-        agents?: string[] | undefined;
+        agents?: CliAgent[] | undefined;
         chat?: string | undefined;
     } | undefined;
 }, {
@@ -90,7 +97,7 @@ declare const aigneFileSchema: z.ZodObject<{
         agents?: string[] | undefined;
     } | undefined;
     cli?: {
-        agents?: string[] | undefined;
+        agents?: CliAgent[] | undefined;
         chat?: string | undefined;
     } | undefined;
 }>;

package/lib/cjs/loader/index.js

@@ -21,12 +21,27 @@ const schema_js_1 = require("./schema.js");
 const AIGNE_FILE_NAME = ["aigne.yaml", "aigne.yml"];
 async function load(path, options = {}) {
     const { aigne, rootDir } = await loadAIGNEFile(path);
-    const allAgentPaths = new Set((0, type_utils_js_1.flat)(aigne.agents, aigne.skills, aigne.mcpServer?.agents, aigne.cli?.agents, aigne.cli?.chat).map((i) => index_js_1.nodejs.path.join(rootDir, i)));
+    const flatCliAgents = (cliAgent) => {
+        if (typeof cliAgent === "string")
+            return [cliAgent];
+        return (0, type_utils_js_1.flat)(cliAgent.url, cliAgent.agents?.flatMap(flatCliAgents));
+    };
+    const allAgentPaths = new Set((0, type_utils_js_1.flat)(aigne.agents, aigne.skills, aigne.mcpServer?.agents, aigne.cli?.chat, aigne.cli?.agents?.flatMap((i) => (typeof i === "string" ? i : flatCliAgents(i)))).map((i) => index_js_1.nodejs.path.join(rootDir, i)));
     const allAgents = {};
     for (const path of allAgentPaths) {
         allAgents[path] = await loadAgent(path, options);
     }
-    const pickAgents = (paths) => paths.map((filename) => allAgents[index_js_1.nodejs.path.join(rootDir, filename)]).filter(type_utils_js_1.isNonNullable);
+    const pickAgent = (path) => allAgents[index_js_1.nodejs.path.join(rootDir, path)];
+    const pickAgents = (paths) => paths.map((filename) => pickAgent(filename)).filter(type_utils_js_1.isNonNullable);
+    const mapCliAgents = (cliAgent) => {
+        if (typeof cliAgent === "string")
+            return { agent: pickAgent(cliAgent) };
+        return {
+            ...cliAgent,
+            agent: cliAgent.url ? pickAgent(cliAgent.url) : undefined,
+            agents: cliAgent.agents?.map(mapCliAgents),
+        };
+    };
     return {
         ...aigne,
         rootDir,
@@ -41,7 +56,7 @@ async function load(path, options = {}) {
         },
         cli: {
             chat: aigne.cli?.chat ? pickAgents([aigne.cli.chat])[0] : undefined,
-            agents: pickAgents(aigne.cli?.agents ?? []),
+            agents: aigne.cli?.agents?.map(mapCliAgents),
         },
     };
 }
@@ -186,6 +201,16 @@ async function loadMemory(memories, provider, options) {
         throw new Error(`Unsupported memory: ${provider}`);
     return new M(options);
 }
+const cliAgentSchema = zod_1.z.union([
+    zod_1.z.string(),
+    zod_1.z.object({
+        url: (0, schema_js_1.optionalize)(zod_1.z.string()),
+        name: (0, schema_js_1.optionalize)(zod_1.z.string()),
+        alias: (0, schema_js_1.optionalize)(zod_1.z.array(zod_1.z.string())),
+        description: (0, schema_js_1.optionalize)(zod_1.z.string()),
+        agents: (0, schema_js_1.optionalize)(zod_1.z.array(zod_1.z.lazy(() => cliAgentSchema))),
+    }),
+]);
 const aigneFileSchema = (0, schema_js_1.camelizeSchema)(zod_1.z.object({
     name: (0, schema_js_1.optionalize)(zod_1.z.string()),
     description: (0, schema_js_1.optionalize)(zod_1.z.string()),
@@ -198,7 +223,7 @@ const aigneFileSchema = (0, schema_js_1.camelizeSchema)(zod_1.z.object({
     })),
     cli: (0, schema_js_1.optionalize)(zod_1.z.object({
         chat: (0, schema_js_1.optionalize)(zod_1.z.string()),
-        agents: (0, schema_js_1.optionalize)(zod_1.z.array(zod_1.z.string())),
+        agents: (0, schema_js_1.optionalize)(zod_1.z.array(cliAgentSchema)),
     })),
 }));
 async function loadAIGNEFile(path) {

package/lib/cjs/utils/agent-utils.d.ts

@@ -1,2 +1,12 @@
 import type { AgentHooks } from "../agents/agent.ts";
+import type { AIGNECLIAgents } from "../aigne/type.js";
 export declare function sortHooks(hooks: AgentHooks[]): AgentHooks[];
+export interface CLIAgent<T> {
+    agent?: T;
+    name?: string;
+    alias?: string[];
+    description?: string;
+    agents?: CLIAgent<T>[];
+}
+export declare function mapCliAgent<A, O>({ agent, agents, ...input }: CLIAgent<A>, transform: (input: A) => O): CLIAgent<O>;
+export declare function findCliAgent(cli: AIGNECLIAgents, parent: string[] | "*", name: string): import("../agents/agent.ts").Agent<any, any> | undefined;

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

@@ -1,9 +1,53 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.sortHooks = sortHooks;
+exports.mapCliAgent = mapCliAgent;
+exports.findCliAgent = findCliAgent;
 const priorities = ["high", "medium", "low"];
 function sortHooks(hooks) {
     return hooks
         .slice(0)
         .sort(({ priority: a = "low" }, { priority: b = "low" }) => a === b ? 0 : priorities.indexOf(a) - priorities.indexOf(b));
 }
+function mapCliAgent({ agent, agents, ...input }, transform) {
+    return {
+        ...input,
+        agent: agent ? transform(agent) : undefined,
+        agents: agents?.map((item) => mapCliAgent(item, transform)),
+    };
+}
+function findCliAgent(cli, parent, name) {
+    if (parent === "*")
+        return findCliAgentRecursive(cli, name);
+    let currentAgents = cli.agents ?? [];
+    for (const name of parent) {
+        const found = currentAgents.find((i) => (i.name || i.agent?.name) === name);
+        if (!found)
+            throw new Error(`Agent ${name} not found in parent path ${parent.join(" -> ")}`);
+        if (found.agents)
+            currentAgents = found.agents;
+        else
+            currentAgents = [];
+    }
+    return currentAgents.find((i) => (i.name || i.agent?.name) === name)?.agent;
+}
+function findCliAgentRecursive(agents, name) {
+    if (agents.chat?.name === name) {
+        return agents.chat;
+    }
+    if (agents.agents) {
+        const queue = [...agents.agents];
+        while (queue.length > 0) {
+            const c = queue.shift();
+            if (!c)
+                break;
+            if ((c.name || c.agent?.name) === name) {
+                return c.agent;
+            }
+            if (c.agents) {
+                queue.push(...c.agents);
+            }
+        }
+    }
+    return undefined;
+}

package/lib/dts/aigne/aigne.d.ts

@@ -6,6 +6,7 @@ import type { UserAgent } from "../agents/user-agent.js";
 import { type LoadOptions } from "../loader/index.js";
 import { AIGNEContext, type Context, type InvokeOptions, type UserContext } from "./context.js";
 import { type MessagePayload, MessageQueue, type MessageQueueListener, type Unsubscribe } from "./message-queue.js";
+import type { AIGNECLIAgents } from "./type.js";
 import type { ContextLimits } from "./usage.js";
 /**
  * Options for the AIGNE class.
@@ -43,10 +44,7 @@ export interface AIGNEOptions {
     mcpServer?: {
         agents?: Agent[];
     };
-    cli?: {
-        chat?: Agent;
-        agents?: Agent[];
-    };
+    cli?: AIGNECLIAgents;
     /**
      * Limits for the AIGNE instance, such as timeout, max tokens, max invocations, etc.
      */
@@ -133,12 +131,7 @@ export declare class AIGNE<U extends UserContext = UserContext> {
             [key: string]: Agent<any, any>;
         };
     };
-    readonly cli: {
-        chat: Agent | undefined;
-        agents: Agent<any, any>[] & {
-            [key: string]: Agent<any, any>;
-        };
-    };
+    readonly cli: AIGNECLIAgents;
     /**
      * Observer for the AIGNE instance.
      */

package/lib/dts/aigne/type.d.ts

@@ -0,0 +1,12 @@
+import type { Agent } from "../agents/agent.ts";
+export interface AIGNECLIAgents {
+    chat?: Agent;
+    agents?: AIGNECLIAgent[];
+}
+export interface AIGNECLIAgent {
+    agent?: Agent;
+    name?: string;
+    alias?: string[];
+    description?: string;
+    agents?: AIGNECLIAgent[];
+}

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

@@ -1,4 +1,4 @@
-import { z } from "zod";
+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";
@@ -14,10 +14,17 @@ export interface LoadOptions {
 }
 export declare function load(path: string, options?: LoadOptions): Promise<AIGNEOptions>;
 export declare function loadAgent(path: string, options?: LoadOptions, agentOptions?: AgentOptions): Promise<Agent>;
+type CliAgent = string | {
+    url?: string;
+    name?: string;
+    alias?: string[];
+    description?: string;
+    agents?: CliAgent[];
+};
 declare const aigneFileSchema: z.ZodObject<{
-    name: z.ZodType<string | undefined, z.ZodTypeDef, string | undefined>;
-    description: z.ZodType<string | undefined, z.ZodTypeDef, string | undefined>;
-    model: z.ZodType<{
+    name: ZodType<string | undefined, z.ZodTypeDef, string | undefined>;
+    description: ZodType<string | undefined, z.ZodTypeDef, string | undefined>;
+    model: ZodType<{
         model?: string | undefined;
         temperature?: number | undefined;
         topP?: number | undefined;
@@ -30,23 +37,23 @@ declare const aigneFileSchema: z.ZodObject<{
         frequencyPenalty?: number | undefined;
         presencePenalty?: number | undefined;
     } | undefined>;
-    imageModel: z.ZodType<{
+    imageModel: ZodType<{
         model?: string | undefined;
     } | undefined, z.ZodTypeDef, {
         model?: string | undefined;
     } | undefined>;
-    agents: z.ZodType<string[] | undefined, z.ZodTypeDef, string[] | undefined>;
-    skills: z.ZodType<string[] | undefined, z.ZodTypeDef, string[] | undefined>;
-    mcpServer: z.ZodType<{
+    agents: ZodType<string[] | undefined, z.ZodTypeDef, string[] | undefined>;
+    skills: ZodType<string[] | undefined, z.ZodTypeDef, string[] | undefined>;
+    mcpServer: ZodType<{
         agents?: string[] | undefined;
     } | undefined, z.ZodTypeDef, {
         agents?: string[] | undefined;
     } | undefined>;
-    cli: z.ZodType<{
-        agents?: string[] | undefined;
+    cli: ZodType<{
+        agents?: CliAgent[] | undefined;
         chat?: string | undefined;
     } | undefined, z.ZodTypeDef, {
-        agents?: string[] | undefined;
+        agents?: CliAgent[] | undefined;
         chat?: string | undefined;
     } | undefined>;
 }, "strip", z.ZodTypeAny, {
@@ -68,7 +75,7 @@ declare const aigneFileSchema: z.ZodObject<{
         agents?: string[] | undefined;
     } | undefined;
     cli?: {
-        agents?: string[] | undefined;
+        agents?: CliAgent[] | undefined;
         chat?: string | undefined;
     } | undefined;
 }, {
@@ -90,7 +97,7 @@ declare const aigneFileSchema: z.ZodObject<{
         agents?: string[] | undefined;
     } | undefined;
     cli?: {
-        agents?: string[] | undefined;
+        agents?: CliAgent[] | undefined;
         chat?: string | undefined;
     } | undefined;
 }>;

package/lib/dts/utils/agent-utils.d.ts

@@ -1,2 +1,12 @@
 import type { AgentHooks } from "../agents/agent.ts";
+import type { AIGNECLIAgents } from "../aigne/type.js";
 export declare function sortHooks(hooks: AgentHooks[]): AgentHooks[];
+export interface CLIAgent<T> {
+    agent?: T;
+    name?: string;
+    alias?: string[];
+    description?: string;
+    agents?: CLIAgent<T>[];
+}
+export declare function mapCliAgent<A, O>({ agent, agents, ...input }: CLIAgent<A>, transform: (input: A) => O): CLIAgent<O>;
+export declare function findCliAgent(cli: AIGNECLIAgents, parent: string[] | "*", name: string): import("../agents/agent.ts").Agent<any, any> | undefined;

package/lib/esm/aigne/aigne.d.ts

@@ -6,6 +6,7 @@ import type { UserAgent } from "../agents/user-agent.js";
 import { type LoadOptions } from "../loader/index.js";
 import { AIGNEContext, type Context, type InvokeOptions, type UserContext } from "./context.js";
 import { type MessagePayload, MessageQueue, type MessageQueueListener, type Unsubscribe } from "./message-queue.js";
+import type { AIGNECLIAgents } from "./type.js";
 import type { ContextLimits } from "./usage.js";
 /**
  * Options for the AIGNE class.
@@ -43,10 +44,7 @@ export interface AIGNEOptions {
     mcpServer?: {
         agents?: Agent[];
     };
-    cli?: {
-        chat?: Agent;
-        agents?: Agent[];
-    };
+    cli?: AIGNECLIAgents;
     /**
      * Limits for the AIGNE instance, such as timeout, max tokens, max invocations, etc.
      */
@@ -133,12 +131,7 @@ export declare class AIGNE<U extends UserContext = UserContext> {
             [key: string]: Agent<any, any>;
         };
     };
-    readonly cli: {
-        chat: Agent | undefined;
-        agents: Agent<any, any>[] & {
-            [key: string]: Agent<any, any>;
-        };
-    };
+    readonly cli: AIGNECLIAgents;
     /**
      * Observer for the AIGNE instance.
      */

package/lib/esm/aigne/aigne.js

@@ -60,10 +60,7 @@ export class AIGNE {
             this.addAgent(...options.agents);
         if (options?.mcpServer?.agents?.length)
             this.mcpServer.agents.push(...options.mcpServer.agents);
-        if (options?.cli?.agents?.length)
-            this.cli.agents.push(...options.cli.agents);
-        if (options?.cli?.chat)
-            this.cli.chat = options.cli.chat;
+        this.cli = options?.cli ?? {};
         this.observer?.serve();
         this.initProcessExitHandler();
     }
@@ -110,10 +107,7 @@ export class AIGNE {
     mcpServer = {
         agents: createAccessorArray([], (arr, name) => arr.find((i) => i.name === name)),
     };
-    cli = {
-        chat: undefined,
-        agents: createAccessorArray([], (arr, name) => arr.find((i) => i.name === name)),
-    };
+    cli = {};
     /**
      * Observer for the AIGNE instance.
      */

package/lib/esm/aigne/type.d.ts

@@ -0,0 +1,12 @@
+import type { Agent } from "../agents/agent.ts";
+export interface AIGNECLIAgents {
+    chat?: Agent;
+    agents?: AIGNECLIAgent[];
+}
+export interface AIGNECLIAgent {
+    agent?: Agent;
+    name?: string;
+    alias?: string[];
+    description?: string;
+    agents?: AIGNECLIAgent[];
+}

package/lib/esm/aigne/type.js

@@ -0,0 +1 @@
+export {};

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

@@ -1,4 +1,4 @@
-import { z } from "zod";
+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";
@@ -14,10 +14,17 @@ export interface LoadOptions {
 }
 export declare function load(path: string, options?: LoadOptions): Promise<AIGNEOptions>;
 export declare function loadAgent(path: string, options?: LoadOptions, agentOptions?: AgentOptions): Promise<Agent>;
+type CliAgent = string | {
+    url?: string;
+    name?: string;
+    alias?: string[];
+    description?: string;
+    agents?: CliAgent[];
+};
 declare const aigneFileSchema: z.ZodObject<{
-    name: z.ZodType<string | undefined, z.ZodTypeDef, string | undefined>;
-    description: z.ZodType<string | undefined, z.ZodTypeDef, string | undefined>;
-    model: z.ZodType<{
+    name: ZodType<string | undefined, z.ZodTypeDef, string | undefined>;
+    description: ZodType<string | undefined, z.ZodTypeDef, string | undefined>;
+    model: ZodType<{
         model?: string | undefined;
         temperature?: number | undefined;
         topP?: number | undefined;
@@ -30,23 +37,23 @@ declare const aigneFileSchema: z.ZodObject<{
         frequencyPenalty?: number | undefined;
         presencePenalty?: number | undefined;
     } | undefined>;
-    imageModel: z.ZodType<{
+    imageModel: ZodType<{
         model?: string | undefined;
     } | undefined, z.ZodTypeDef, {
         model?: string | undefined;
     } | undefined>;
-    agents: z.ZodType<string[] | undefined, z.ZodTypeDef, string[] | undefined>;
-    skills: z.ZodType<string[] | undefined, z.ZodTypeDef, string[] | undefined>;
-    mcpServer: z.ZodType<{
+    agents: ZodType<string[] | undefined, z.ZodTypeDef, string[] | undefined>;
+    skills: ZodType<string[] | undefined, z.ZodTypeDef, string[] | undefined>;
+    mcpServer: ZodType<{
         agents?: string[] | undefined;
     } | undefined, z.ZodTypeDef, {
         agents?: string[] | undefined;
     } | undefined>;
-    cli: z.ZodType<{
-        agents?: string[] | undefined;
+    cli: ZodType<{
+        agents?: CliAgent[] | undefined;
         chat?: string | undefined;
     } | undefined, z.ZodTypeDef, {
-        agents?: string[] | undefined;
+        agents?: CliAgent[] | undefined;
         chat?: string | undefined;
     } | undefined>;
 }, "strip", z.ZodTypeAny, {
@@ -68,7 +75,7 @@ declare const aigneFileSchema: z.ZodObject<{
         agents?: string[] | undefined;
     } | undefined;
     cli?: {
-        agents?: string[] | undefined;
+        agents?: CliAgent[] | undefined;
         chat?: string | undefined;
     } | undefined;
 }, {
@@ -90,7 +97,7 @@ declare const aigneFileSchema: z.ZodObject<{
         agents?: string[] | undefined;
     } | undefined;
     cli?: {
-        agents?: string[] | undefined;
+        agents?: CliAgent[] | undefined;
         chat?: string | undefined;
     } | undefined;
 }>;

package/lib/esm/loader/index.js

@@ -16,12 +16,27 @@ import { camelizeSchema, chatModelSchema, imageModelSchema, optionalize } from "
 const AIGNE_FILE_NAME = ["aigne.yaml", "aigne.yml"];
 export async function load(path, options = {}) {
     const { aigne, rootDir } = await loadAIGNEFile(path);
-    const allAgentPaths = new Set(flat(aigne.agents, aigne.skills, aigne.mcpServer?.agents, aigne.cli?.agents, aigne.cli?.chat).map((i) => nodejs.path.join(rootDir, i)));
+    const flatCliAgents = (cliAgent) => {
+        if (typeof cliAgent === "string")
+            return [cliAgent];
+        return flat(cliAgent.url, cliAgent.agents?.flatMap(flatCliAgents));
+    };
+    const allAgentPaths = new Set(flat(aigne.agents, aigne.skills, aigne.mcpServer?.agents, aigne.cli?.chat, aigne.cli?.agents?.flatMap((i) => (typeof i === "string" ? i : flatCliAgents(i)))).map((i) => nodejs.path.join(rootDir, i)));
     const allAgents = {};
     for (const path of allAgentPaths) {
         allAgents[path] = await loadAgent(path, options);
     }
-    const pickAgents = (paths) => paths.map((filename) => allAgents[nodejs.path.join(rootDir, filename)]).filter(isNonNullable);
+    const pickAgent = (path) => allAgents[nodejs.path.join(rootDir, path)];
+    const pickAgents = (paths) => paths.map((filename) => pickAgent(filename)).filter(isNonNullable);
+    const mapCliAgents = (cliAgent) => {
+        if (typeof cliAgent === "string")
+            return { agent: pickAgent(cliAgent) };
+        return {
+            ...cliAgent,
+            agent: cliAgent.url ? pickAgent(cliAgent.url) : undefined,
+            agents: cliAgent.agents?.map(mapCliAgents),
+        };
+    };
     return {
         ...aigne,
         rootDir,
@@ -36,7 +51,7 @@ export async function load(path, options = {}) {
         },
         cli: {
             chat: aigne.cli?.chat ? pickAgents([aigne.cli.chat])[0] : undefined,
-            agents: pickAgents(aigne.cli?.agents ?? []),
+            agents: aigne.cli?.agents?.map(mapCliAgents),
         },
     };
 }
@@ -181,6 +196,16 @@ async function loadMemory(memories, provider, options) {
         throw new Error(`Unsupported memory: ${provider}`);
     return new M(options);
 }
+const cliAgentSchema = z.union([
+    z.string(),
+    z.object({
+        url: optionalize(z.string()),
+        name: optionalize(z.string()),
+        alias: optionalize(z.array(z.string())),
+        description: optionalize(z.string()),
+        agents: optionalize(z.array(z.lazy(() => cliAgentSchema))),
+    }),
+]);
 const aigneFileSchema = camelizeSchema(z.object({
     name: optionalize(z.string()),
     description: optionalize(z.string()),
@@ -193,7 +218,7 @@ const aigneFileSchema = camelizeSchema(z.object({
     })),
     cli: optionalize(z.object({
         chat: optionalize(z.string()),
-        agents: optionalize(z.array(z.string())),
+        agents: optionalize(z.array(cliAgentSchema)),
     })),
 }));
 export async function loadAIGNEFile(path) {

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

@@ -1,2 +1,12 @@
 import type { AgentHooks } from "../agents/agent.ts";
+import type { AIGNECLIAgents } from "../aigne/type.js";
 export declare function sortHooks(hooks: AgentHooks[]): AgentHooks[];
+export interface CLIAgent<T> {
+    agent?: T;
+    name?: string;
+    alias?: string[];
+    description?: string;
+    agents?: CLIAgent<T>[];
+}
+export declare function mapCliAgent<A, O>({ agent, agents, ...input }: CLIAgent<A>, transform: (input: A) => O): CLIAgent<O>;
+export declare function findCliAgent(cli: AIGNECLIAgents, parent: string[] | "*", name: string): import("../agents/agent.ts").Agent<any, any> | undefined;

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

@@ -4,3 +4,45 @@ export function sortHooks(hooks) {
         .slice(0)
         .sort(({ priority: a = "low" }, { priority: b = "low" }) => a === b ? 0 : priorities.indexOf(a) - priorities.indexOf(b));
 }
+export function mapCliAgent({ agent, agents, ...input }, transform) {
+    return {
+        ...input,
+        agent: agent ? transform(agent) : undefined,
+        agents: agents?.map((item) => mapCliAgent(item, transform)),
+    };
+}
+export function findCliAgent(cli, parent, name) {
+    if (parent === "*")
+        return findCliAgentRecursive(cli, name);
+    let currentAgents = cli.agents ?? [];
+    for (const name of parent) {
+        const found = currentAgents.find((i) => (i.name || i.agent?.name) === name);
+        if (!found)
+            throw new Error(`Agent ${name} not found in parent path ${parent.join(" -> ")}`);
+        if (found.agents)
+            currentAgents = found.agents;
+        else
+            currentAgents = [];
+    }
+    return currentAgents.find((i) => (i.name || i.agent?.name) === name)?.agent;
+}
+function findCliAgentRecursive(agents, name) {
+    if (agents.chat?.name === name) {
+        return agents.chat;
+    }
+    if (agents.agents) {
+        const queue = [...agents.agents];
+        while (queue.length > 0) {
+            const c = queue.shift();
+            if (!c)
+                break;
+            if ((c.name || c.agent?.name) === name) {
+                return c.agent;
+            }
+            if (c.agents) {
+                queue.push(...c.agents);
+            }
+        }
+    }
+    return undefined;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aigne/core",
-  "version": "1.61.0",
+  "version": "1.62.0-beta",
   "description": "The functional core of agentic AI",
   "publishConfig": {
     "access": "public"
@@ -92,7 +92,7 @@
     "zod": "^3.25.67",
     "zod-from-json-schema": "^0.0.5",
     "zod-to-json-schema": "^3.24.6",
-    "@aigne/observability-api": "^0.11.0",
+    "@aigne/observability-api": "^0.11.1-beta",
     "@aigne/platform-helpers": "^0.6.3"
   },
   "devDependencies": {