@aigne/agent-library 1.24.0-beta.3 → 1.24.0-beta.5

package/CHANGELOG.md

@@ -7,6 +7,36 @@
     * @aigne/core bumped to 1.22.0
     * @aigne/openai bumped to 0.3.4
 
+## [1.24.0-beta.5](https://github.com/AIGNE-io/aigne-framework/compare/agent-library-v1.24.0-beta.4...agent-library-v1.24.0-beta.5) (2025-12-25)
+
+
+### Features
+
+* **agent-library:** add askUserQuestion agent ([#848](https://github.com/AIGNE-io/aigne-framework/issues/848)) ([60fa69b](https://github.com/AIGNE-io/aigne-framework/commit/60fa69b40ec122295e57ad175075875ed4840345))
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @aigne/core bumped to 1.72.0-beta.5
+    * @aigne/openai bumped to 0.16.16-beta.5
+
+## [1.24.0-beta.4](https://github.com/AIGNE-io/aigne-framework/compare/agent-library-v1.24.0-beta.3...agent-library-v1.24.0-beta.4) (2025-12-24)
+
+
+### Features
+
+* add Agent Skill support ([#787](https://github.com/AIGNE-io/aigne-framework/issues/787)) ([f04fbe7](https://github.com/AIGNE-io/aigne-framework/commit/f04fbe76ec24cf3c59c74adf92d87b0c3784a8f7))
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @aigne/core bumped to 1.72.0-beta.4
+    * @aigne/openai bumped to 0.16.16-beta.4
+
 ## [1.24.0-beta.3](https://github.com/AIGNE-io/aigne-framework/compare/agent-library-v1.24.0-beta.2...agent-library-v1.24.0-beta.3) (2025-12-19)
 
 

package/lib/cjs/ask-user-question/index.d.ts

@@ -0,0 +1,29 @@
+import { Agent, type AgentInvokeOptions, type AgentProcessResult, type Message } from "@aigne/core";
+import { z } from "zod";
+export interface AskUserQuestionAgentOption {
+    label: string;
+    description?: string;
+}
+export interface AskUserQuestionAgentInput extends Message {
+    questions: {
+        question: string;
+        options?: AskUserQuestionAgentOption[];
+        multipleSelect?: boolean;
+    }[];
+    allowCustomAnswer?: boolean;
+}
+export interface AskUserQuestionAgentOutput extends Message {
+    answers: {
+        question: string;
+        answer: string | string[];
+    }[];
+}
+export default class AskUserQuestionAgent extends Agent<AskUserQuestionAgentInput, AskUserQuestionAgentOutput> {
+    tag: string;
+    static schema(): z.ZodObject<{}, "strip", z.ZodTypeAny, {}, {}>;
+    static load<I extends Message = any, O extends Message = any>(options: {
+        filepath: string;
+        parsed: object;
+    }): Promise<Agent<I, O>>;
+    process(input: AskUserQuestionAgentInput, options: AgentInvokeOptions): Promise<AgentProcessResult<AskUserQuestionAgentOutput>>;
+}

package/lib/cjs/ask-user-question/index.js

@@ -0,0 +1,100 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const core_1 = require("@aigne/core");
+const schema_js_1 = require("@aigne/core/loader/schema.js");
+const zod_1 = require("zod");
+const askUserQuestionAgentOptionSchema = zod_1.z.object({
+    label: zod_1.z.string().describe("The display text for this option (1-5 words)"),
+    description: (0, schema_js_1.optionalize)(zod_1.z.string()).describe("Explanation of what this option means"),
+});
+const askUserQuestionAgentInputSchema = zod_1.z.object({
+    questions: zod_1.z
+        .array(zod_1.z.object({
+        question: zod_1.z.string().describe("The question to ask the user"),
+        options: (0, schema_js_1.optionalize)(zod_1.z.array(askUserQuestionAgentOptionSchema)).describe("List of options to present to the user"),
+        multipleSelect: (0, schema_js_1.optionalize)(zod_1.z.boolean()).describe("Whether to allow multiple selections"),
+    }))
+        .describe("List of questions to ask the user"),
+    allowCustomAnswer: (0, schema_js_1.optionalize)(zod_1.z.boolean()).describe("Whether to allow the user to provide custom answers"),
+});
+class AskUserQuestionAgent extends core_1.Agent {
+    tag = "AskUserQuestion";
+    static schema() {
+        return zod_1.z.object({});
+    }
+    static async load(options) {
+        return new AskUserQuestionAgent({
+            name: defaultName,
+            description: defaultDescription,
+            ...options.parsed,
+            inputSchema: askUserQuestionAgentInputSchema,
+        });
+    }
+    async process(input, options) {
+        const { prompts } = options;
+        if (!prompts)
+            throw new Error("Prompts is not available in AskUserQuestionAgent");
+        const { questions, allowCustomAnswer } = input;
+        const answers = [];
+        for (const q of questions) {
+            let answer;
+            if (q.options?.length) {
+                const choices = q.options.map((opt) => ({
+                    value: opt.label,
+                    name: opt.label,
+                    description: opt.description ?? opt.label,
+                }));
+                if (allowCustomAnswer) {
+                    choices.push({
+                        name: "None of the above / Enter my own response",
+                        value: "OTHER_OPTION",
+                    });
+                }
+                if (!q.multipleSelect) {
+                    answer = await prompts.select({
+                        message: q.question,
+                        choices,
+                    });
+                }
+                else {
+                    answer = await prompts.checkbox({
+                        message: q.question,
+                        choices,
+                    });
+                }
+                if (answer === "OTHER_OPTION" ||
+                    (Array.isArray(answer) && answer.includes("OTHER_OPTION"))) {
+                    answer = await prompts.input({
+                        message: `Please provide your response for: ${q.question}`,
+                    });
+                }
+            }
+            else {
+                answer = await prompts.input({
+                    message: q.question,
+                });
+            }
+            answers.push({
+                question: q.question,
+                answer,
+            });
+        }
+        return {
+            answers,
+        };
+    }
+}
+exports.default = AskUserQuestionAgent;
+const defaultName = "askUserQuestion";
+const defaultDescription = `\
+Use this tool when you need to ask the user questions during execution. This allows you to:
+1. Gather user preferences or requirements
+2. Clarify ambiguous instructions
+3. Get decisions on implementation choices as you work
+4. Offer choices to the user about what direction to take.
+
+Usage notes:
+- Users will always be able to select "Other" to provide custom text input
+- Use multiSelect: true to allow multiple answers to be selected for a question
+- If you recommend a specific option, make that the first option in the list and add "(Recommended)" at the end of the label
+`;

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

@@ -3,6 +3,7 @@ import { Agent, type AgentInvokeOptions, type AgentOptions, type AgentResponseSt
 import { type NestAgentSchema } from "@aigne/core/loader/agent-yaml.js";
 import { type LoadOptions } from "@aigne/core/loader/index.js";
 import { type SandboxRuntimeConfig } from "@anthropic-ai/sandbox-runtime";
+import z from "zod";
 export interface BashAgentOptions extends AgentOptions<BashAgentInput, BashAgentOutput> {
     sandbox?: Partial<{
         [K in keyof SandboxRuntimeConfig]: Partial<SandboxRuntimeConfig[K]>;
@@ -59,6 +60,53 @@ export interface BashAgentOutput extends Message {
 }
 export declare class BashAgent extends Agent<BashAgentInput, BashAgentOutput> {
     options: BashAgentOptions;
+    tag: string;
+    static schema({ filepath }: {
+        filepath: string;
+    }): z.ZodObject<{
+        sandbox: z.ZodType<boolean | {
+            [x: string]: z.ZodTypeAny | undefined;
+        } | undefined, z.ZodTypeDef, boolean | {
+            [x: string]: z.ZodTypeAny | undefined;
+        } | undefined>;
+        inputKey: z.ZodType<string | undefined, z.ZodTypeDef, string | undefined>;
+        timeout: z.ZodType<number | undefined, z.ZodTypeDef, number | undefined>;
+        permissions: z.ZodType<{
+            allow?: string[] | undefined;
+            deny?: string[] | undefined;
+            guard?: NestAgentSchema | undefined;
+            defaultMode?: "allow" | "ask" | "deny" | undefined;
+        } | undefined, z.ZodTypeDef, {
+            allow?: string[] | undefined;
+            deny?: string[] | undefined;
+            guard?: NestAgentSchema | undefined;
+            defaultMode?: "allow" | "ask" | "deny" | undefined;
+        } | undefined>;
+    }, "strip", z.ZodTypeAny, {
+        sandbox?: boolean | {
+            [x: string]: z.ZodTypeAny | undefined;
+        } | undefined;
+        inputKey?: string | undefined;
+        timeout?: number | undefined;
+        permissions?: {
+            allow?: string[] | undefined;
+            deny?: string[] | undefined;
+            guard?: NestAgentSchema | undefined;
+            defaultMode?: "allow" | "ask" | "deny" | undefined;
+        } | undefined;
+    }, {
+        sandbox?: boolean | {
+            [x: string]: z.ZodTypeAny | undefined;
+        } | undefined;
+        inputKey?: string | undefined;
+        timeout?: number | undefined;
+        permissions?: {
+            allow?: string[] | undefined;
+            deny?: string[] | undefined;
+            guard?: NestAgentSchema | undefined;
+            defaultMode?: "allow" | "ask" | "deny" | undefined;
+        } | undefined;
+    }>;
     static load(options: {
         filepath: string;
         parsed: LoadBashAgentOptions;

package/lib/cjs/bash/index.js

@@ -48,15 +48,30 @@ let sandboxInitialization;
 const mutex = new mutex_js_1.Mutex();
 class BashAgent extends core_1.Agent {
     options;
+    tag = "Bash";
+    static schema({ filepath }) {
+        const nestAgentSchema = (0, agent_yaml_js_1.getNestAgentSchema)({ filepath });
+        return (0, schema_js_1.camelizeSchema)(zod_1.default.object({
+            sandbox: (0, schema_js_1.optionalize)(zod_1.default.union([makeShapePropertiesOptions(sandbox_runtime_1.SandboxRuntimeConfigSchema, 2), zod_1.default.boolean()])),
+            inputKey: (0, schema_js_1.optionalize)(zod_1.default.string().describe("The input key for the bash script.")),
+            timeout: (0, schema_js_1.optionalize)(zod_1.default.number().describe("Timeout for script execution in milliseconds.")),
+            permissions: (0, schema_js_1.optionalize)((0, schema_js_1.camelizeSchema)(zod_1.default.object({
+                allow: (0, schema_js_1.optionalize)(zod_1.default.array(zod_1.default.string())),
+                deny: (0, schema_js_1.optionalize)(zod_1.default.array(zod_1.default.string())),
+                defaultMode: (0, schema_js_1.optionalize)(zod_1.default.enum(["allow", "ask", "deny"])),
+                guard: (0, schema_js_1.optionalize)(nestAgentSchema),
+            }))),
+        }));
+    }
     static async load(options) {
-        const schema = getBashAgentSchema({ filepath: options.filepath });
-        const parsed = await schema.parseAsync(options.parsed);
+        const valid = await BashAgent.schema(options).parseAsync(options.parsed);
         return new BashAgent({
-            ...parsed,
+            ...options.parsed,
+            ...valid,
             permissions: {
-                ...parsed.permissions,
-                guard: parsed.permissions?.guard
-                    ? await (0, index_js_1.loadNestAgent)(options.filepath, parsed.permissions.guard, options.options ?? {}, {
+                ...valid.permissions,
+                guard: valid.permissions?.guard
+                    ? await (0, index_js_1.loadNestAgent)(options.filepath, valid.permissions.guard, options.options ?? {}, {
                         outputSchema: zod_1.default.object({
                             approved: zod_1.default.boolean().describe("Whether the command is approved by the user."),
                             reason: zod_1.default.string().describe("Optional reason for rejection.").optional(),
@@ -334,20 +349,6 @@ When to use:
 }
 exports.BashAgent = BashAgent;
 exports.default = BashAgent;
-function getBashAgentSchema({ filepath }) {
-    const nestAgentSchema = (0, agent_yaml_js_1.getNestAgentSchema)({ filepath });
-    return (0, schema_js_1.camelizeSchema)(zod_1.default.object({
-        sandbox: (0, schema_js_1.optionalize)(zod_1.default.union([makeShapePropertiesOptions(sandbox_runtime_1.SandboxRuntimeConfigSchema, 2), zod_1.default.boolean()])),
-        inputKey: (0, schema_js_1.optionalize)(zod_1.default.string().describe("The input key for the bash script.")),
-        timeout: (0, schema_js_1.optionalize)(zod_1.default.number().describe("Timeout for script execution in milliseconds.")),
-        permissions: (0, schema_js_1.optionalize)((0, schema_js_1.camelizeSchema)(zod_1.default.object({
-            allow: (0, schema_js_1.optionalize)(zod_1.default.array(zod_1.default.string())),
-            deny: (0, schema_js_1.optionalize)(zod_1.default.array(zod_1.default.string())),
-            defaultMode: (0, schema_js_1.optionalize)(zod_1.default.enum(["allow", "ask", "deny"])),
-            guard: (0, schema_js_1.optionalize)(nestAgentSchema),
-        }))),
-    }));
-}
 function makeShapePropertiesOptions(schema, depth = 1) {
     return zod_1.default.object(Object.fromEntries(Object.entries(schema.shape).map(([key, value]) => {
         const isObject = value instanceof zod_1.ZodObject;

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

@@ -1,6 +1,8 @@
 import { type AgentInvokeOptions, type AgentOptions, AIAgent, type AIAgentOptions, type Message, type PromptBuilder } from "@aigne/core";
-import { type Instructions, type NestAgentSchema } from "@aigne/core/loader/agent-yaml.js";
-import { type LoadOptions } from "@aigne/core/loader/index.js";
+import { type NestAgentSchema } from "@aigne/core/loader/agent-yaml.js";
+import type { AgentLoadOptions } from "@aigne/core/loader/index.js";
+import { type Instructions } from "@aigne/core/loader/schema.js";
+import { type ZodType } from "zod";
 import { type StateManagementOptions } from "./type.js";
 /**
  * Configuration options for the Orchestrator Agent
@@ -17,17 +19,11 @@ export interface OrchestratorAgentOptions<I extends Message = Message, O extends
     stateManagement?: StateManagementOptions;
     concurrency?: number;
 }
-export interface LoadOrchestratorAgentOptions<I extends Message = Message, O extends Message = Message> extends Omit<AIAgentOptions<I, O>, "instructions"> {
-    objective?: string | PromptBuilder | Instructions;
-    planner?: NestAgentSchema | {
-        instructions?: string | PromptBuilder | Instructions;
-    };
-    worker?: NestAgentSchema | {
-        instructions?: string | PromptBuilder | Instructions;
-    };
-    completer?: NestAgentSchema | {
-        instructions?: string | PromptBuilder | Instructions;
-    };
+export interface LoadOrchestratorAgentOptions {
+    objective?: string | Instructions;
+    planner?: NestAgentSchema;
+    worker?: NestAgentSchema;
+    completer?: NestAgentSchema;
     stateManagement?: StateManagementOptions;
 }
 /**
@@ -47,10 +43,13 @@ export interface LoadOrchestratorAgentOptions<I extends Message = Message, O ext
  */
 export declare class OrchestratorAgent<I extends Message = Message, O extends Message = Message> extends AIAgent<I, O> {
     tag: string;
+    static schema<T>({ filepath }: {
+        filepath: string;
+    }): ZodType<T>;
     static load<I extends Message = Message, O extends Message = Message>({ filepath, parsed, options, }: {
         filepath: string;
-        parsed: AgentOptions<I, O> & LoadOrchestratorAgentOptions<I, O>;
-        options?: LoadOptions;
+        parsed: LoadOrchestratorAgentOptions & AgentOptions<I, O>;
+        options?: AgentLoadOptions;
     }): Promise<OrchestratorAgent<I, O>>;
     /**
      * Factory method to create an OrchestratorAgent instance

package/lib/cjs/orchestrator/index.js

@@ -36,7 +36,6 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.OrchestratorAgent = void 0;
 const core_1 = require("@aigne/core");
 const agent_yaml_js_1 = require("@aigne/core/loader/agent-yaml.js");
-const index_js_1 = require("@aigne/core/loader/index.js");
 const schema_js_1 = require("@aigne/core/loader/schema.js");
 const agent_utils_js_1 = require("@aigne/core/utils/agent-utils.js");
 const fastq = __importStar(require("@aigne/core/utils/queue.js"));
@@ -90,28 +89,41 @@ const DEFAULT_CONCURRENCY = 5;
  */
 class OrchestratorAgent extends core_1.AIAgent {
     tag = "OrchestratorAgent";
-    static async load({ filepath, parsed, options = {}, }) {
-        const schema = getOrchestratorAgentSchema({ filepath });
-        const valid = await schema.parseAsync(parsed);
+    static schema({ filepath }) {
+        const nestAgentSchema = (0, agent_yaml_js_1.getNestAgentSchema)({ filepath });
+        const instructionsSchema = (0, schema_js_1.getInstructionsSchema)({ filepath });
+        return (0, schema_js_1.camelizeSchema)(zod_1.z.object({
+            objective: (0, schema_js_1.optionalize)(instructionsSchema),
+            planner: (0, schema_js_1.optionalize)(nestAgentSchema),
+            worker: (0, schema_js_1.optionalize)(nestAgentSchema),
+            completer: (0, schema_js_1.optionalize)(nestAgentSchema),
+            stateManagement: (0, schema_js_1.optionalize)((0, schema_js_1.camelizeSchema)(type_js_1.stateManagementOptionsSchema)),
+            concurrency: (0, schema_js_1.optionalize)(zod_1.z.number().int().min(1).default(DEFAULT_CONCURRENCY)),
+        }));
+    }
+    static async load({ filepath, parsed, options, }) {
+        const valid = await OrchestratorAgent.schema({
+            filepath,
+        }).parseAsync(parsed);
         return new OrchestratorAgent({
             ...parsed,
-            objective: valid.objective && (0, index_js_1.instructionsToPromptBuilder)(valid.objective),
+            objective: valid.objective ? (0, schema_js_1.instructionsToPromptBuilder)(valid.objective) : undefined,
             planner: valid.planner
-                ? (await (0, index_js_1.loadNestAgent)(filepath, valid.planner, options, {
+                ? (await options?.loadNestAgent(filepath, valid.planner, options, {
                     ...defaultPlannerOptions,
                     afs: parsed.afs,
                     skills: parsed.skills,
                 }))
                 : undefined,
             worker: valid.worker
-                ? (await (0, index_js_1.loadNestAgent)(filepath, valid.worker, options, {
+                ? (await options?.loadNestAgent(filepath, valid.worker, options, {
                     ...defaultWorkerOptions,
                     afs: parsed.afs,
                     skills: parsed.skills,
                 }))
                 : undefined,
             completer: valid.completer
-                ? (await (0, index_js_1.loadNestAgent)(filepath, valid.completer, options, {
+                ? (await options?.loadNestAgent(filepath, valid.completer, options, {
                     ...defaultCompleterOptions,
                     outputSchema: parsed.outputSchema,
                     afs: parsed.afs,
@@ -272,15 +284,3 @@ class OrchestratorAgent extends core_1.AIAgent {
 }
 exports.OrchestratorAgent = OrchestratorAgent;
 exports.default = OrchestratorAgent;
-function getOrchestratorAgentSchema({ filepath }) {
-    const nestAgentSchema = (0, agent_yaml_js_1.getNestAgentSchema)({ filepath });
-    const instructionsSchema = (0, agent_yaml_js_1.getInstructionsSchema)({ filepath });
-    return (0, schema_js_1.camelizeSchema)(zod_1.z.object({
-        objective: (0, schema_js_1.optionalize)(instructionsSchema),
-        planner: (0, schema_js_1.optionalize)(nestAgentSchema),
-        worker: (0, schema_js_1.optionalize)(nestAgentSchema),
-        completer: (0, schema_js_1.optionalize)(nestAgentSchema),
-        stateManagement: (0, schema_js_1.optionalize)((0, schema_js_1.camelizeSchema)(type_js_1.stateManagementOptionsSchema)),
-        concurrency: (0, schema_js_1.optionalize)(zod_1.z.number().int().min(1).default(DEFAULT_CONCURRENCY)),
-    }));
-}

package/lib/dts/ask-user-question/index.d.ts

@@ -0,0 +1,29 @@
+import { Agent, type AgentInvokeOptions, type AgentProcessResult, type Message } from "@aigne/core";
+import { z } from "zod";
+export interface AskUserQuestionAgentOption {
+    label: string;
+    description?: string;
+}
+export interface AskUserQuestionAgentInput extends Message {
+    questions: {
+        question: string;
+        options?: AskUserQuestionAgentOption[];
+        multipleSelect?: boolean;
+    }[];
+    allowCustomAnswer?: boolean;
+}
+export interface AskUserQuestionAgentOutput extends Message {
+    answers: {
+        question: string;
+        answer: string | string[];
+    }[];
+}
+export default class AskUserQuestionAgent extends Agent<AskUserQuestionAgentInput, AskUserQuestionAgentOutput> {
+    tag: string;
+    static schema(): z.ZodObject<{}, "strip", z.ZodTypeAny, {}, {}>;
+    static load<I extends Message = any, O extends Message = any>(options: {
+        filepath: string;
+        parsed: object;
+    }): Promise<Agent<I, O>>;
+    process(input: AskUserQuestionAgentInput, options: AgentInvokeOptions): Promise<AgentProcessResult<AskUserQuestionAgentOutput>>;
+}

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

@@ -3,6 +3,7 @@ import { Agent, type AgentInvokeOptions, type AgentOptions, type AgentResponseSt
 import { type NestAgentSchema } from "@aigne/core/loader/agent-yaml.js";
 import { type LoadOptions } from "@aigne/core/loader/index.js";
 import { type SandboxRuntimeConfig } from "@anthropic-ai/sandbox-runtime";
+import z from "zod";
 export interface BashAgentOptions extends AgentOptions<BashAgentInput, BashAgentOutput> {
     sandbox?: Partial<{
         [K in keyof SandboxRuntimeConfig]: Partial<SandboxRuntimeConfig[K]>;
@@ -59,6 +60,53 @@ export interface BashAgentOutput extends Message {
 }
 export declare class BashAgent extends Agent<BashAgentInput, BashAgentOutput> {
     options: BashAgentOptions;
+    tag: string;
+    static schema({ filepath }: {
+        filepath: string;
+    }): z.ZodObject<{
+        sandbox: z.ZodType<boolean | {
+            [x: string]: z.ZodTypeAny | undefined;
+        } | undefined, z.ZodTypeDef, boolean | {
+            [x: string]: z.ZodTypeAny | undefined;
+        } | undefined>;
+        inputKey: z.ZodType<string | undefined, z.ZodTypeDef, string | undefined>;
+        timeout: z.ZodType<number | undefined, z.ZodTypeDef, number | undefined>;
+        permissions: z.ZodType<{
+            allow?: string[] | undefined;
+            deny?: string[] | undefined;
+            guard?: NestAgentSchema | undefined;
+            defaultMode?: "allow" | "ask" | "deny" | undefined;
+        } | undefined, z.ZodTypeDef, {
+            allow?: string[] | undefined;
+            deny?: string[] | undefined;
+            guard?: NestAgentSchema | undefined;
+            defaultMode?: "allow" | "ask" | "deny" | undefined;
+        } | undefined>;
+    }, "strip", z.ZodTypeAny, {
+        sandbox?: boolean | {
+            [x: string]: z.ZodTypeAny | undefined;
+        } | undefined;
+        inputKey?: string | undefined;
+        timeout?: number | undefined;
+        permissions?: {
+            allow?: string[] | undefined;
+            deny?: string[] | undefined;
+            guard?: NestAgentSchema | undefined;
+            defaultMode?: "allow" | "ask" | "deny" | undefined;
+        } | undefined;
+    }, {
+        sandbox?: boolean | {
+            [x: string]: z.ZodTypeAny | undefined;
+        } | undefined;
+        inputKey?: string | undefined;
+        timeout?: number | undefined;
+        permissions?: {
+            allow?: string[] | undefined;
+            deny?: string[] | undefined;
+            guard?: NestAgentSchema | undefined;
+            defaultMode?: "allow" | "ask" | "deny" | undefined;
+        } | undefined;
+    }>;
     static load(options: {
         filepath: string;
         parsed: LoadBashAgentOptions;

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

@@ -1,6 +1,8 @@
 import { type AgentInvokeOptions, type AgentOptions, AIAgent, type AIAgentOptions, type Message, type PromptBuilder } from "@aigne/core";
-import { type Instructions, type NestAgentSchema } from "@aigne/core/loader/agent-yaml.js";
-import { type LoadOptions } from "@aigne/core/loader/index.js";
+import { type NestAgentSchema } from "@aigne/core/loader/agent-yaml.js";
+import type { AgentLoadOptions } from "@aigne/core/loader/index.js";
+import { type Instructions } from "@aigne/core/loader/schema.js";
+import { type ZodType } from "zod";
 import { type StateManagementOptions } from "./type.js";
 /**
  * Configuration options for the Orchestrator Agent
@@ -17,17 +19,11 @@ export interface OrchestratorAgentOptions<I extends Message = Message, O extends
     stateManagement?: StateManagementOptions;
     concurrency?: number;
 }
-export interface LoadOrchestratorAgentOptions<I extends Message = Message, O extends Message = Message> extends Omit<AIAgentOptions<I, O>, "instructions"> {
-    objective?: string | PromptBuilder | Instructions;
-    planner?: NestAgentSchema | {
-        instructions?: string | PromptBuilder | Instructions;
-    };
-    worker?: NestAgentSchema | {
-        instructions?: string | PromptBuilder | Instructions;
-    };
-    completer?: NestAgentSchema | {
-        instructions?: string | PromptBuilder | Instructions;
-    };
+export interface LoadOrchestratorAgentOptions {
+    objective?: string | Instructions;
+    planner?: NestAgentSchema;
+    worker?: NestAgentSchema;
+    completer?: NestAgentSchema;
     stateManagement?: StateManagementOptions;
 }
 /**
@@ -47,10 +43,13 @@ export interface LoadOrchestratorAgentOptions<I extends Message = Message, O ext
  */
 export declare class OrchestratorAgent<I extends Message = Message, O extends Message = Message> extends AIAgent<I, O> {
     tag: string;
+    static schema<T>({ filepath }: {
+        filepath: string;
+    }): ZodType<T>;
     static load<I extends Message = Message, O extends Message = Message>({ filepath, parsed, options, }: {
         filepath: string;
-        parsed: AgentOptions<I, O> & LoadOrchestratorAgentOptions<I, O>;
-        options?: LoadOptions;
+        parsed: LoadOrchestratorAgentOptions & AgentOptions<I, O>;
+        options?: AgentLoadOptions;
     }): Promise<OrchestratorAgent<I, O>>;
     /**
      * Factory method to create an OrchestratorAgent instance

package/lib/esm/ask-user-question/index.d.ts

@@ -0,0 +1,29 @@
+import { Agent, type AgentInvokeOptions, type AgentProcessResult, type Message } from "@aigne/core";
+import { z } from "zod";
+export interface AskUserQuestionAgentOption {
+    label: string;
+    description?: string;
+}
+export interface AskUserQuestionAgentInput extends Message {
+    questions: {
+        question: string;
+        options?: AskUserQuestionAgentOption[];
+        multipleSelect?: boolean;
+    }[];
+    allowCustomAnswer?: boolean;
+}
+export interface AskUserQuestionAgentOutput extends Message {
+    answers: {
+        question: string;
+        answer: string | string[];
+    }[];
+}
+export default class AskUserQuestionAgent extends Agent<AskUserQuestionAgentInput, AskUserQuestionAgentOutput> {
+    tag: string;
+    static schema(): z.ZodObject<{}, "strip", z.ZodTypeAny, {}, {}>;
+    static load<I extends Message = any, O extends Message = any>(options: {
+        filepath: string;
+        parsed: object;
+    }): Promise<Agent<I, O>>;
+    process(input: AskUserQuestionAgentInput, options: AgentInvokeOptions): Promise<AgentProcessResult<AskUserQuestionAgentOutput>>;
+}

package/lib/esm/ask-user-question/index.js

@@ -0,0 +1,97 @@
+import { Agent } from "@aigne/core";
+import { optionalize } from "@aigne/core/loader/schema.js";
+import { z } from "zod";
+const askUserQuestionAgentOptionSchema = z.object({
+    label: z.string().describe("The display text for this option (1-5 words)"),
+    description: optionalize(z.string()).describe("Explanation of what this option means"),
+});
+const askUserQuestionAgentInputSchema = z.object({
+    questions: z
+        .array(z.object({
+        question: z.string().describe("The question to ask the user"),
+        options: optionalize(z.array(askUserQuestionAgentOptionSchema)).describe("List of options to present to the user"),
+        multipleSelect: optionalize(z.boolean()).describe("Whether to allow multiple selections"),
+    }))
+        .describe("List of questions to ask the user"),
+    allowCustomAnswer: optionalize(z.boolean()).describe("Whether to allow the user to provide custom answers"),
+});
+export default class AskUserQuestionAgent extends Agent {
+    tag = "AskUserQuestion";
+    static schema() {
+        return z.object({});
+    }
+    static async load(options) {
+        return new AskUserQuestionAgent({
+            name: defaultName,
+            description: defaultDescription,
+            ...options.parsed,
+            inputSchema: askUserQuestionAgentInputSchema,
+        });
+    }
+    async process(input, options) {
+        const { prompts } = options;
+        if (!prompts)
+            throw new Error("Prompts is not available in AskUserQuestionAgent");
+        const { questions, allowCustomAnswer } = input;
+        const answers = [];
+        for (const q of questions) {
+            let answer;
+            if (q.options?.length) {
+                const choices = q.options.map((opt) => ({
+                    value: opt.label,
+                    name: opt.label,
+                    description: opt.description ?? opt.label,
+                }));
+                if (allowCustomAnswer) {
+                    choices.push({
+                        name: "None of the above / Enter my own response",
+                        value: "OTHER_OPTION",
+                    });
+                }
+                if (!q.multipleSelect) {
+                    answer = await prompts.select({
+                        message: q.question,
+                        choices,
+                    });
+                }
+                else {
+                    answer = await prompts.checkbox({
+                        message: q.question,
+                        choices,
+                    });
+                }
+                if (answer === "OTHER_OPTION" ||
+                    (Array.isArray(answer) && answer.includes("OTHER_OPTION"))) {
+                    answer = await prompts.input({
+                        message: `Please provide your response for: ${q.question}`,
+                    });
+                }
+            }
+            else {
+                answer = await prompts.input({
+                    message: q.question,
+                });
+            }
+            answers.push({
+                question: q.question,
+                answer,
+            });
+        }
+        return {
+            answers,
+        };
+    }
+}
+const defaultName = "askUserQuestion";
+const defaultDescription = `\
+Use this tool when you need to ask the user questions during execution. This allows you to:
+1. Gather user preferences or requirements
+2. Clarify ambiguous instructions
+3. Get decisions on implementation choices as you work
+4. Offer choices to the user about what direction to take.
+
+Usage notes:
+- Users will always be able to select "Other" to provide custom text input
+- Use multiSelect: true to allow multiple answers to be selected for a question
+- If you recommend a specific option, make that the first option in the list and add "(Recommended)" at the end of the label
+`;

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

@@ -3,6 +3,7 @@ import { Agent, type AgentInvokeOptions, type AgentOptions, type AgentResponseSt
 import { type NestAgentSchema } from "@aigne/core/loader/agent-yaml.js";
 import { type LoadOptions } from "@aigne/core/loader/index.js";
 import { type SandboxRuntimeConfig } from "@anthropic-ai/sandbox-runtime";
+import z from "zod";
 export interface BashAgentOptions extends AgentOptions<BashAgentInput, BashAgentOutput> {
     sandbox?: Partial<{
         [K in keyof SandboxRuntimeConfig]: Partial<SandboxRuntimeConfig[K]>;
@@ -59,6 +60,53 @@ export interface BashAgentOutput extends Message {
 }
 export declare class BashAgent extends Agent<BashAgentInput, BashAgentOutput> {
     options: BashAgentOptions;
+    tag: string;
+    static schema({ filepath }: {
+        filepath: string;
+    }): z.ZodObject<{
+        sandbox: z.ZodType<boolean | {
+            [x: string]: z.ZodTypeAny | undefined;
+        } | undefined, z.ZodTypeDef, boolean | {
+            [x: string]: z.ZodTypeAny | undefined;
+        } | undefined>;
+        inputKey: z.ZodType<string | undefined, z.ZodTypeDef, string | undefined>;
+        timeout: z.ZodType<number | undefined, z.ZodTypeDef, number | undefined>;
+        permissions: z.ZodType<{
+            allow?: string[] | undefined;
+            deny?: string[] | undefined;
+            guard?: NestAgentSchema | undefined;
+            defaultMode?: "allow" | "ask" | "deny" | undefined;
+        } | undefined, z.ZodTypeDef, {
+            allow?: string[] | undefined;
+            deny?: string[] | undefined;
+            guard?: NestAgentSchema | undefined;
+            defaultMode?: "allow" | "ask" | "deny" | undefined;
+        } | undefined>;
+    }, "strip", z.ZodTypeAny, {
+        sandbox?: boolean | {
+            [x: string]: z.ZodTypeAny | undefined;
+        } | undefined;
+        inputKey?: string | undefined;
+        timeout?: number | undefined;
+        permissions?: {
+            allow?: string[] | undefined;
+            deny?: string[] | undefined;
+            guard?: NestAgentSchema | undefined;
+            defaultMode?: "allow" | "ask" | "deny" | undefined;
+        } | undefined;
+    }, {
+        sandbox?: boolean | {
+            [x: string]: z.ZodTypeAny | undefined;
+        } | undefined;
+        inputKey?: string | undefined;
+        timeout?: number | undefined;
+        permissions?: {
+            allow?: string[] | undefined;
+            deny?: string[] | undefined;
+            guard?: NestAgentSchema | undefined;
+            defaultMode?: "allow" | "ask" | "deny" | undefined;
+        } | undefined;
+    }>;
     static load(options: {
         filepath: string;
         parsed: LoadBashAgentOptions;

package/lib/esm/bash/index.js

@@ -12,15 +12,30 @@ let sandboxInitialization;
 const mutex = new Mutex();
 export class BashAgent extends Agent {
     options;
+    tag = "Bash";
+    static schema({ filepath }) {
+        const nestAgentSchema = getNestAgentSchema({ filepath });
+        return camelizeSchema(z.object({
+            sandbox: optionalize(z.union([makeShapePropertiesOptions(SandboxRuntimeConfigSchema, 2), z.boolean()])),
+            inputKey: optionalize(z.string().describe("The input key for the bash script.")),
+            timeout: optionalize(z.number().describe("Timeout for script execution in milliseconds.")),
+            permissions: optionalize(camelizeSchema(z.object({
+                allow: optionalize(z.array(z.string())),
+                deny: optionalize(z.array(z.string())),
+                defaultMode: optionalize(z.enum(["allow", "ask", "deny"])),
+                guard: optionalize(nestAgentSchema),
+            }))),
+        }));
+    }
     static async load(options) {
-        const schema = getBashAgentSchema({ filepath: options.filepath });
-        const parsed = await schema.parseAsync(options.parsed);
+        const valid = await BashAgent.schema(options).parseAsync(options.parsed);
         return new BashAgent({
-            ...parsed,
+            ...options.parsed,
+            ...valid,
             permissions: {
-                ...parsed.permissions,
-                guard: parsed.permissions?.guard
-                    ? await loadNestAgent(options.filepath, parsed.permissions.guard, options.options ?? {}, {
+                ...valid.permissions,
+                guard: valid.permissions?.guard
+                    ? await loadNestAgent(options.filepath, valid.permissions.guard, options.options ?? {}, {
                         outputSchema: z.object({
                             approved: z.boolean().describe("Whether the command is approved by the user."),
                             reason: z.string().describe("Optional reason for rejection.").optional(),
@@ -297,20 +312,6 @@ When to use:
     }
 }
 export default BashAgent;
-function getBashAgentSchema({ filepath }) {
-    const nestAgentSchema = getNestAgentSchema({ filepath });
-    return camelizeSchema(z.object({
-        sandbox: optionalize(z.union([makeShapePropertiesOptions(SandboxRuntimeConfigSchema, 2), z.boolean()])),
-        inputKey: optionalize(z.string().describe("The input key for the bash script.")),
-        timeout: optionalize(z.number().describe("Timeout for script execution in milliseconds.")),
-        permissions: optionalize(camelizeSchema(z.object({
-            allow: optionalize(z.array(z.string())),
-            deny: optionalize(z.array(z.string())),
-            defaultMode: optionalize(z.enum(["allow", "ask", "deny"])),
-            guard: optionalize(nestAgentSchema),
-        }))),
-    }));
-}
 function makeShapePropertiesOptions(schema, depth = 1) {
     return z.object(Object.fromEntries(Object.entries(schema.shape).map(([key, value]) => {
         const isObject = value instanceof ZodObject;

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

@@ -1,6 +1,8 @@
 import { type AgentInvokeOptions, type AgentOptions, AIAgent, type AIAgentOptions, type Message, type PromptBuilder } from "@aigne/core";
-import { type Instructions, type NestAgentSchema } from "@aigne/core/loader/agent-yaml.js";
-import { type LoadOptions } from "@aigne/core/loader/index.js";
+import { type NestAgentSchema } from "@aigne/core/loader/agent-yaml.js";
+import type { AgentLoadOptions } from "@aigne/core/loader/index.js";
+import { type Instructions } from "@aigne/core/loader/schema.js";
+import { type ZodType } from "zod";
 import { type StateManagementOptions } from "./type.js";
 /**
  * Configuration options for the Orchestrator Agent
@@ -17,17 +19,11 @@ export interface OrchestratorAgentOptions<I extends Message = Message, O extends
     stateManagement?: StateManagementOptions;
     concurrency?: number;
 }
-export interface LoadOrchestratorAgentOptions<I extends Message = Message, O extends Message = Message> extends Omit<AIAgentOptions<I, O>, "instructions"> {
-    objective?: string | PromptBuilder | Instructions;
-    planner?: NestAgentSchema | {
-        instructions?: string | PromptBuilder | Instructions;
-    };
-    worker?: NestAgentSchema | {
-        instructions?: string | PromptBuilder | Instructions;
-    };
-    completer?: NestAgentSchema | {
-        instructions?: string | PromptBuilder | Instructions;
-    };
+export interface LoadOrchestratorAgentOptions {
+    objective?: string | Instructions;
+    planner?: NestAgentSchema;
+    worker?: NestAgentSchema;
+    completer?: NestAgentSchema;
     stateManagement?: StateManagementOptions;
 }
 /**
@@ -47,10 +43,13 @@ export interface LoadOrchestratorAgentOptions<I extends Message = Message, O ext
  */
 export declare class OrchestratorAgent<I extends Message = Message, O extends Message = Message> extends AIAgent<I, O> {
     tag: string;
+    static schema<T>({ filepath }: {
+        filepath: string;
+    }): ZodType<T>;
     static load<I extends Message = Message, O extends Message = Message>({ filepath, parsed, options, }: {
         filepath: string;
-        parsed: AgentOptions<I, O> & LoadOrchestratorAgentOptions<I, O>;
-        options?: LoadOptions;
+        parsed: LoadOrchestratorAgentOptions & AgentOptions<I, O>;
+        options?: AgentLoadOptions;
     }): Promise<OrchestratorAgent<I, O>>;
     /**
      * Factory method to create an OrchestratorAgent instance

package/lib/esm/orchestrator/index.js

@@ -1,7 +1,6 @@
 import { AIAgent, } from "@aigne/core";
-import { getInstructionsSchema, getNestAgentSchema, } from "@aigne/core/loader/agent-yaml.js";
-import { instructionsToPromptBuilder, loadNestAgent, } from "@aigne/core/loader/index.js";
-import { camelizeSchema, optionalize } from "@aigne/core/loader/schema.js";
+import { getNestAgentSchema } from "@aigne/core/loader/agent-yaml.js";
+import { camelizeSchema, getInstructionsSchema, instructionsToPromptBuilder, optionalize, } from "@aigne/core/loader/schema.js";
 import { isAgent } from "@aigne/core/utils/agent-utils.js";
 import * as fastq from "@aigne/core/utils/queue.js";
 import { estimateTokens } from "@aigne/core/utils/token-estimator.js";
@@ -54,28 +53,41 @@ const DEFAULT_CONCURRENCY = 5;
  */
 export class OrchestratorAgent extends AIAgent {
     tag = "OrchestratorAgent";
-    static async load({ filepath, parsed, options = {}, }) {
-        const schema = getOrchestratorAgentSchema({ filepath });
-        const valid = await schema.parseAsync(parsed);
+    static schema({ filepath }) {
+        const nestAgentSchema = getNestAgentSchema({ filepath });
+        const instructionsSchema = getInstructionsSchema({ filepath });
+        return camelizeSchema(z.object({
+            objective: optionalize(instructionsSchema),
+            planner: optionalize(nestAgentSchema),
+            worker: optionalize(nestAgentSchema),
+            completer: optionalize(nestAgentSchema),
+            stateManagement: optionalize(camelizeSchema(stateManagementOptionsSchema)),
+            concurrency: optionalize(z.number().int().min(1).default(DEFAULT_CONCURRENCY)),
+        }));
+    }
+    static async load({ filepath, parsed, options, }) {
+        const valid = await OrchestratorAgent.schema({
+            filepath,
+        }).parseAsync(parsed);
         return new OrchestratorAgent({
             ...parsed,
-            objective: valid.objective && instructionsToPromptBuilder(valid.objective),
+            objective: valid.objective ? instructionsToPromptBuilder(valid.objective) : undefined,
             planner: valid.planner
-                ? (await loadNestAgent(filepath, valid.planner, options, {
+                ? (await options?.loadNestAgent(filepath, valid.planner, options, {
                     ...defaultPlannerOptions,
                     afs: parsed.afs,
                     skills: parsed.skills,
                 }))
                 : undefined,
             worker: valid.worker
-                ? (await loadNestAgent(filepath, valid.worker, options, {
+                ? (await options?.loadNestAgent(filepath, valid.worker, options, {
                     ...defaultWorkerOptions,
                     afs: parsed.afs,
                     skills: parsed.skills,
                 }))
                 : undefined,
             completer: valid.completer
-                ? (await loadNestAgent(filepath, valid.completer, options, {
+                ? (await options?.loadNestAgent(filepath, valid.completer, options, {
                     ...defaultCompleterOptions,
                     outputSchema: parsed.outputSchema,
                     afs: parsed.afs,
@@ -235,15 +247,3 @@ export class OrchestratorAgent extends AIAgent {
     }
 }
 export default OrchestratorAgent;
-function getOrchestratorAgentSchema({ filepath }) {
-    const nestAgentSchema = getNestAgentSchema({ filepath });
-    const instructionsSchema = getInstructionsSchema({ filepath });
-    return camelizeSchema(z.object({
-        objective: optionalize(instructionsSchema),
-        planner: optionalize(nestAgentSchema),
-        worker: optionalize(nestAgentSchema),
-        completer: optionalize(nestAgentSchema),
-        stateManagement: optionalize(camelizeSchema(stateManagementOptionsSchema)),
-        concurrency: optionalize(z.number().int().min(1).default(DEFAULT_CONCURRENCY)),
-    }));
-}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aigne/agent-library",
-  "version": "1.24.0-beta.3",
+  "version": "1.24.0-beta.5",
   "description": "Collection of agent libraries for AIGNE framework",
   "publishConfig": {
     "access": "public"
@@ -57,9 +57,9 @@
     "yaml": "^2.8.1",
     "zod": "^3.25.67",
     "zod-to-json-schema": "^3.24.6",
-    "@aigne/core": "^1.72.0-beta.3",
-    "@aigne/sqlite": "^0.4.9-beta",
-    "@aigne/openai": "^0.16.16-beta.3"
+    "@aigne/core": "^1.72.0-beta.5",
+    "@aigne/openai": "^0.16.16-beta.5",
+    "@aigne/sqlite": "^0.4.9-beta"
   },
   "devDependencies": {
     "@types/bun": "^1.2.22",