@aigne/core 1.15.0 → 1.16.0

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

@@ -1,7 +1,14 @@
+import type { Camelize } from "camelize-ts";
 import { z } from "zod";
 import { type Agent } from "../agents/agent.js";
-import type { ChatModel, ChatModelOptions } from "../models/chat-model.js";
+import type { ChatModel, ChatModelOptions } from "../agents/chat-model.js";
 export interface LoadOptions {
+    models: {
+        new (parameters: {
+            model?: string;
+            modelOptions?: ChatModelOptions;
+        }): ChatModel;
+    }[];
     path: string;
 }
 export declare function load(options: LoadOptions): Promise<{
@@ -15,12 +22,12 @@ export declare function load(options: LoadOptions): Promise<{
         temperature?: number | null | undefined;
         provider?: string | null | undefined;
         top_p?: number | null | undefined;
-        frequent_penalty?: number | null | undefined;
+        frequency_penalty?: number | null | undefined;
         presence_penalty?: number | null | undefined;
     } | null | undefined;
 }>;
 export declare function loadAgent(path: string): Promise<Agent>;
-export declare function loadModel(model?: z.infer<typeof aigneFileSchema>["chat_model"], modelOptions?: ChatModelOptions): Promise<ChatModel | undefined>;
+export declare function loadModel(models: LoadOptions["models"], model?: Camelize<z.infer<typeof aigneFileSchema>["chat_model"]>, modelOptions?: ChatModelOptions): Promise<ChatModel | undefined>;
 declare const aigneFileSchema: z.ZodObject<{
     name: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     description: z.ZodOptional<z.ZodNullable<z.ZodString>>;
@@ -29,35 +36,35 @@ declare const aigneFileSchema: z.ZodObject<{
         name: z.ZodOptional<z.ZodNullable<z.ZodString>>;
         temperature: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
         top_p: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
-        frequent_penalty: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        frequency_penalty: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
         presence_penalty: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
     }, "strip", z.ZodTypeAny, {
         name?: string | null | undefined;
         temperature?: number | null | undefined;
         provider?: string | null | undefined;
         top_p?: number | null | undefined;
-        frequent_penalty?: number | null | undefined;
+        frequency_penalty?: number | null | undefined;
         presence_penalty?: number | null | undefined;
     }, {
         name?: string | null | undefined;
         temperature?: number | null | undefined;
         provider?: string | null | undefined;
         top_p?: number | null | undefined;
-        frequent_penalty?: number | null | undefined;
+        frequency_penalty?: number | null | undefined;
         presence_penalty?: number | null | undefined;
     }>]>>>, {
         name?: string | null | undefined;
         temperature?: number | null | undefined;
         provider?: string | null | undefined;
         top_p?: number | null | undefined;
-        frequent_penalty?: number | null | undefined;
+        frequency_penalty?: number | null | undefined;
         presence_penalty?: number | null | undefined;
     } | null | undefined, string | {
         name?: string | null | undefined;
         temperature?: number | null | undefined;
         provider?: string | null | undefined;
         top_p?: number | null | undefined;
-        frequent_penalty?: number | null | undefined;
+        frequency_penalty?: number | null | undefined;
         presence_penalty?: number | null | undefined;
     } | null | undefined>;
     agents: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodString, "many">>>;
@@ -71,7 +78,7 @@ declare const aigneFileSchema: z.ZodObject<{
         temperature?: number | null | undefined;
         provider?: string | null | undefined;
         top_p?: number | null | undefined;
-        frequent_penalty?: number | null | undefined;
+        frequency_penalty?: number | null | undefined;
         presence_penalty?: number | null | undefined;
     } | null | undefined;
     agents?: string[] | null | undefined;
@@ -84,7 +91,7 @@ declare const aigneFileSchema: z.ZodObject<{
         temperature?: number | null | undefined;
         provider?: string | null | undefined;
         top_p?: number | null | undefined;
-        frequent_penalty?: number | null | undefined;
+        frequency_penalty?: number | null | undefined;
         presence_penalty?: number | null | undefined;
     } | null | undefined;
     agents?: string[] | null | undefined;
