@aigne/core 1.34.0 → 1.37.0

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

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

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

@@ -10,6 +10,7 @@ import { type Nullish, type PromiseOrValue, type XOr } from "../utils/type-utils
 import type { GuideRailAgent, GuideRailAgentOutput } from "./guide-rail-agent.js";
 import { type TransferAgentOutput } from "./types.js";
 export * from "./types.js";
+export declare const DEFAULT_INPUT_ACTION_GET = "$get";
 /**
  * Basic message type that can contain any key-value pairs
  */
@@ -72,6 +73,11 @@ export interface AgentOptions<I extends Message = Message, O extends Message = M
      * Used to validate that input messages conform to the expected format
      */
     inputSchema?: AgentInputOutputSchema<I>;
+    /**
+     * Default input message for the agent, it can be used to provide partial input
+     * or default values for the agent's input schema.
+     */
+    defaultInput?: Agent<I, O>["defaultInput"];
     /**
      * Zod schema defining the output message structure
      *
@@ -106,7 +112,7 @@ export interface AgentOptions<I extends Message = Message, O extends Message = M
      * Maximum number of memory items to retrieve
      */
     maxRetrieveMemoryCount?: number;
-    hooks?: AgentHooks<I, O>;
+    hooks?: AgentHooks<I, O> | AgentHooks<I, O>[];
 }
 export declare const agentOptionsSchema: ZodObject<{
     [key in keyof AgentOptions]: ZodType<AgentOptions[key]>;
@@ -137,6 +143,10 @@ export interface AgentInvokeOptions<U extends UserContext = UserContext> {
      * and returns the final JSON result
      */
     streaming?: boolean;
+    /**
+     * Optional hooks for agent invocation
+     */
+    hooks?: AgentHooks<any, any>;
 }
 /**
  * Agent is the base class for all agents.
@@ -190,7 +200,7 @@ export declare abstract class Agent<I extends Message = any, O extends Message =
      * Here's an example of using hooks:
      * {@includeCode ../../test/agents/agent.test.ts#example-agent-hooks}
      */
-    readonly hooks: AgentHooks<I, O>;
+    readonly hooks: AgentHooks<I, O>[];
     /**
      * List of GuideRail agents applied to this agent
      *
@@ -232,6 +242,11 @@ export declare abstract class Agent<I extends Message = any, O extends Message =
      */
     readonly description?: string;
     private readonly _inputSchema?;
+    defaultInput?: Partial<{
+        [key in keyof I]: {
+            [DEFAULT_INPUT_ACTION_GET]: string;
+        } | I[key];
+    }>;
     private readonly _outputSchema?;
     /**
      * Get the input data schema for this agent
@@ -372,6 +387,8 @@ export declare abstract class Agent<I extends Message = any, O extends Message =
      * @returns Agent response (streaming or regular)
      */
     invoke(input: I & Message, options?: Partial<AgentInvokeOptions>): Promise<AgentResponse<O>>;
+    private callHooks;
+    private mergeDefaultInput;
     protected invokeSkill<I extends Message, O extends Message>(skill: Agent<I, O>, input: I & Message, options: AgentInvokeOptions): Promise<O>;
     /**
      * Process agent output
@@ -517,11 +534,15 @@ export interface AgentHooks<I extends Message = Message, O extends Message = Mes
      *
      * @param event Object containing the input message
      */
-    onStart?: (event: {
+    onStart?: ((event: {
         context: Context;
         input: I;
     }) => PromiseOrValue<void | {
         input?: I;
+    }>) | Agent<{
+        input: I;
+    }, {
+        input?: I;
     }>;
     /**
      * Called when agent processing completes or fails
@@ -532,13 +553,39 @@ export interface AgentHooks<I extends Message = Message, O extends Message = Mes
      *
      * @param event Object containing the input message and either output or error
      */
-    onEnd?: (event: XOr<{
+    onEnd?: ((event: XOr<{
         context: Context;
         input: I;
         output: O;
         error: Error;
     }, "output", "error">) => PromiseOrValue<void | {
         output?: O;
+    }>) | Agent<XOr<{
+        input: I;
+        output: O;
+        error: Error;
+    }, "output", "error">, {
+        output?: O;
+    }>;
+    onSuccess?: ((event: {
+        context: Context;
+        input: I;
+        output: O;
+    }) => PromiseOrValue<void | {
+        output?: O;
+    }>) | Agent<{
+        input: I;
+        output: O;
+    }, {
+        output?: O;
+    }>;
+    onError?: ((event: {
+        context: Context;
+        input: I;
+        error: Error;
+    }) => void) | Agent<{
+        input: I;
+        error: Error;
     }>;
     /**
      * Called before a skill (sub-agent) is invoked
@@ -548,11 +595,14 @@ export interface AgentHooks<I extends Message = Message, O extends Message = Mes
      *
      * @param event Object containing the skill being used and input message
      */
-    onSkillStart?: (event: {
+    onSkillStart?: ((event: {
         context: Context;
         skill: Agent;
         input: Message;
-    }) => PromiseOrValue<void>;
+    }) => PromiseOrValue<void>) | Agent<{
+        skill: Agent;
+        input: Message;
+    }>;
     /**
      * Called after a skill (sub-agent) completes or fails
      *
@@ -562,13 +612,18 @@ export interface AgentHooks<I extends Message = Message, O extends Message = Mes
      *
      * @param event Object containing the skill used, input message, and either output or error
      */
-    onSkillEnd?: (event: XOr<{
+    onSkillEnd?: ((event: XOr<{
         context: Context;
         skill: Agent;
         input: Message;
         output: Message;
         error: Error;
-    }, "output", "error">) => PromiseOrValue<void>;
+    }, "output", "error">) => PromiseOrValue<void>) | Agent<XOr<{
+        skill: Agent;
+        input: Message;
+        output: Message;
+        error: Error;
+    }, "output", "error">>;
     /**
      * Called when an agent hands off processing to another agent
      *
@@ -578,13 +633,19 @@ export interface AgentHooks<I extends Message = Message, O extends Message = Mes
      *
      * @param event Object containing the source agent, target agent, and input message
      */
-    onHandoff?: (event: {
+    onHandoff?: ((event: {
         context: Context;
         source: Agent;
         target: Agent;
         input: I;
-    }) => PromiseOrValue<void>;
+    }) => PromiseOrValue<void>) | Agent<{
+        source: Agent;
+        target: Agent;
+        input: I;
+    }>;
 }
+export type AgentHookInput<H extends keyof AgentHooks, Hook extends AgentHooks[H] = AgentHooks[H]> = Hook extends (input: infer I) => any ? Omit<I, "context"> : never;
+export type AgentHookOutput<H extends keyof AgentHooks, Hook extends AgentHooks[H] = AgentHooks[H]> = Hook extends (...args: any[]) => any ? Exclude<Awaited<ReturnType<Hook>>, void> | undefined : never;
 /**
  * Response type for an agent, can be:
  * - Direct response object

package/lib/dts/agents/team-agent.d.ts

@@ -22,6 +22,73 @@ export declare enum ProcessMode {
      */
     parallel = "parallel"
 }
+export declare const DEFAULT_REFLECTION_MAX_ITERATIONS = 3;
+/**
+ * Configuration for reflection mode processing in TeamAgent.
+ *
+ * Reflection mode enables iterative refinement of agent outputs through a review process.
+ * The team agent will repeatedly process the input and have a reviewer agent evaluate
+ * the output until it meets approval criteria or reaches the maximum iteration limit.
+ *
+ * This is particularly useful for:
+ * - Quality assurance workflows where outputs need validation
+ * - Iterative improvement processes where initial results can be refined
+ * - Self-correcting agent systems that learn from feedback
+ */
+export interface ReflectionMode {
+    /**
+     * The agent responsible for reviewing and providing feedback on the team's output.
+     *
+     * The reviewer agent receives the combined output from the team's processing
+     * and should provide feedback or evaluation that can be used to determine
+     * whether the output meets the required standards.
+     */
+    reviewer: Agent;
+    /**
+     * Function that determines whether the reviewer's output indicates approval.
+     *
+     * This function receives the reviewer agent's output message and should return:
+     * - `true` or truthy value: The output is approved and processing should stop
+     * - `false` or falsy value: The output needs improvement and another iteration should run
+     *
+     * The function can be synchronous or asynchronous, allowing for complex approval logic
+     * including external validation, scoring systems, or human-in-the-loop approval.
+     *
+     * @param output - The message output from the reviewer agent
+     * @returns A boolean or truthy/falsy value indicating approval status
+     */
+    isApproved: (output: Message) => PromiseOrValue<boolean | unknown>;
+    /**
+     * Maximum number of reflection iterations before giving up.
+     *
+     * This prevents infinite loops when the approval criteria cannot be met.
+     * If the maximum iterations are reached without approval, the process will
+     * throw an error indicating the reflection failed to converge.
+     *
+     * @default 3
+     */
+    maxIterations?: number;
+    /**
+     * Controls the behavior when maximum iterations are reached without approval.
+     *
+     * When set to `true`, the TeamAgent will return the last generated output
+     * instead of throwing an error when the maximum number of reflection iterations
+     * is reached without the reviewer's approval.
+     *
+     * When set to `false` or undefined, the TeamAgent will throw an error
+     * indicating that the reflection process failed to converge within the
+     * maximum iteration limit.
+     *
+     * This option is useful for scenarios where:
+     * - You want to get the best available result even if it's not perfect
+     * - The approval criteria might be too strict for the given context
+     * - You prefer graceful degradation over complete failure
+     * - You want to implement custom error handling based on the returned result
+     *
+     * @default false
+     */
+    returnLastOnMaxIterations?: boolean;
+}
 /**
  * Configuration options for creating a TeamAgent.
  *
@@ -33,6 +100,21 @@ export interface TeamAgentOptions<I extends Message, O extends Message> extends
      * @default {ProcessMode.sequential}
      */
     mode?: ProcessMode;
+    /**
+     * Configuration for reflection mode processing.
+     *
+     * When enabled, the TeamAgent will use an iterative refinement process where:
+     * 1. The team processes the input normally
+     * 2. A reviewer agent evaluates the output
+     * 3. If not approved, the process repeats with the previous output as context
+     * 4. This continues until approval or maximum iterations are reached
+     *
+     * This enables self-improving agent workflows that can iteratively refine
+     * their outputs based on feedback from a specialized reviewer agent.
+     *
+     * @see ReflectionMode for detailed configuration options
+     */
+    reflection?: ReflectionMode;
     /**
      * Specifies which input field should be treated as an array for iterative processing.
      *
@@ -116,6 +198,14 @@ export declare class TeamAgent<I extends Message, O extends Message> extends Age
      * This can be either sequential (one after another) or parallel (all at once).
      */
     mode: ProcessMode;
+    /**
+     * The reflection mode configuration with guaranteed maxIterations value.
+     *
+     * This is the internal representation after processing the user-provided
+     * reflection configuration, ensuring that maxIterations always has a value
+     * (defaulting to DEFAULT_REFLECTION_MAX_ITERATIONS if not specified).
+     */
+    reflection?: ReflectionMode & Required<Pick<ReflectionMode, "maxIterations">>;
     /**
      * The input field key to iterate over when processing array inputs.
      *
@@ -148,8 +238,10 @@ export declare class TeamAgent<I extends Message, O extends Message> extends Age
      * @returns A stream of message chunks that collectively form the response
      */
     process(input: I, options: AgentInvokeOptions): PromiseOrValue<AgentProcessResult<O>>;
+    private _processNonReflection;
+    private _processReflection;
     private _processIterator;
-    private _process;
+    private _processNonIterator;
     /**
      * Process input sequentially through each agent in the team.
      *

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

@@ -180,6 +180,7 @@ declare class AIGNEContextShared {
     span?: Span;
     constructor(parent?: (Pick<Context, "model" | "skills" | "limits" | "observer"> & {
         messageQueue?: MessageQueue;
+        events?: Emitter<any>;
     }) | undefined);
     readonly messageQueue: MessageQueue;
     readonly events: Emitter<any>;

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

@@ -1,17 +1,2 @@
-import { type ZodObject, type ZodType, z } from "zod";
-import { Agent, type FunctionAgentFn } from "../agents/agent.js";
-export declare function loadAgentFromJsFile(path: string): Promise<Agent<any, any> | {
-    process: FunctionAgentFn;
-    name: string;
-    description?: string | undefined;
-    inputSchema?: ZodObject<Record<string, ZodType<any, z.ZodTypeDef, any>>, z.UnknownKeysParam, z.ZodTypeAny, {
-        [x: string]: any;
-    }, {
-        [x: string]: any;
-    }> | undefined;
-    outputSchema?: ZodObject<Record<string, ZodType<any, z.ZodTypeDef, any>>, z.UnknownKeysParam, z.ZodTypeAny, {
-        [x: string]: any;
-    }, {
-        [x: string]: any;
-    }> | undefined;
-}>;
+import { Agent } from "../agents/agent.js";
+export declare function loadAgentFromJsFile(path: string): Promise<Agent<any, any> | import("./agent-yaml.js").AgentSchema>;

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

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

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

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

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

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

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

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

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

@@ -10,6 +10,7 @@ import { type Nullish, type PromiseOrValue, type XOr } from "../utils/type-utils
 import type { GuideRailAgent, GuideRailAgentOutput } from "./guide-rail-agent.js";
 import { type TransferAgentOutput } from "./types.js";
 export * from "./types.js";
+export declare const DEFAULT_INPUT_ACTION_GET = "$get";
 /**
  * Basic message type that can contain any key-value pairs
  */
@@ -72,6 +73,11 @@ export interface AgentOptions<I extends Message = Message, O extends Message = M
      * Used to validate that input messages conform to the expected format
      */
     inputSchema?: AgentInputOutputSchema<I>;
+    /**
+     * Default input message for the agent, it can be used to provide partial input
+     * or default values for the agent's input schema.
+     */
+    defaultInput?: Agent<I, O>["defaultInput"];
     /**
      * Zod schema defining the output message structure
      *
@@ -106,7 +112,7 @@ export interface AgentOptions<I extends Message = Message, O extends Message = M
      * Maximum number of memory items to retrieve
      */
     maxRetrieveMemoryCount?: number;
-    hooks?: AgentHooks<I, O>;
+    hooks?: AgentHooks<I, O> | AgentHooks<I, O>[];
 }
 export declare const agentOptionsSchema: ZodObject<{
     [key in keyof AgentOptions]: ZodType<AgentOptions[key]>;
@@ -137,6 +143,10 @@ export interface AgentInvokeOptions<U extends UserContext = UserContext> {
      * and returns the final JSON result
      */
     streaming?: boolean;
+    /**
+     * Optional hooks for agent invocation
+     */
+    hooks?: AgentHooks<any, any>;
 }
 /**
  * Agent is the base class for all agents.
@@ -190,7 +200,7 @@ export declare abstract class Agent<I extends Message = any, O extends Message =
      * Here's an example of using hooks:
      * {@includeCode ../../test/agents/agent.test.ts#example-agent-hooks}
      */
-    readonly hooks: AgentHooks<I, O>;
+    readonly hooks: AgentHooks<I, O>[];
     /**
      * List of GuideRail agents applied to this agent
      *
@@ -232,6 +242,11 @@ export declare abstract class Agent<I extends Message = any, O extends Message =
      */
     readonly description?: string;
     private readonly _inputSchema?;
+    defaultInput?: Partial<{
+        [key in keyof I]: {
+            [DEFAULT_INPUT_ACTION_GET]: string;
+        } | I[key];
+    }>;
     private readonly _outputSchema?;
     /**
      * Get the input data schema for this agent
@@ -372,6 +387,8 @@ export declare abstract class Agent<I extends Message = any, O extends Message =
      * @returns Agent response (streaming or regular)
      */
     invoke(input: I & Message, options?: Partial<AgentInvokeOptions>): Promise<AgentResponse<O>>;
+    private callHooks;
+    private mergeDefaultInput;
     protected invokeSkill<I extends Message, O extends Message>(skill: Agent<I, O>, input: I & Message, options: AgentInvokeOptions): Promise<O>;
     /**
      * Process agent output
@@ -517,11 +534,15 @@ export interface AgentHooks<I extends Message = Message, O extends Message = Mes
      *
      * @param event Object containing the input message
      */
-    onStart?: (event: {
+    onStart?: ((event: {
         context: Context;
         input: I;
     }) => PromiseOrValue<void | {
         input?: I;
+    }>) | Agent<{
+        input: I;
+    }, {
+        input?: I;
     }>;
     /**
      * Called when agent processing completes or fails
@@ -532,13 +553,39 @@ export interface AgentHooks<I extends Message = Message, O extends Message = Mes
      *
      * @param event Object containing the input message and either output or error
      */
-    onEnd?: (event: XOr<{
+    onEnd?: ((event: XOr<{
         context: Context;
         input: I;
         output: O;
         error: Error;
     }, "output", "error">) => PromiseOrValue<void | {
         output?: O;
+    }>) | Agent<XOr<{
+        input: I;
+        output: O;
+        error: Error;
+    }, "output", "error">, {
+        output?: O;
+    }>;
+    onSuccess?: ((event: {
+        context: Context;
+        input: I;
+        output: O;
+    }) => PromiseOrValue<void | {
+        output?: O;
+    }>) | Agent<{
+        input: I;
+        output: O;
+    }, {
+        output?: O;
+    }>;
+    onError?: ((event: {
+        context: Context;
+        input: I;
+        error: Error;
+    }) => void) | Agent<{
+        input: I;
+        error: Error;
     }>;
     /**
      * Called before a skill (sub-agent) is invoked
@@ -548,11 +595,14 @@ export interface AgentHooks<I extends Message = Message, O extends Message = Mes
      *
      * @param event Object containing the skill being used and input message
      */
-    onSkillStart?: (event: {
+    onSkillStart?: ((event: {
         context: Context;
         skill: Agent;
         input: Message;
-    }) => PromiseOrValue<void>;
+    }) => PromiseOrValue<void>) | Agent<{
+        skill: Agent;
+        input: Message;
+    }>;
     /**
      * Called after a skill (sub-agent) completes or fails
      *
@@ -562,13 +612,18 @@ export interface AgentHooks<I extends Message = Message, O extends Message = Mes
      *
      * @param event Object containing the skill used, input message, and either output or error
      */
-    onSkillEnd?: (event: XOr<{
+    onSkillEnd?: ((event: XOr<{
         context: Context;
         skill: Agent;
         input: Message;
         output: Message;
         error: Error;
-    }, "output", "error">) => PromiseOrValue<void>;
+    }, "output", "error">) => PromiseOrValue<void>) | Agent<XOr<{
+        skill: Agent;
+        input: Message;
+        output: Message;
+        error: Error;
+    }, "output", "error">>;
     /**
      * Called when an agent hands off processing to another agent
      *
@@ -578,13 +633,19 @@ export interface AgentHooks<I extends Message = Message, O extends Message = Mes
      *
      * @param event Object containing the source agent, target agent, and input message
      */
-    onHandoff?: (event: {
+    onHandoff?: ((event: {
         context: Context;
         source: Agent;
         target: Agent;
         input: I;
-    }) => PromiseOrValue<void>;
+    }) => PromiseOrValue<void>) | Agent<{
+        source: Agent;
+        target: Agent;
+        input: I;
+    }>;
 }
+export type AgentHookInput<H extends keyof AgentHooks, Hook extends AgentHooks[H] = AgentHooks[H]> = Hook extends (input: infer I) => any ? Omit<I, "context"> : never;
+export type AgentHookOutput<H extends keyof AgentHooks, Hook extends AgentHooks[H] = AgentHooks[H]> = Hook extends (...args: any[]) => any ? Exclude<Awaited<ReturnType<Hook>>, void> | undefined : never;
 /**
  * Response type for an agent, can be:
  * - Direct response object