@aigne/core 1.15.0 → 1.17.0

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
      *
@@ -209,61 +250,71 @@ export class Agent {
     /**
      * Check context status to ensure it hasn't timed out
      *
-     * @param context The context to check
+     * @param options Invocation options containing context
      * @throws Error if the context has timed out
      */
-    checkContextStatus(context) {
-        if (context) {
-            const { status } = context;
-            if (status === "timeout") {
-                throw new Error(`AIGNE for agent ${this.name} has timed out`);
-            }
+    checkContextStatus(options) {
+        const { status } = options.context;
+        if (status === "timeout") {
+            throw new Error(`AIGNE for agent ${this.name} has timed out`);
         }
     }
     async newDefaultContext() {
         return import("../aigne/context.js").then((m) => new m.AIGNEContext());
     }
-    async invoke(input, context, options) {
-        const ctx = context ?? (await this.newDefaultContext());
+    async invoke(input, options = {}) {
+        const opts = {
+            ...options,
+            context: options.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 });
+            opts.context.emit("agentStarted", { agent: this, input: message });
         try {
+            await this.hooks.onStart?.({ context: opts.context, input: message });
             const parsedInput = checkArguments(`Agent ${this.name} input`, this.inputSchema, message);
-            this.preprocess(parsedInput, ctx);
-            this.checkContextStatus(ctx);
-            let response = await this.process(parsedInput, ctx);
+            await this.preprocess(parsedInput, opts);
+            this.checkContextStatus(opts);
+            let response = await this.process(parsedInput, opts);
             if (response instanceof Agent) {
                 response = transferToAgentOutput(response);
             }
-            if (options?.streaming) {
+            if (opts.streaming) {
                 const stream = response instanceof ReadableStream
                     ? response
                     : isAsyncGenerator(response)
                         ? asyncGeneratorToReadableStream(response)
                         : objectToAgentResponseStream(response);
-                return onAgentResponseStreamEnd(stream, async (result) => {
-                    return await this.processAgentOutput(parsedInput, result, ctx);
+                return this.checkResponseByGuideRails(message, onAgentResponseStreamEnd(stream, async (result) => {
+                    return await this.processAgentOutput(parsedInput, result, opts);
                 }, {
-                    errorCallback: (error) => {
-                        try {
-                            this.processAgentError(error, ctx);
-                        }
-                        catch (error) {
-                            return error;
-                        }
+                    errorCallback: async (error) => {
+                        return await this.processAgentError(message, error, opts);
                     },
-                });
+                }), opts);
             }
-            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, opts), opts);
         }
         catch (error) {
-            this.processAgentError(error, ctx);
+            throw await this.processAgentError(message, error, opts);
+        }
+    }
+    async invokeSkill(skill, input, options) {
+        const { context } = options;
+        await this.hooks.onSkillStart?.({ context, skill, input });
+        try {
+            const output = await context.invoke(skill, input);
+            await this.hooks.onSkillEnd?.({ context, skill, input, output });
+            return output;
+        }
+        catch (error) {
+            await this.hooks.onSkillEnd?.({ context, skill, input, error });
+            throw error;
         }
     }
     /**
@@ -273,16 +324,18 @@ export class Agent {
      *
      * @param input Original input message
      * @param output Raw output produced by the agent
-     * @param context Execution context
+     * @param options Invocation options
      * @returns Final processed output
      */
-    async processAgentOutput(input, output, context) {
+    async processAgentOutput(input, output, options) {
+        const { context } = options;
         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, options);
+        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?.({ context, input, output: finalOutput });
         return finalOutput;
     }
     /**
@@ -291,14 +344,15 @@ export class Agent {
      * Logs error information, triggers failure events, and re-throws the error
      *
      * @param error Caught error
-     * @param context Execution context
-     * @throws Always throws the received error
+     * @param options Invocation options
      */
-    processAgentError(error, context) {
-        logger.core("Invoke agent %s failed with error: %O", this.name, error);
+    async processAgentError(input, error, options) {
+        logger.error("Invoke agent %s failed with error: %O", this.name, error);
         if (!this.disableEvents)
-            context.emit("agentFailed", { agent: this, error });
-        throw error;
+            options.context.emit("agentFailed", { agent: this, error });
+        const { context } = options;
+        await this.hooks.onEnd?.({ context, input, error });
+        return error;
     }
     /**
      * Check agent invocation usage to prevent exceeding limits
@@ -306,11 +360,11 @@ export class Agent {
      * If the context has a maximum invocation limit set, checks if the limit
      * has been exceeded and increments the invocation counter
      *
-     * @param context Execution context
+     * @param options Invocation options containing context and limits
      * @throws Error if maximum invocation limit is exceeded
      */
-    checkAgentInvokesUsage(context) {
-        const { limits, usage } = context;
+    checkAgentInvokesUsage(options) {
+        const { limits, usage } = options.context;
         if (limits?.maxAgentInvokes && usage.agentCalls >= limits.maxAgentInvokes) {
             throw new Error(`Exceeded max agent invokes ${usage.agentCalls}/${limits.maxAgentInvokes}`);
         }
@@ -324,11 +378,53 @@ export class Agent {
      * - Verifying invocation limits
      *
      * @param _ Input message (unused)
-     * @param context Execution context
+     * @param options Options for agent invocation
+     */
+    async preprocess(_, options) {
+        this.checkContextStatus(options);
+        this.checkAgentInvokesUsage(options);
+    }
+    async checkResponseByGuideRails(input, output, options) {
+        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, options);
+                if (error) {
+                    return {
+                        ...(await this.onGuideRailError(error)),
+                        $status: "GuideRailError",
+                    };
+                }
+            });
+        }
+        const error = await this.runGuideRails(input, result, options);
+        if (!error)
+            return output;
+        return { ...(await this.onGuideRailError(error)), $status: "GuideRailError" };
+    }
+    async runGuideRails(input, output, options) {
+        const result = await Promise.all((this.guideRails ?? []).map((i) => options.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"
      */
-    preprocess(_, context) {
-        this.checkContextStatus(context);
-        this.checkAgentInvokesUsage(context);
+    async onGuideRailError(error) {
+        return error;
     }
     /**
      * Post-processing operations after handling output
@@ -339,26 +435,26 @@ export class Agent {
      *
      * @param input Input message
      * @param output Output message
-     * @param context Execution context
+     * @param options Options for agent invocation
      */
-    postprocess(input, output, context) {
-        this.checkContextStatus(context);
-        this.publishToTopics(output, context);
+    async postprocess(input, output, options) {
+        this.checkContextStatus(options);
+        this.publishToTopics(output, options);
         for (const memory of this.memories) {
             if (memory.autoUpdate) {
-                memory.record({
+                await memory.record({
                     content: [
                         { role: "user", content: input },
                         { role: "agent", content: replaceTransferAgentToName(output), source: this.name },
                     ],
-                }, context);
+                }, options.context);
             }
         }
     }
-    async publishToTopics(output, context) {
+    async publishToTopics(output, options) {
         const publishTopics = typeof this.publishTopic === "function" ? await this.publishTopic(output) : this.publishTopic;
         if (publishTopics?.length) {
-            context.publish(publishTopics, {
+            options.context.publish(publishTopics, {
                 role: this.constructor.name === "UserAgent" ? "user" : "agent",
                 source: this.name,
                 message: output,
@@ -510,11 +606,11 @@ export class FunctionAgent extends Agent {
      * Process input implementation, calls the configured processing function
      *
      * @param input Input message
-     * @param context Execution context
+     * @param options Invocation options
      * @returns Processing result
      */
-    process(input, context) {
-        return this._process(input, context);
+    process(input, options) {
+        return this._process(input, options);
     }
 }
 function functionToAgent(agent) {

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

@@ -1,10 +1,9 @@
 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 { type DefaultMemoryOptions } from "../memory/default-memory/index.js";
 import { PromptBuilder } from "../prompt/prompt-builder.js";
-import { Agent, type AgentOptions, type AgentProcessAsyncGenerator, type Message } from "./agent.js";
+import { Agent, type AgentInvokeOptions, 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
  *
@@ -215,7 +214,8 @@ export declare class AIAgent<I extends Message = Message, O extends Message = Me
      *
      * @protected
      */
-    process(input: I, context: Context): AgentProcessAsyncGenerator<O>;
+    process(input: I, options: AgentInvokeOptions): AgentProcessAsyncGenerator<O>;
+    protected onGuideRailError(error: GuideRailAgentOutput): Promise<O | GuideRailAgentOutput>;
     /**
      * Process router mode requests
      *
@@ -224,5 +224,5 @@ export declare class AIAgent<I extends Message = Message, O extends Message = Me
      *
      * @protected
      */
-    _processRouter(input: I, model: ChatModel, modelInput: ChatModelInput, context: Context, toolsMap: Map<string, Agent>): AgentProcessAsyncGenerator<O>;
+    _processRouter(input: I, model: ChatModel, modelInput: ChatModelInput, options: AgentInvokeOptions, toolsMap: Map<string, Agent>): AgentProcessAsyncGenerator<O>;
 }

package/lib/esm/agents/ai-agent.js

@@ -1,11 +1,11 @@
 import { z } from "zod";
-import { DefaultMemory } from "../memory/default-memory.js";
+import { DefaultMemory } from "../memory/default-memory/index.js";
 import { MemoryAgent } from "../memory/memory.js";
-import { ChatModel } from "../models/chat-model.js";
 import { MESSAGE_KEY, PromptBuilder } from "../prompt/prompt-builder.js";
 import { AgentMessageTemplate, ToolMessageTemplate } from "../prompt/template.js";
 import { checkArguments, isEmpty } from "../utils/type-utils.js";
 import { Agent, agentOptionsSchema, } from "./agent.js";
+import { ChatModel, } from "./chat-model.js";
 import { isTransferAgentOutput } from "./types.js";
 /**
  * Tool choice options for AI agents
@@ -185,26 +185,26 @@ export class AIAgent extends Agent {
      *
      * @protected
      */
-    async *process(input, context) {
-        const model = this.model ?? context.model;
+    async *process(input, options) {
+        const model = this.model ?? options.context.model;
         if (!model)
             throw new Error("model is required to run AIAgent");
         const { toolAgents, ...modelInput } = await this.instructions.build({
             agent: this,
             input,
             model,
-            context,
+            context: options.context,
         });
         const toolsMap = new Map(toolAgents?.map((i) => [i.name, i]));
         if (this.toolChoice === "router") {
-            yield* this._processRouter(input, model, modelInput, context, toolsMap);
+            yield* this._processRouter(input, model, modelInput, options, toolsMap);
             return;
         }
         const toolCallMessages = [];
         const outputKey = this.outputKey || MESSAGE_KEY;
         for (;;) {
             const modelOutput = {};
-            const stream = await context.invoke(model, { ...modelInput, messages: modelInput.messages.concat(toolCallMessages) }, { streaming: true });
+            const stream = await options.context.invoke(model, { ...modelInput, messages: modelInput.messages.concat(toolCallMessages) }, { streaming: true });
             for await (const value of stream) {
                 if (value.delta.text?.text) {
                     yield { delta: { text: { [outputKey]: value.delta.text.text } } };
@@ -222,9 +222,7 @@ export class AIAgent extends Agent {
                     if (!tool)
                         throw new Error(`Tool not found: ${call.function.name}`);
                     // NOTE: should pass both arguments (model generated) and input (user provided) to the tool
-                    const output = await context
-                        .invoke(tool, { ...input, ...call.function.arguments }, { disableTransfer: true })
-                        .catch((error) => {
+                    const output = await this.invokeSkill(tool, { ...input, ...call.function.arguments }, options).catch((error) => {
                         if (!this.catchToolsError) {
                             return Promise.reject(error);
                         }
@@ -248,7 +246,7 @@ export class AIAgent extends Agent {
                 }
             }
             const result = {};
-            if (modelInput.responseFormat?.type === "json_schema") {
+            if (json) {
                 Object.assign(result, json);
             }
             else if (text) {
@@ -260,6 +258,12 @@ export class AIAgent extends Agent {
             return;
         }
     }
+    async onGuideRailError(error) {
+        const outputKey = this.outputKey || MESSAGE_KEY;
+        return {
+            [outputKey]: error.reason,
+        };
+    }
     /**
      * Process router mode requests
      *
@@ -268,15 +272,15 @@ export class AIAgent extends Agent {
      *
      * @protected
      */
-    async *_processRouter(input, model, modelInput, context, toolsMap) {
-        const { toolCalls: [call] = [], } = await context.invoke(model, modelInput);
+    async *_processRouter(input, model, modelInput, options, toolsMap) {
+        const { toolCalls: [call] = [], } = await options.context.invoke(model, modelInput);
         if (!call) {
             throw new Error("Router toolChoice requires exactly one tool to be executed");
         }
         const tool = toolsMap.get(call.function.name);
         if (!tool)
             throw new Error(`Tool not found: ${call.function.name}`);
-        const stream = await context.invoke(tool, { ...call.function.arguments, ...input }, { streaming: true });
+        const stream = await options.context.invoke(tool, { ...call.function.arguments, ...input }, { streaming: true, sourceAgent: this });
         yield* stream;
     }
 }

package/lib/{dts/models → esm/agents}/chat-model.d.ts

@@ -1,6 +1,5 @@
-import { Agent, type AgentProcessResult, type Message } from "../agents/agent.js";
-import type { Context } from "../aigne/context.js";
 import type { PromiseOrValue } from "../utils/type-utils.js";
+import { Agent, type AgentInvokeOptions, type AgentProcessResult, type Message } from "./agent.js";
 /**
  * ChatModel is an abstract base class for interacting with Large Language Models (LLMs).
  *
@@ -10,19 +9,19 @@ import type { PromiseOrValue } from "../utils/type-utils.js";
  *
  * @example
  * Here's how to implement a custom ChatModel:
- * {@includeCode ../../test/models/chat-model.test.ts#example-chat-model}
+ * {@includeCode ../../test/agents/chat-model.test.ts#example-chat-model}
  *
  * @example
  * Here's an example showing streaming response with readable stream:
- * {@includeCode ../../test/models/chat-model.test.ts#example-chat-model-streaming}
+ * {@includeCode ../../test/agents/chat-model.test.ts#example-chat-model-streaming}
  *
  * @example
  * Here's an example showing streaming response with async generator:
- * {@includeCode ../../test/models/chat-model.test.ts#example-chat-model-streaming-async-generator}
+ * {@includeCode ../../test/agents/chat-model.test.ts#example-chat-model-streaming-async-generator}
  *
  * @example
  * Here's an example with tool calls:
- * {@includeCode ../../test/models/chat-model.test.ts#example-chat-model-tools}
+ * {@includeCode ../../test/agents/chat-model.test.ts#example-chat-model-tools}
  */
 export declare abstract class ChatModel extends Agent<ChatModelInput, ChatModelOutput> {
     constructor();
@@ -44,16 +43,27 @@ export declare abstract class ChatModel extends Agent<ChatModelInput, ChatModelO
         supportsParallelToolCalls: boolean;
     };
     private validateToolNames;
+    /**
+     * Normalizes tool names to ensure compatibility with language models
+     *
+     * This method converts tool names to a format that complies with model requirements
+     * by replacing hyphens and whitespace characters with underscores. The normalized
+     * names are used for tool calls while preserving the original names for reference.
+     *
+     * @param name - The original tool name to normalize
+     * @returns A promise that resolves to the normalized tool name
+     */
+    protected normalizeToolName(name: string): Promise<string>;
     /**
      * Performs preprocessing operations before handling input
      *
      * Primarily checks if token usage exceeds limits, throwing an exception if limits are exceeded
      *
      * @param input Input message
-     * @param context Execution context
+     * @param options Options for invoking the agent
      * @throws Error if token usage exceeds maximum limit
      */
-    protected preprocess(input: ChatModelInput, context: Context): void;
+    protected preprocess(input: ChatModelInput, options: AgentInvokeOptions): Promise<void>;
     /**
      * Performs postprocessing operations after handling output
      *
@@ -61,9 +71,9 @@ export declare abstract class ChatModel extends Agent<ChatModelInput, ChatModelO
      *
      * @param input Input message
      * @param output Output message
-     * @param context Execution context
+     * @param options Options for invoking the agent
      */
-    protected postprocess(input: ChatModelInput, output: ChatModelOutput, context: Context): void;
+    protected postprocess(input: ChatModelInput, output: ChatModelOutput, options: AgentInvokeOptions): Promise<void>;
     /**
      * Processes input messages and generates model responses
      *
@@ -81,10 +91,10 @@ export declare abstract class ChatModel extends Agent<ChatModelInput, ChatModelO
      * - Tool call processing if applicable
      *
      * @param input - The standardized input containing messages and model options
-     * @param context - The execution context with settings and state
+     * @param options - The options for invoking the agent, including context and limits
      * @returns A promise or direct value containing the model's response
      */
-    abstract process(input: ChatModelInput, context: Context): PromiseOrValue<AgentProcessResult<ChatModelOutput>>;
+    abstract process(input: ChatModelInput, options: AgentInvokeOptions): PromiseOrValue<AgentProcessResult<ChatModelOutput>>;
 }
 /**
  * Input message format for ChatModel
@@ -94,11 +104,11 @@ export declare abstract class ChatModel extends Agent<ChatModelInput, ChatModelO
  *
  * @example
  * Here's a basic ChatModel input example:
- * {@includeCode ../../test/models/chat-model.test.ts#example-chat-model}
+ * {@includeCode ../../test/agents/chat-model.test.ts#example-chat-model}
  *
  * @example
  * Here's an example with tool calling:
- * {@includeCode ../../test/models/chat-model.test.ts#example-chat-model-tools}
+ * {@includeCode ../../test/agents/chat-model.test.ts#example-chat-model-tools}
  */
 export interface ChatModelInput extends Message {
     /**
@@ -213,7 +223,7 @@ export type ChatModelInputResponseFormat = {
  *
  * @example
  * Here's an example showing how to use tools:
- * {@includeCode ../../test/models/chat-model.test.ts#example-chat-model-tools}
+ * {@includeCode ../../test/agents/chat-model.test.ts#example-chat-model-tools}
  */
 export interface ChatModelInputTool {
     /**
@@ -249,7 +259,7 @@ export interface ChatModelInputTool {
  *
  * @example
  * Here's an example showing how to use tools:
- * {@includeCode ../../test/models/chat-model.test.ts#example-chat-model-tools}
+ * {@includeCode ../../test/agents/chat-model.test.ts#example-chat-model-tools}
  */
 export type ChatModelInputToolChoice = "auto" | "none" | "required" | {
     type: "function";
@@ -296,11 +306,11 @@ export interface ChatModelOptions {
  *
  * @example
  * Here's a basic output example:
- * {@includeCode ../../test/models/chat-model.test.ts#example-chat-model}
+ * {@includeCode ../../test/agents/chat-model.test.ts#example-chat-model}
  *
  * @example
  * Here's an example with tool calls:
- * {@includeCode ../../test/models/chat-model.test.ts#example-chat-model-tools}
+ * {@includeCode ../../test/agents/chat-model.test.ts#example-chat-model-tools}
  */
 export interface ChatModelOutput extends Message {
     /**
@@ -331,7 +341,7 @@ export interface ChatModelOutput extends Message {
  *
  * @example
  * Here's an example with tool calls:
- * {@includeCode ../../test/models/chat-model.test.ts#example-chat-model-tools}
+ * {@includeCode ../../test/agents/chat-model.test.ts#example-chat-model-tools}
  */
 export interface ChatModelOutputToolCall {
     /**