@@ -98,7 +105,7 @@ export declare function loadAIGNEFile(path: string): Promise<{
         temperature?: number | null | undefined;
         provider?: string | null | undefined;
         top_p?: number | null | undefined;
-        frequent_penalty?: number | null | undefined;
+        frequency_penalty?: number | null | undefined;
         presence_penalty?: number | null | undefined;
     } | null | undefined;
     agents?: string[] | null | undefined;

package/lib/dts/memory/retriever.d.ts

@@ -39,11 +39,11 @@ export declare const memoryRetrieverInputSchema: z.ZodObject<{
     limit: z.ZodOptional<z.ZodNumber>;
     search: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
-    limit?: number | undefined;
     search?: string | undefined;
-}, {
     limit?: number | undefined;
+}, {
     search?: string | undefined;
+    limit?: number | undefined;
 }>;
 /**
  * @hidden

package/lib/dts/prompt/prompt-builder.d.ts

@@ -1,9 +1,9 @@
 import type { GetPromptResult } from "@modelcontextprotocol/sdk/types.js";
 import { Agent, type Message } from "../agents/agent.js";
 import type { AIAgent } from "../agents/ai-agent.js";
+import type { ChatModel, ChatModelInput } from "../agents/chat-model.js";
 import type { Context } from "../aigne/context.js";
 import type { MemoryAgent } from "../memory/memory.js";
-import type { ChatModel, ChatModelInput } from "../models/chat-model.js";
 import { ChatMessagesTemplate } from "./template.js";
 export declare const MESSAGE_KEY = "$message";
 export declare function createMessage<I extends Message>(message: string | I): I;
@@ -11,7 +11,7 @@ export declare function getMessage(input: Message): string | undefined;
 export interface PromptBuilderOptions {
     instructions?: string | ChatMessagesTemplate;
 }
-export interface PromptBuilderBuildOptions {
+export interface PromptBuildOptions {
     memory?: MemoryAgent | MemoryAgent[];
     context: Context;
     agent?: AIAgent;
@@ -32,7 +32,7 @@ export declare class PromptBuilder {
     private static fromMCPPromptResult;
     constructor(options?: PromptBuilderOptions);
     instructions?: string | ChatMessagesTemplate;
-    build(options: PromptBuilderBuildOptions): Promise<ChatModelInput & {
+    build(options: PromptBuildOptions): Promise<ChatModelInput & {
         toolAgents?: Agent[];
     }>;
     private buildMessages;

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

@@ -1,4 +1,4 @@
-import type { ChatModelInputMessage, ChatModelInputMessageContent, ChatModelOutputToolCall } from "../models/chat-model.js";
+import type { ChatModelInputMessage, ChatModelInputMessageContent, ChatModelOutputToolCall } from "../agents/chat-model.js";
 export declare class PromptTemplate {
     template: string;
     static from(template: string): PromptTemplate;
@@ -24,7 +24,7 @@ export declare class AgentMessageTemplate extends ChatMessageTemplate {
     constructor(content?: ChatModelInputMessage["content"], toolCalls?: ChatModelOutputToolCall[] | undefined, name?: string);
     format(variables?: Record<string, unknown>): {
         toolCalls: ChatModelOutputToolCall[] | undefined;
-        role: import("../models/chat-model.js").Role;
+        role: import("../agents/chat-model.js").Role;
         content?: ChatModelInputMessageContent;
         toolCallId?: string;
         name?: string;
@@ -36,7 +36,7 @@ export declare class ToolMessageTemplate extends ChatMessageTemplate {
     constructor(content: object | string, toolCallId: string, name?: string);
     format(variables?: Record<string, unknown>): {
         toolCallId: string;
-        role: import("../models/chat-model.js").Role;
+        role: import("../agents/chat-model.js").Role;
         content?: ChatModelInputMessageContent;
         toolCalls?: {
             id: string;

package/lib/dts/utils/logger.d.ts

@@ -1,8 +1,33 @@
-import debug from "debug";
-export declare const logger: debug.Debug & {
-    debug: debug.Debug;
-    default: debug.Debug;
-} & {
-    core: debug.Debugger;
-    mcp: debug.Debugger;
-};
+export declare enum LogLevel {
+    ERROR = "error",
+    WARN = "warn",
+    INFO = "info",
+    DEBUG = "debug"
+}
+export declare class Logger {
+    constructor(options: {
+        level: LogLevel;
+        ns: string;
+    });
+    level: LogLevel;
+    private debugLogger;
+    private infoLogger;
+    private warnLogger;
+    private errorLogger;
+    logMessage: {
+        (...data: any[]): void;
+        (...data: any[]): void;
+        (message?: any, ...optionalParams: any[]): void;
+    };
+    logError: {
+        (...data: any[]): void;
+        (...data: any[]): void;
+        (message?: any, ...optionalParams: any[]): void;
+    };
+    debug(message: string, ...args: unknown[]): void;
+    info(message: string, ...args: unknown[]): void;
+    warn(message: string, ...args: unknown[]): void;
+    error(message: string, ...args: unknown[]): void;
+    enabled(level: LogLevel): boolean;
+}
+export declare const logger: Logger;

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

@@ -1,3 +1,3 @@
-import type { ChatModelOutputUsage } from "../models/chat-model.js";
+import type { ChatModelOutputUsage } from "../agents/chat-model.js";
 import type { Nullish } from "./type-utils.js";
 export declare function mergeUsage(...usages: Nullish<ChatModelOutputUsage>[]): ChatModelOutputUsage;

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

@@ -6,7 +6,7 @@ export declare function mergeAgentResponseChunk<T extends Message>(output: T, ch
 export declare function agentResponseStreamToObject<T extends Message>(stream: AgentResponseStream<T> | AgentProcessAsyncGenerator<T>): Promise<T>;
 export declare function asyncGeneratorToReadableStream<T extends Message>(generator: AgentProcessAsyncGenerator<T>): AgentResponseStream<T>;
 export declare function onAgentResponseStreamEnd<T extends Message>(stream: AgentResponseStream<T>, callback: (result: T) => PromiseOrValue<Partial<T> | void>, options?: {
-    errorCallback?: (error: Error) => Error;
+    errorCallback?: (error: Error) => PromiseOrValue<Error>;
     processChunk?: (chunk: AgentResponseChunk<T>) => AgentResponseChunk<T>;
 }): ReadableStream<any>;
 export declare function isAsyncGenerator<T extends AsyncGenerator>(value: AsyncGenerator | unknown): value is T;
@@ -19,3 +19,5 @@ export declare function readableStreamToArray<T>(stream: ReadableStream<T>, opti
     catchError?: false;
 }): Promise<T[]>;
 export declare function stringToAgentResponseStream(str: string, key?: "text" | typeof MESSAGE_KEY | string): AgentResponseStream<Message>;
+export declare function toReadableStream(stream: NodeJS.ReadStream): ReadableStream<Uint8Array<ArrayBufferLike>>;
+export declare function readAllString(stream: NodeJS.ReadStream | ReadableStream): Promise<string>;

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

@@ -2,6 +2,11 @@ import { type ZodType } from "zod";
 export type PromiseOrValue<T> = T | Promise<T>;
 export type Nullish<T> = T | null | undefined | void;
 export type OmitPropertiesFromArrayFirstElement<T extends unknown[], K extends string | number | symbol> = T extends [infer U, ...infer Rest] ? [Omit<U, K>, ...Rest] : never;
+export type XOr<T, K extends keyof T, O extends keyof T> = (Omit<T, O> & {
+    [key in O]?: undefined;
+}) | (Omit<T, K> & {
+    [key in K]?: undefined;
+});
 export declare function isNil(value: unknown): value is null | undefined;
 export declare function isRecord<T>(value: unknown): value is Record<string, T>;
 export declare function isEmpty(obj: unknown): boolean;

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

@@ -3,7 +3,8 @@ import { ZodObject, type ZodType } from "zod";
 import type { Context } from "../aigne/context.js";
 import type { MessagePayload } from "../aigne/message-queue.js";
 import type { MemoryAgent } from "../memory/memory.js";
-import { type Nullish, type PromiseOrValue } from "../utils/type-utils.js";
+import { type Nullish, type PromiseOrValue, type XOr } from "../utils/type-utils.js";
+import type { GuideRailAgent, GuideRailAgentOutput } from "./guide-rail-agent.js";
 import { type TransferAgentOutput } from "./types.js";
 export * from "./types.js";
 /**
@@ -29,7 +30,7 @@ export type PublishTopic<O extends Message> = string | string[] | ((output: O) =
  * @template I The agent input message type
  * @template O The agent output message type
  */
