@aigne/agent-library 1.22.4-beta → 1.23.0-beta

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

@@ -1,50 +1,33 @@
-import { Agent, type AgentInvokeOptions, type AgentOptions, type Message } from "@aigne/core";
-import { type FullPlanOutput, type StepWithResult } from "./orchestrator-prompts.js";
-/**
- * Re-export orchestrator prompt templates and related types
- */
-export * from "./orchestrator-prompts.js";
-/**
- * Represents a complete plan with execution results
- * @hidden
- */
-export interface FullPlanWithResult {
-    /**
-     * The overall objective
-     */
-    objective: string;
-    /**
-     * The generated complete plan
-     */
-    plan?: FullPlanOutput;
-    /**
-     * List of executed steps with their results
-     */
-    steps: StepWithResult[];
-    /**
-     * Final result
-     */
-    result?: string;
-    /**
-     * Plan completion status
-     */
-    status?: boolean;
-}
+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 StateManagementOptions } from "./type.js";
 /**
  * Configuration options for the Orchestrator Agent
  */
-export interface OrchestratorAgentOptions<I extends Message = Message, O extends Message = Message> extends AgentOptions<I, O> {
-    /**
-     * Maximum number of iterations to prevent infinite loops
-     * Default: 30
-     */
-    maxIterations?: number;
+export interface OrchestratorAgentOptions<I extends Message = Message, O extends Message = Message> extends Omit<AIAgentOptions<I, O>, "instructions"> {
+    objective: PromptBuilder;
+    planner?: OrchestratorAgent<I, O>["planner"];
+    worker?: OrchestratorAgent<I, O>["worker"];
+    completer?: OrchestratorAgent<I, O>["completer"];
     /**
-     * Number of concurrent tasks
-     * Default: 5
+     * Configuration for managing execution state
+     * Prevents context overflow during long-running executions
      */
-    tasksConcurrency?: number;
-    inputKey: string;
+    stateManagement?: StateManagementOptions;
+}
+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;
+    };
+    stateManagement?: StateManagementOptions;
 }
 /**
  * Orchestrator Agent Class
@@ -61,8 +44,13 @@ export interface OrchestratorAgentOptions<I extends Message = Message, O extends
  * - Executes tasks and steps according to the plan
  * - Synthesizes final result through completer
  */
