@aigne/core 1.15.0 → 1.16.0

package/CHANGELOG.md

@@ -22,6 +22,21 @@
 * rename @aigne/core-next to @aigne/core ([3a81009](https://github.com/AIGNE-io/aigne-framework/commit/3a8100962c81813217b687ae28e8de604419c622))
 * use text resource from MCP correctly ([8b9eba8](https://github.com/AIGNE-io/aigne-framework/commit/8b9eba83352ec096a2a5d4f410d4c4bde7420bce))
 
+## [1.16.0](https://github.com/AIGNE-io/aigne-framework/compare/core-v1.15.0...core-v1.16.0) (2025-05-23)
+
+
+### Features
+
+* add `--chat` option for `run` command ([#120](https://github.com/AIGNE-io/aigne-framework/issues/120)) ([7699550](https://github.com/AIGNE-io/aigne-framework/commit/76995507001ca33b09b29f72ff588dae513cb340))
+* **core:** support check output with guide rail agents ([#117](https://github.com/AIGNE-io/aigne-framework/issues/117)) ([bdf7ab3](https://github.com/AIGNE-io/aigne-framework/commit/bdf7ab31789379ba5b0fd920541a469cb86150ff))
+* **core:** support lifecycle hooks for agent ([#124](https://github.com/AIGNE-io/aigne-framework/issues/124)) ([0af6afa](https://github.com/AIGNE-io/aigne-framework/commit/0af6afa923dcb917d545fd4535cabe7804fa84c9))
+* **models:** publish model adapters as standalone packages ([#126](https://github.com/AIGNE-io/aigne-framework/issues/126)) ([588b8ae](https://github.com/AIGNE-io/aigne-framework/commit/588b8aea6abcee5fa87def1358bf51f84021c6ef))
+
+
+### Bug Fixes
+
+* automatically convert tool names to a valid format ([#128](https://github.com/AIGNE-io/aigne-framework/issues/128)) ([e9ee91d](https://github.com/AIGNE-io/aigne-framework/commit/e9ee91d9d782fa19000adb4cf95b9d65196ab651))
+
 ## [1.15.0](https://github.com/AIGNE-io/aigne-framework/compare/core-v1.14.0...core-v1.15.0) (2025-05-15)
 
 

package/README.md

@@ -16,12 +16,12 @@ Core library of [AIGNE Framework](https://github.com/AIGNE-io/aigne-framework) f
 
 ## Features
 
-- **Multiple AI Model Support**: Built-in support for OpenAI, Gemini, Claude, Nova, and other mainstream AI models, easily extensible to support additional models
-- **Agent System**: Powerful agent abstractions supporting AI agents, function agents, MCP agents, and more
-- **AIGNE Environment**: Flexible handling communication between agents and workflow execution
-- **Workflow Patterns**: Support for sequential, concurrent, routing, handoff, and other workflow patterns
-- **MCP Protocol Integration**: Seamless integration with external systems through the Model Context Protocol
-- **TypeScript Support**: Comprehensive type definitions providing an excellent development experience
+* **Multiple AI Model Support**: Built-in support for OpenAI, Gemini, Claude, Nova, and other mainstream AI models, easily extensible to support additional models
+* **Agent System**: Powerful agent abstractions supporting AI agents, function agents, MCP agents, and more
+* **AIGNE Environment**: Flexible handling communication between agents and workflow execution
+* **Workflow Patterns**: Support for sequential, concurrent, routing, handoff, and other workflow patterns
+* **MCP Protocol Integration**: Seamless integration with external systems through the Model Context Protocol
+* **TypeScript Support**: Comprehensive type definitions providing an excellent development experience
 
 ## Installation
 
@@ -68,7 +68,9 @@ const aigne = new AIGNE({ model });
 const userAgent = await aigne.invoke(agent);
 
 // Send a message to the agent
-const response = await userAgent.invoke("Hello, can you help me write a short article?");
+const response = await userAgent.invoke(
+  "Hello, can you help me write a short article?",
+);
 console.log(response);
 ```
 

package/README.zh.md

@@ -16,12 +16,12 @@
 
 ## 特性
 
-- **多 AI 模型支持**：内置支持 OpenAI、Gemini、Claude、Nova 等主流 AI 模型，可轻松扩展支持其他模型
-- **代理系统**：强大的代理抽象，支持 AI 代理、功能代理、MCP 代理等
-- **AIGNE 环境**：灵活处理代理之间的通信和工作流执行
-- **工作流模式**：支持顺序、并发、路由、交接等多种工作流模式
-- **MCP 协议集成**：通过模型上下文协议与外部系统无缝集成
-- **TypeScript 支持**：全面的类型定义，提供出色的开发体验
+* **多 AI 模型支持**：内置支持 OpenAI、Gemini、Claude、Nova 等主流 AI 模型，可轻松扩展支持其他模型
+* **代理系统**：强大的代理抽象，支持 AI 代理、功能代理、MCP 代理等
+* **AIGNE 环境**：灵活处理代理之间的通信和工作流执行
+* **工作流模式**：支持顺序、并发、路由、交接等多种工作流模式
+* **MCP 协议集成**：通过模型上下文协议与外部系统无缝集成
+* **TypeScript 支持**：全面的类型定义，提供出色的开发体验
 
 ## 安装
 
@@ -68,7 +68,9 @@ const aigne = new AIGNE({ model });
 const userAgent = await aigne.invoke(agent);
 
 // 向代理发送消息
-const response = await userAgent.invoke("Hello, can you help me write a short article?");
+const response = await userAgent.invoke(
+  "Hello, can you help me write a short article?",
+);
 console.log(response);
 ```
 

package/lib/cjs/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/cjs/agents/agent.js

@@ -61,6 +61,16 @@ exports.agentOptionsSchema = zod_1.z.object({
     skills: zod_1.z.array(zod_1.z.union([zod_1.z.custom(), zod_1.z.custom()])).optional(),
     disableEvents: zod_1.z.boolean().optional(),
     memory: zod_1.z.union([zod_1.z.custom(), zod_1.z.array(zod_1.z.custom())]).optional(),
+    hooks: zod_1.z
+        .object({
+        onStart: zod_1.z.custom().optional(),
+        onEnd: zod_1.z.custom().optional(),
+        onSkillStart: zod_1.z.custom().optional(),
+        onSkillEnd: zod_1.z.custom().optional(),
+        onHandoff: zod_1.z.custom().optional(),
+    })
+        .optional(),
+    guideRails: zod_1.z.array(zod_1.z.custom()).optional(),
 });
 /**
  * Agent is the base class for all agents.
@@ -107,11 +117,42 @@ 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
      *
@@ -268,12 +309,13 @@ class Agent {
     async invoke(input, context, options) {
         const ctx = context ?? (await this.newDefaultContext());
         const message = typeof input === "string" ? (0, prompt_builder_js_1.createMessage)(input) : input;
-        logger_js_1.logger.core("Invoke agent %s started with input: %O", this.name, input);
+        logger_js_1.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 = (0, type_utils_js_1.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) {
@@ -285,27 +327,34 @@ class Agent {
                     : (0, stream_utils_js_1.isAsyncGenerator)(response)
                         ? (0, stream_utils_js_1.asyncGeneratorToReadableStream)(response)
                         : (0, stream_utils_js_1.objectToAgentResponseStream)(response);
-                return (0, stream_utils_js_1.onAgentResponseStreamEnd)(stream, async (result) => {
+                return this.checkResponseByGuideRails(message, (0, stream_utils_js_1.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 (0, stream_utils_js_1.agentResponseStreamToObject)(response)
                 : (0, stream_utils_js_1.isAsyncGenerator)(response)
                     ? await (0, stream_utils_js_1.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;
         }
     }
     /**
@@ -321,10 +370,11 @@ class Agent {
     async processAgentOutput(input, output, context) {
         const parsedOutput = (0, type_utils_js_1.checkArguments)(`Agent ${this.name} output`, this.outputSchema, output);
         const finalOutput = this.includeInputInOutput ? { ...input, ...parsedOutput } : parsedOutput;
-        this.postprocess(input, finalOutput, context);
-        logger_js_1.logger.core("Invoke agent %s succeed with output: %O", this.name, finalOutput);
+        await this.postprocess(input, finalOutput, context);
+        logger_js_1.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;
     }
     /**
@@ -334,13 +384,13 @@ class Agent {
      *
      * @param error Caught error
      * @param context Execution context
-     * @throws Always throws the received error
      */
-    processAgentError(error, context) {
-        logger_js_1.logger.core("Invoke agent %s failed with error: %O", this.name, error);
+    async processAgentError(input, error, context) {
+        logger_js_1.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
@@ -372,6 +422,48 @@ 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 (0, stream_utils_js_1.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/cjs/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
      *

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

@@ -4,11 +4,11 @@ exports.AIAgent = exports.aiAgentOptionsSchema = exports.aiAgentToolChoiceSchema
 const zod_1 = require("zod");
 const default_memory_js_1 = require("../memory/default-memory.js");
 const memory_js_1 = require("../memory/memory.js");
-const chat_model_js_1 = require("../models/chat-model.js");
 const prompt_builder_js_1 = require("../prompt/prompt-builder.js");
 const template_js_1 = require("../prompt/template.js");
 const type_utils_js_1 = require("../utils/type-utils.js");
 const agent_js_1 = require("./agent.js");
+const chat_model_js_1 = require("./chat-model.js");
 const types_js_1 = require("./types.js");
 /**
  * Tool choice options for AI agents
@@ -225,9 +225,7 @@ class AIAgent extends agent_js_1.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 }, context).catch((error) => {
                         if (!this.catchToolsError) {
                             return Promise.reject(error);
                         }
@@ -251,7 +249,7 @@ class AIAgent extends agent_js_1.Agent {
                 }
             }
             const result = {};
-            if (modelInput.responseFormat?.type === "json_schema") {
+            if (json) {
                 Object.assign(result, json);
             }
             else if (text) {
@@ -263,6 +261,12 @@ class AIAgent extends agent_js_1.Agent {
             return;
         }
     }
+    async onGuideRailError(error) {
+        const outputKey = this.outputKey || prompt_builder_js_1.MESSAGE_KEY;
+        return {
+            [outputKey]: error.reason,
+        };
+    }
     /**
      * Process router mode requests
      *
@@ -279,7 +283,7 @@ class AIAgent extends agent_js_1.Agent {
         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 context.invoke(tool, { ...call.function.arguments, ...input }, { streaming: true, sourceAgent: this });
         yield* stream;
     }
 }

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

@@ -1,6 +1,6 @@
-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 AgentProcessResult, type Message } from "./agent.js";
 /**
  * ChatModel is an abstract base class for interacting with Large Language Models (LLMs).
  *
@@ -10,19 +10,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,6 +44,17 @@ 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
      *
@@ -53,7 +64,7 @@ export declare abstract class ChatModel extends Agent<ChatModelInput, ChatModelO
      * @param context Execution context
      * @throws Error if token usage exceeds maximum limit
      */
-    protected preprocess(input: ChatModelInput, context: Context): void;
+    protected preprocess(input: ChatModelInput, context: Context): Promise<void>;
     /**
      * Performs postprocessing operations after handling output
      *
@@ -94,11 +105,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 +224,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 +260,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 +307,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 +342,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 {
     /**