-export interface AgentOptions<I extends Message = Message, O extends Message = Message> {
+export interface AgentOptions<I extends Message = Message, O extends Message = Message> extends Partial<Pick<Agent, "guideRails" | "hooks">> {
     /**
      * Topics the agent should subscribe to
      *
@@ -139,6 +140,35 @@ export declare abstract class Agent<I extends Message = Message, O extends Messa
      * List of memories this agent can use
      */
     readonly memories: MemoryAgent[];
+    /**
+     * Lifecycle hooks for agent processing.
+     *
+     * Hooks enable tracing, logging, monitoring, and custom behavior
+     * without modifying the core agent implementation
+     *
+     * @example
+     * Here's an example of using hooks:
+     * {@includeCode ../../test/agents/agent.test.ts#example-agent-hooks}
+     */
+    readonly hooks: AgentHooks;
+    /**
+     * List of GuideRail agents applied to this agent
+     *
+     * GuideRail agents validate, transform, or control the message flow by:
+     * - Enforcing rules and safety policies
+     * - Validating inputs/outputs against specific criteria
+     * - Implementing business logic validations
+     * - Monitoring and auditing agent behavior
+     *
+     * Each GuideRail agent can examine both input and expected output,
+     * and has the ability to abort the process with an explanation
+     *
+     * @example
+     * Here's an example of using GuideRail agents:
+     *
+     * {@includeCode ../../test/agents/agent.test.ts#example-agent-guide-rails}
+     */
+    readonly guideRails?: GuideRailAgent[];
     /**
      * Name of the agent, used for identification and logging
      *
@@ -301,6 +331,7 @@ export declare abstract class Agent<I extends Message = Message, O extends Messa
      * @returns Agent response (streaming or regular)
      */
     invoke(input: I | string, context?: Context, options?: AgentInvokeOptions): Promise<AgentResponse<O>>;
+    protected invokeSkill<I extends Message, O extends Message>(skill: Agent<I, O>, input: I, context: Context): Promise<O>;
     /**
      * Process agent output
      *
@@ -319,7 +350,6 @@ export declare abstract class Agent<I extends Message = Message, O extends Messa
      *
      * @param error Caught error
      * @param context Execution context
-     * @throws Always throws the received error
      */
     private processAgentError;
     /**
@@ -342,7 +372,25 @@ export declare abstract class Agent<I extends Message = Message, O extends Messa
      * @param _ Input message (unused)
      * @param context Execution context
      */
-    protected preprocess(_: I, context: Context): void;
+    protected preprocess(_: I, context: Context): PromiseOrValue<void>;
+    private checkResponseByGuideRails;
+    private runGuideRails;
+    /**
+     * Handle errors detected by GuideRail agents
+     *
+     * This method is called when a GuideRail agent aborts the process, providing
+     * a way for agents to customize error handling behavior. By default, it simply
+     * returns the original error, but subclasses can override this method to:
+     * - Transform the error into a more specific response
+     * - Apply recovery strategies
+     * - Log or report the error in a custom format
+     * - Return a fallback output instead of an error
+     *
+     * @param error The GuideRail agent output containing abort=true and a reason
+     * @returns Either the original/modified error or a substitute output object
+     *          which will be tagged with $status: "GuideRailError"
+     */
+    protected onGuideRailError(error: GuideRailAgentOutput): Promise<O | GuideRailAgentOutput>;
     /**
      * Post-processing operations after handling output
      *
@@ -354,7 +402,7 @@ export declare abstract class Agent<I extends Message = Message, O extends Messa
      * @param output Output message
      * @param context Execution context
      */
-    protected postprocess(input: I, output: O, context: Context): void;
+    protected postprocess(input: I, output: O, context: Context): PromiseOrValue<void>;
     protected publishToTopics(output: Message, context: Context): Promise<void>;
     /**
      * Core processing method of the agent, must be implemented in subclasses
@@ -419,6 +467,81 @@ export declare abstract class Agent<I extends Message = Message, O extends Messa
      */
     [Symbol.asyncDispose](): Promise<void>;
 }
+/**
+ * Lifecycle hooks for agent execution
+ *
+ * Hooks provide a way to intercept and extend agent behavior at key points during
+ * the agent's lifecycle, enabling custom functionality like logging, monitoring,
+ * tracing, error handling, and more.
+ */
+export interface AgentHooks<I extends Message = Message, O extends Message = Message> {
+    /**
+     * Called when agent processing begins
+     *
+     * This hook runs before the agent processes input, allowing for
+     * setup operations, logging, or input transformations.
+     *
+     * @param event Object containing the input message
+     */
+    onStart?: (event: {
+        input: I;
+    }) => PromiseOrValue<void>;
+    /**
+     * Called when agent processing completes or fails
+     *
+     * This hook runs after processing finishes, receiving either the output
+     * or an error if processing failed. Useful for cleanup operations,
+     * logging results, or error handling.
+     *
+     * @param event Object containing the input message and either output or error
+     */
+    onEnd?: (event: XOr<{
+        input: I;
+        output: O;
+        error: Error;
+    }, "output", "error">) => PromiseOrValue<void>;
+    /**
+     * Called before a skill (sub-agent) is invoked
+     *
+     * This hook runs when the agent delegates work to a skill,
+     * allowing for tracking skill usage or transforming input to the skill.
+     *
+     * @param event Object containing the skill being used and input message
+     */
+    onSkillStart?: (event: {
+        skill: Agent;
+        input: I;
+    }) => PromiseOrValue<void>;
+    /**
+     * Called after a skill (sub-agent) completes or fails
+     *
+     * This hook runs when a skill finishes execution, receiving either the output
+     * or an error if the skill failed. Useful for monitoring skill performance
+     * or handling skill-specific errors.
+     *
+     * @param event Object containing the skill used, input message, and either output or error
+     */
+    onSkillEnd?: (event: XOr<{
+        skill: Agent;
+        input: I;
+        output: O;
+        error: Error;
+    }, "output", "error">) => PromiseOrValue<void>;
+    /**
+     * Called when an agent hands off processing to another agent
+     *
+     * This hook runs when a source agent transfers control to a target agent,
+     * allowing for tracking of handoffs between agents and monitoring the flow
+     * of processing in multi-agent systems.
+     *
+     * @param event Object containing the source agent, target agent, and input message
+     */
+    onHandoff?: (event: {
+        source: Agent;
+        target: Agent;
+        input: I;
+    }) => PromiseOrValue<void>;
+}
 /**
  * Response type for an agent, can be:
  * - Direct response object
@@ -427,7 +550,7 @@ export declare abstract class Agent<I extends Message = Message, O extends Messa
  *
  * @template T Response data type
  */
-export type AgentResponse<T> = T | TransferAgentOutput | AgentResponseStream<T>;
+export type AgentResponse<T> = T | AgentResponseStream<T> | TransferAgentOutput | GuideRailAgentOutput;
 /**
  * Streaming response type for an agent
  *

package/lib/esm/agents/agent.js

@@ -19,6 +19,16 @@ export const agentOptionsSchema = z.object({
     skills: z.array(z.union([z.custom(), z.custom()])).optional(),
     disableEvents: z.boolean().optional(),
     memory: z.union([z.custom(), z.array(z.custom())]).optional(),
+    hooks: z
+        .object({
+        onStart: z.custom().optional(),
+        onEnd: z.custom().optional(),
+        onSkillStart: z.custom().optional(),
+        onSkillEnd: z.custom().optional(),
+        onHandoff: z.custom().optional(),
+    })
+        .optional(),
+    guideRails: z.array(z.custom()).optional(),
 });
 /**
  * Agent is the base class for all agents.
@@ -65,11 +75,42 @@ export class Agent {
         else if (options.memory) {
             this.memories.push(options.memory);
         }
+        this.hooks = options.hooks ?? {};
+        this.guideRails = options.guideRails;
     }
     /**
      * List of memories this agent can use
      */
     memories = [];
+    /**
+     * Lifecycle hooks for agent processing.
+     *
+     * Hooks enable tracing, logging, monitoring, and custom behavior
+     * without modifying the core agent implementation
+     *
+     * @example
+     * Here's an example of using hooks:
+     * {@includeCode ../../test/agents/agent.test.ts#example-agent-hooks}
+     */
+    hooks;
+    /**
+     * List of GuideRail agents applied to this agent
+     *
+     * GuideRail agents validate, transform, or control the message flow by:
+     * - Enforcing rules and safety policies
+     * - Validating inputs/outputs against specific criteria
+     * - Implementing business logic validations
+     * - Monitoring and auditing agent behavior
+     *
+     * Each GuideRail agent can examine both input and expected output,
+     * and has the ability to abort the process with an explanation
+     *
+     * @example
+     * Here's an example of using GuideRail agents:
+     *
+     * {@includeCode ../../test/agents/agent.test.ts#example-agent-guide-rails}
+     */
+    guideRails;
     /**
      * Name of the agent, used for identification and logging
      *
@@ -226,12 +267,13 @@ export class Agent {
     async invoke(input, context, options) {
         const ctx = context ?? (await this.newDefaultContext());
         const message = typeof input === "string" ? createMessage(input) : input;
-        logger.core("Invoke agent %s started with input: %O", this.name, input);
+        logger.debug("Invoke agent %s started with input: %O", this.name, input);
         if (!this.disableEvents)
             ctx.emit("agentStarted", { agent: this, input: message });
         try {
+            await this.hooks.onStart?.({ input: message });
             const parsedInput = checkArguments(`Agent ${this.name} input`, this.inputSchema, message);
-            this.preprocess(parsedInput, ctx);
+            await this.preprocess(parsedInput, ctx);
             this.checkContextStatus(ctx);
             let response = await this.process(parsedInput, ctx);
             if (response instanceof Agent) {
@@ -243,27 +285,34 @@ export class Agent {
                     : isAsyncGenerator(response)
                         ? asyncGeneratorToReadableStream(response)
                         : objectToAgentResponseStream(response);
-                return onAgentResponseStreamEnd(stream, async (result) => {
+                return this.checkResponseByGuideRails(message, onAgentResponseStreamEnd(stream, async (result) => {
                     return await this.processAgentOutput(parsedInput, result, ctx);
                 }, {
-                    errorCallback: (error) => {
-                        try {
-                            this.processAgentError(error, ctx);
-                        }
-                        catch (error) {
-                            return error;
-                        }
+                    errorCallback: async (error) => {
+                        return await this.processAgentError(message, error, ctx);
                     },
-                });
+                }), ctx);
             }
-            return await this.processAgentOutput(parsedInput, response instanceof ReadableStream
+            return await this.checkResponseByGuideRails(message, this.processAgentOutput(parsedInput, response instanceof ReadableStream
                 ? await agentResponseStreamToObject(response)
                 : isAsyncGenerator(response)
                     ? await agentResponseStreamToObject(response)
-                    : response, ctx);
+                    : response, ctx), ctx);
         }
         catch (error) {
-            this.processAgentError(error, ctx);
+            throw await this.processAgentError(message, error, ctx);
+        }
+    }
+    async invokeSkill(skill, input, context) {
+        await this.hooks.onSkillStart?.({ skill, input });
+        try {
+            const output = await context.invoke(skill, input);
+            await this.hooks.onSkillEnd?.({ skill, input, output });
+            return output;
+        }
+        catch (error) {
+            await this.hooks.onSkillEnd?.({ skill, input, error });
+            throw error;
         }
     }
     /**
@@ -279,10 +328,11 @@ export class Agent {
     async processAgentOutput(input, output, context) {
         const parsedOutput = checkArguments(`Agent ${this.name} output`, this.outputSchema, output);
         const finalOutput = this.includeInputInOutput ? { ...input, ...parsedOutput } : parsedOutput;
-        this.postprocess(input, finalOutput, context);
-        logger.core("Invoke agent %s succeed with output: %O", this.name, finalOutput);
+        await this.postprocess(input, finalOutput, context);
+        logger.debug("Invoke agent %s succeed with output: %O", this.name, finalOutput);
         if (!this.disableEvents)
             context.emit("agentSucceed", { agent: this, output: finalOutput });
+        await this.hooks.onEnd?.({ input, output: finalOutput });
         return finalOutput;
     }
     /**
@@ -292,13 +342,13 @@ export class Agent {
      *
      * @param error Caught error
      * @param context Execution context
-     * @throws Always throws the received error
      */
-    processAgentError(error, context) {
-        logger.core("Invoke agent %s failed with error: %O", this.name, error);
+    async processAgentError(input, error, context) {
+        logger.error("Invoke agent %s failed with error: %O", this.name, error);
         if (!this.disableEvents)
             context.emit("agentFailed", { agent: this, error });
-        throw error;
+        await this.hooks.onEnd?.({ input, error });
+        return error;
     }
     /**
      * Check agent invocation usage to prevent exceeding limits
@@ -330,6 +380,48 @@ export class Agent {
         this.checkContextStatus(context);
         this.checkAgentInvokesUsage(context);
     }
+    async checkResponseByGuideRails(input, output, context) {
+        if (!this.guideRails?.length)
+            return output;
+        const result = await output;
+        if (result instanceof ReadableStream) {
+            return onAgentResponseStreamEnd(result, async (result) => {
+                const error = await this.runGuideRails(input, result, context);
+                if (error) {
+                    return {
+                        ...(await this.onGuideRailError(error)),
+                        $status: "GuideRailError",
+                    };
+                }
+            });
+        }
+        const error = await this.runGuideRails(input, result, context);
+        if (!error)
+            return output;
+        return { ...(await this.onGuideRailError(error)), $status: "GuideRailError" };
+    }
+    async runGuideRails(input, output, context) {
+        const result = await Promise.all((this.guideRails ?? []).map((i) => context.invoke(i, { input, output })));
+        return result.find((i) => !!i.abort);
+    }
+    /**
+     * Handle errors detected by GuideRail agents
+     *
+     * This method is called when a GuideRail agent aborts the process, providing
+     * a way for agents to customize error handling behavior. By default, it simply
+     * returns the original error, but subclasses can override this method to:
+     * - Transform the error into a more specific response
+     * - Apply recovery strategies
+     * - Log or report the error in a custom format
+     * - Return a fallback output instead of an error
+     *
+     * @param error The GuideRail agent output containing abort=true and a reason
+     * @returns Either the original/modified error or a substitute output object
+     *          which will be tagged with $status: "GuideRailError"
+     */
+    async onGuideRailError(error) {
+        return error;
+    }
     /**
      * Post-processing operations after handling output
      *

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

@@ -1,10 +1,10 @@
 import { type ZodObject, type ZodType, z } from "zod";
 import type { Context } from "../aigne/context.js";
 import { type DefaultMemoryOptions } from "../memory/default-memory.js";
-import { ChatModel } from "../models/chat-model.js";
-import type { ChatModelInput } from "../models/chat-model.js";
 import { PromptBuilder } from "../prompt/prompt-builder.js";
 import { Agent, type AgentOptions, type AgentProcessAsyncGenerator, type Message } from "./agent.js";
+import { ChatModel, type ChatModelInput } from "./chat-model.js";
+import type { GuideRailAgentOutput } from "./guide-rail-agent.js";
 /**
  * Configuration options for an AI Agent
  *
@@ -216,6 +216,7 @@ export declare class AIAgent<I extends Message = Message, O extends Message = Me
      * @protected
      */
     process(input: I, context: Context): AgentProcessAsyncGenerator<O>;
+    protected onGuideRailError(error: GuideRailAgentOutput): Promise<O | GuideRailAgentOutput>;
     /**
      * Process router mode requests
      *