-export declare class OrchestratorAgent<I extends Message = Message, O extends Message = Message> extends Agent<I, O> {
+export declare class OrchestratorAgent<I extends Message = Message, O extends Message = Message> extends AIAgent<I, O> {
     tag: string;
+    static load<I extends Message = Message, O extends Message = Message>({ filepath, parsed, options, }: {
+        filepath: string;
+        parsed: AgentOptions<I, O> & LoadOrchestratorAgentOptions<I, O>;
+        options?: LoadOptions;
+    }): Promise<OrchestratorAgent<I, O>>;
     /**
      * Factory method to create an OrchestratorAgent instance
      * @param options - Configuration options for the Orchestrator Agent
@@ -74,36 +62,16 @@ export declare class OrchestratorAgent<I extends Message = Message, O extends Me
      * @param options - Configuration options for the Orchestrator Agent
      */
     constructor(options: OrchestratorAgentOptions<I, O>);
+    private objective;
     private planner;
+    private worker;
     private completer;
-    inputKey: string;
-    /**
-     * Maximum number of iterations
-     * Prevents infinite execution loops
-     */
-    maxIterations?: number;
-    /**
-     * Number of concurrent tasks
-     * Controls how many tasks can be executed simultaneously
-     */
-    tasksConcurrency?: number;
+    private stateManagement?;
     /**
-     * Process input and execute the orchestrator workflow
-     *
-     * Workflow:
-     * 1. Extract the objective
-     * 2. Loop until plan completion or maximum iterations:
-     *    a. Generate/update execution plan
-     *    b. If plan is complete, synthesize result
-     *    c. Otherwise, execute steps in the plan
-     *
-     * @param input - Input message containing the objective
-     * @param options - Agent invocation options
-     * @returns Processing result
+     * Compress execution state to prevent context overflow
+     * Uses reverse accumulation to efficiently find optimal task count
      */
-    process(input: I, options: AgentInvokeOptions): Promise<O>;
-    private getFullPlanInput;
-    private getFullPlan;
-    private synthesizePlanResult;
-    private executeStep;
+    private compressState;
+    process(input: I, options: AgentInvokeOptions): AsyncGenerator<import("@aigne/core").AgentResponseChunk<O>, void, unknown>;
 }
+export default OrchestratorAgent;

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

@@ -0,0 +1,3 @@
+export declare const ORCHESTRATOR_COMPLETE_PROMPT = "You are an intelligent assistant that synthesizes and presents the results of completed tasks.\n\n## User Objective\n{{ objective }}\n\n## Execution Results\n{{ executionState | yaml.stringify }}\n\n## Your Task\nBased on the execution results above, provide a comprehensive and helpful response to the user's objective.\n";
+export declare const TODO_PLANNER_PROMPT_TEMPLATE = "You are an intelligent task planner that determines what needs to be done next to achieve the user's objective.\n\n## Your Role\nContinuously evaluate progress and decide the next task to execute. You work iteratively - planning one task at a time based on the current state and previous results.\n\n## Available Skills\n{{ skills | yaml.stringify }}\n\n## User Objective\n{{ objective }}\n\n## Current State\n{{ executionState | yaml.stringify }}\n\n## Understanding Task Status\nEach task in the execution state has a status:\n- **completed**: Task finished successfully, result is available\n- **failed**: Task encountered an error, check error field for details\n- **pending**: Task has not been executed yet\n\n## Your Task\nBased on the objective, current state, and any previous results, determine what should happen next:\n\n1. **If the objective is achieved or all work is complete:** Set finished: true and leave nextTask empty\n2. **If a previous task failed:** Decide whether to retry, skip, or use an alternative approach\n3. **If more work is needed:** Provide a clear, actionable nextTask description\n\n### Guidelines:\n- Focus on the immediate next step, not the entire plan\n- Review task history to avoid repeating work and build on previous results\n- Pay attention to task status - handle failures appropriately\n- Write self-contained task descriptions that the worker can execute independently\n- Set finished: true when the objective is satisfied\n- Consider retrying failed tasks with different approaches if appropriate\n";
+export declare const TODO_WORKER_PROMPT_TEMPLATE = "You are a task execution agent. Your job is to execute the specific task assigned to you - nothing more, nothing less.\n\n## Overall Objective (For Context Only)\n{{ objective }}\n\n**CRITICAL CONSTRAINT**: The objective above is provided ONLY for context. You must NOT attempt to:\n- Solve the entire objective\n- Plan additional steps beyond your current task\n- Make decisions about what should happen next\n- Execute any tasks other than the one explicitly assigned to you below\n\nYour SOLE responsibility is to execute the specific task described below and return the result.\n\n## Current Execution State\n{{ executionState | yaml.stringify }}\n\n## Your Current Task\n{{ task }}\n\n## Important Instructions\n- Focus EXCLUSIVELY on completing the current task described above\n- The task is self-contained - execute it completely and accurately\n- Do NOT perform additional tasks beyond what is specified\n- Do NOT try to determine what should happen after this task\n- Use the available tools and skills to accomplish this specific task\n- Return a clear result that the planner can use to decide the next step\n\n## Output Format\nReturn your task execution result as a structured response. The output schema will guide you on the required fields.\n";

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

@@ -0,0 +1,505 @@
+import type { Message } from "@aigne/core";
+import z from "zod";
+/**
+ * Task execution status
+ */
+export type TaskStatus = "pending" | "completed" | "failed";
+/**
+ * Individual task execution record
+ */
+export interface TaskRecord {
+    /** Task description */
+    task: string;
+    /** Task execution status */
+    status: TaskStatus;
+    /** Task execution result (can be any type) */
+    result?: unknown;
+    /** Error information if task failed */
+    error?: {
+        message: string;
+    };
+    /** Timestamp when task was created */
+    createdAt?: number;
+    /** Timestamp when task was completed or failed */
+    completedAt?: number;
+}
+/**
+ * Execution state tracking all tasks
+ */
+export interface ExecutionState {
+    tasks: TaskRecord[];
+}
+export declare const taskRecordSchema: z.ZodObject<{
+    task: z.ZodString;
+    status: z.ZodEnum<["pending", "completed", "failed"]>;
+    result: z.ZodOptional<z.ZodUnknown>;
+    error: z.ZodOptional<z.ZodObject<{
+        message: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        message: string;
+    }, {
+        message: string;
+    }>>;
+    createdAt: z.ZodOptional<z.ZodNumber>;
+    completedAt: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    status: "pending" | "completed" | "failed";
+    task: string;
+    error?: {
+        message: string;
+    } | undefined;
+    result?: unknown;
+    createdAt?: number | undefined;
+    completedAt?: number | undefined;
+}, {
+    status: "pending" | "completed" | "failed";
+    task: string;
+    error?: {
+        message: string;
+    } | undefined;
+    result?: unknown;
+    createdAt?: number | undefined;
+    completedAt?: number | undefined;
+}>;
+export declare const executionStateSchema: z.ZodObject<{
+    tasks: z.ZodArray<z.ZodObject<{
+        task: z.ZodString;
+        status: z.ZodEnum<["pending", "completed", "failed"]>;
+        result: z.ZodOptional<z.ZodUnknown>;
+        error: z.ZodOptional<z.ZodObject<{
+            message: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            message: string;
+        }, {
+            message: string;
+        }>>;
+        createdAt: z.ZodOptional<z.ZodNumber>;
+        completedAt: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        status: "pending" | "completed" | "failed";
+        task: string;
+        error?: {
+            message: string;
+        } | undefined;
+        result?: unknown;
+        createdAt?: number | undefined;
+        completedAt?: number | undefined;
+    }, {
+        status: "pending" | "completed" | "failed";
+        task: string;
+        error?: {
+            message: string;
+        } | undefined;
+        result?: unknown;
+        createdAt?: number | undefined;
+        completedAt?: number | undefined;
+    }>, "many">;
+}, "strip", z.ZodTypeAny, {
+    tasks: {
+        status: "pending" | "completed" | "failed";
+        task: string;
+        error?: {
+            message: string;
+        } | undefined;
+        result?: unknown;
+        createdAt?: number | undefined;
+        completedAt?: number | undefined;
+    }[];
+}, {
+    tasks: {
+        status: "pending" | "completed" | "failed";
+        task: string;
+        error?: {
+            message: string;
+        } | undefined;
+        result?: unknown;
+        createdAt?: number | undefined;
+        completedAt?: number | undefined;
+    }[];
+}>;
+export interface PlannerInput extends Message {
+    objective: string;
+    skills: {
+        name: string;
+        description?: string;
+    }[];
+    executionState: ExecutionState;
+}
+export declare const plannerInputSchema: z.ZodObject<{
+    objective: z.ZodString;
+    skills: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        name: string;
+        description?: string | undefined;
+    }, {
+        name: string;
+        description?: string | undefined;
+    }>, "many">;
+    executionState: z.ZodObject<{
+        tasks: z.ZodArray<z.ZodObject<{
+            task: z.ZodString;
+            status: z.ZodEnum<["pending", "completed", "failed"]>;
+            result: z.ZodOptional<z.ZodUnknown>;
+            error: z.ZodOptional<z.ZodObject<{
+                message: z.ZodString;
+            }, "strip", z.ZodTypeAny, {
+                message: string;
+            }, {
+                message: string;
+            }>>;
+            createdAt: z.ZodOptional<z.ZodNumber>;
+            completedAt: z.ZodOptional<z.ZodNumber>;
+        }, "strip", z.ZodTypeAny, {
+            status: "pending" | "completed" | "failed";
+            task: string;
+            error?: {
+                message: string;
+            } | undefined;
+            result?: unknown;
+            createdAt?: number | undefined;
+            completedAt?: number | undefined;
+        }, {
+            status: "pending" | "completed" | "failed";
+            task: string;
+            error?: {
+                message: string;
+            } | undefined;
+            result?: unknown;
+            createdAt?: number | undefined;
+            completedAt?: number | undefined;
+        }>, "many">;
+    }, "strip", z.ZodTypeAny, {
+        tasks: {
+            status: "pending" | "completed" | "failed";
+            task: string;
+            error?: {
+                message: string;
+            } | undefined;
+            result?: unknown;
+            createdAt?: number | undefined;
+            completedAt?: number | undefined;
+        }[];
+    }, {
+        tasks: {
+            status: "pending" | "completed" | "failed";
+            task: string;
+            error?: {
+                message: string;
+            } | undefined;
+            result?: unknown;
+            createdAt?: number | undefined;
+            completedAt?: number | undefined;
+        }[];
+    }>;
+}, "strip", z.ZodTypeAny, {
+    skills: {
+        name: string;
+        description?: string | undefined;
+    }[];
+    objective: string;
+    executionState: {
+        tasks: {
+            status: "pending" | "completed" | "failed";
+            task: string;
+            error?: {
+                message: string;
+            } | undefined;
+            result?: unknown;
+            createdAt?: number | undefined;
+            completedAt?: number | undefined;
+        }[];
+    };
+}, {
+    skills: {
+        name: string;
+        description?: string | undefined;
+    }[];
+    objective: string;
+    executionState: {
+        tasks: {
+            status: "pending" | "completed" | "failed";
+            task: string;
+            error?: {
+                message: string;
+            } | undefined;
+            result?: unknown;
+            createdAt?: number | undefined;
+            completedAt?: number | undefined;
+        }[];
+    };
+}>;
+export interface PlannerOutput extends Message {
+    nextTask?: string;
+    finished?: boolean;
+}
+export declare const plannerOutputSchema: z.ZodObject<{
+    nextTask: z.ZodOptional<z.ZodString>;
+    finished: z.ZodOptional<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    nextTask?: string | undefined;
+    finished?: boolean | undefined;
+}, {
+    nextTask?: string | undefined;
+    finished?: boolean | undefined;
+}>;
+export interface WorkerInput extends Message {
+    objective: string;
+    executionState: ExecutionState;
+    task: string;
+}
+export declare const workerInputSchema: z.ZodObject<{
+    objective: z.ZodString;
+    task: z.ZodString;
+    executionState: z.ZodObject<{
+        tasks: z.ZodArray<z.ZodObject<{
+            task: z.ZodString;
+            status: z.ZodEnum<["pending", "completed", "failed"]>;
+            result: z.ZodOptional<z.ZodUnknown>;
+            error: z.ZodOptional<z.ZodObject<{
+                message: z.ZodString;
+            }, "strip", z.ZodTypeAny, {
+                message: string;
+            }, {
+                message: string;
+            }>>;
+            createdAt: z.ZodOptional<z.ZodNumber>;
+            completedAt: z.ZodOptional<z.ZodNumber>;
+        }, "strip", z.ZodTypeAny, {
+            status: "pending" | "completed" | "failed";
+            task: string;
+            error?: {
+                message: string;
+            } | undefined;
+            result?: unknown;
+            createdAt?: number | undefined;
+            completedAt?: number | undefined;
+        }, {
+            status: "pending" | "completed" | "failed";
+            task: string;
+            error?: {
+                message: string;
+            } | undefined;
+            result?: unknown;
+            createdAt?: number | undefined;
+            completedAt?: number | undefined;
+        }>, "many">;
+    }, "strip", z.ZodTypeAny, {
+        tasks: {
+            status: "pending" | "completed" | "failed";
+            task: string;
+            error?: {
+                message: string;
+            } | undefined;
+            result?: unknown;
+            createdAt?: number | undefined;
+            completedAt?: number | undefined;
+        }[];
+    }, {
+        tasks: {
+            status: "pending" | "completed" | "failed";
+            task: string;
+            error?: {
+                message: string;
+            } | undefined;
+            result?: unknown;
+            createdAt?: number | undefined;
+            completedAt?: number | undefined;
+        }[];
+    }>;
+}, "strip", z.ZodTypeAny, {
+    task: string;
+    objective: string;
+    executionState: {
+        tasks: {
+            status: "pending" | "completed" | "failed";
+            task: string;
+            error?: {
+                message: string;
+            } | undefined;
+            result?: unknown;
+            createdAt?: number | undefined;
+            completedAt?: number | undefined;
+        }[];
+    };
+}, {
+    task: string;
+    objective: string;
+    executionState: {
+        tasks: {
+            status: "pending" | "completed" | "failed";
+            task: string;
+            error?: {
+                message: string;
+            } | undefined;
+            result?: unknown;
+            createdAt?: number | undefined;
+            completedAt?: number | undefined;
+        }[];
+    };
+}>;
+/**
+ * Worker output structure
+ */
+export interface WorkerOutput extends Message {
+    /** Task execution result */
+    result?: string;
+    /** Whether the task was completed successfully */
+    success: boolean;
+    /** Error information if task failed */
+    error?: {
+        message: string;
+    };
+}
+export declare const workerOutputSchema: z.ZodObject<{
+    result: z.ZodOptional<z.ZodString>;
+    success: z.ZodBoolean;
+    error: z.ZodOptional<z.ZodObject<{
+        message: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        message: string;
+    }, {
+        message: string;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    success: boolean;
+    error?: {
+        message: string;
+    } | undefined;
+    result?: string | undefined;
+}, {
+    success: boolean;
+    error?: {
+        message: string;
+    } | undefined;
+    result?: string | undefined;
+}>;
+export interface CompleterInput extends Message {
+    objective: string;
+    executionState: ExecutionState;
+}
+export declare const completerInputSchema: z.ZodObject<{
+    objective: z.ZodString;
+    executionState: z.ZodObject<{
+        tasks: z.ZodArray<z.ZodObject<{
+            task: z.ZodString;
+            status: z.ZodEnum<["pending", "completed", "failed"]>;
+            result: z.ZodOptional<z.ZodUnknown>;
+            error: z.ZodOptional<z.ZodObject<{
+                message: z.ZodString;
+            }, "strip", z.ZodTypeAny, {
+                message: string;
+            }, {
+                message: string;
+            }>>;
+            createdAt: z.ZodOptional<z.ZodNumber>;
+            completedAt: z.ZodOptional<z.ZodNumber>;
+        }, "strip", z.ZodTypeAny, {
+            status: "pending" | "completed" | "failed";
+            task: string;
+            error?: {
+                message: string;
+            } | undefined;
+            result?: unknown;
+            createdAt?: number | undefined;
+            completedAt?: number | undefined;
+        }, {
+            status: "pending" | "completed" | "failed";
+            task: string;
+            error?: {
+                message: string;
+            } | undefined;
+            result?: unknown;
+            createdAt?: number | undefined;
+            completedAt?: number | undefined;
+        }>, "many">;
+    }, "strip", z.ZodTypeAny, {
+        tasks: {
+            status: "pending" | "completed" | "failed";
+            task: string;
+            error?: {
+                message: string;
+            } | undefined;
+            result?: unknown;
+            createdAt?: number | undefined;
+            completedAt?: number | undefined;
+        }[];
+    }, {
+        tasks: {
+            status: "pending" | "completed" | "failed";
+            task: string;
+            error?: {
+                message: string;
+            } | undefined;
+            result?: unknown;
+            createdAt?: number | undefined;
+            completedAt?: number | undefined;
+        }[];
+    }>;
+}, "strip", z.ZodTypeAny, {
+    objective: string;
+    executionState: {
+        tasks: {
+            status: "pending" | "completed" | "failed";
+            task: string;
+            error?: {
+                message: string;
+            } | undefined;
+            result?: unknown;
+            createdAt?: number | undefined;
+            completedAt?: number | undefined;
+        }[];
+    };
+}, {
+    objective: string;
+    executionState: {
+        tasks: {
+            status: "pending" | "completed" | "failed";
+            task: string;
+            error?: {
+                message: string;
+            } | undefined;
+            result?: unknown;
+            createdAt?: number | undefined;
+            completedAt?: number | undefined;
+        }[];
+    };
+}>;
+/**
+ * Default maximum number of task execution iterations
+ */
+export declare const DEFAULT_MAX_ITERATIONS = 20;
+/**
+ * Options for managing execution state to prevent context overflow
+ */
+export interface StateManagementOptions {
+    /**
+     * Maximum tokens allowed for execution state
+     * When exceeded, triggers compression
+     */
+    maxTokens?: number;
+    /**
+     * Number of recent tasks to keep when compression is triggered
+     */
+    keepRecent?: number;
+    /**
+     * Maximum number of task execution iterations
+     * When reached, orchestrator will stop and synthesize final result
+     * @default 20
+     */
+    maxIterations?: number;
+}
+export declare const stateManagementOptionsSchema: z.ZodObject<{
+    maxTokens: z.ZodType<number | undefined, z.ZodTypeDef, number | undefined>;
+    keepRecent: z.ZodType<number | undefined, z.ZodTypeDef, number | undefined>;
+    maxIterations: z.ZodType<number | undefined, z.ZodTypeDef, number | undefined>;
+}, "strip", z.ZodTypeAny, {
+    maxTokens?: number | undefined;
+    keepRecent?: number | undefined;
+    maxIterations?: number | undefined;
+}, {
+    maxTokens?: number | undefined;
+    keepRecent?: number | undefined;
+    maxIterations?: number | undefined;
+}>;