@aigne/core 1.16.0 → 1.18.0

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

@@ -2,6 +2,7 @@ import type { Camelize } from "camelize-ts";
 import { z } from "zod";
 import { type Agent } from "../agents/agent.js";
 import type { ChatModel, ChatModelOptions } from "../agents/chat-model.js";
+import type { MemoryAgent, MemoryAgentOptions } from "../memory/memory.js";
 export interface LoadOptions {
     models: {
         new (parameters: {
@@ -9,6 +10,9 @@ export interface LoadOptions {
             modelOptions?: ChatModelOptions;
         }): ChatModel;
     }[];
+    memories?: {
+        new (parameters?: MemoryAgentOptions): MemoryAgent;
+    }[];
     path: string;
 }
 export declare function load(options: LoadOptions): Promise<{
@@ -26,7 +30,7 @@ export declare function load(options: LoadOptions): Promise<{
         presence_penalty?: number | null | undefined;
     } | null | undefined;
 }>;
-export declare function loadAgent(path: string): Promise<Agent>;
+export declare function loadAgent(path: string, options?: LoadOptions): Promise<Agent>;
 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>>;

package/lib/cjs/loader/index.js

@@ -4,24 +4,22 @@ exports.load = load;
 exports.loadAgent = loadAgent;
 exports.loadModel = loadModel;
 exports.loadAIGNEFile = loadAIGNEFile;
-const promises_1 = require("node:fs/promises");
-const node_path_1 = require("node:path");
 const yaml_1 = require("yaml");
 const zod_1 = require("zod");
 const agent_js_1 = require("../agents/agent.js");
 const ai_agent_js_1 = require("../agents/ai-agent.js");
 const mcp_agent_js_1 = require("../agents/mcp-agent.js");
+const nodejs_js_1 = require("../utils/nodejs.js");
 const type_utils_js_1 = require("../utils/type-utils.js");
 const agent_js_js_1 = require("./agent-js.js");
 const agent_yaml_js_1 = require("./agent-yaml.js");
 const AIGNE_FILE_NAME = ["aigne.yaml", "aigne.yml"];
 async function load(options) {
-    const { path } = options;
-    const aigneFilePath = await getAIGNEFilePath(path);
-    const rootDir = (0, node_path_1.dirname)(aigneFilePath);
+    const aigneFilePath = await getAIGNEFilePath(options.path);
+    const rootDir = nodejs_js_1.nodejs.path.dirname(aigneFilePath);
     const aigne = await loadAIGNEFile(aigneFilePath);
-    const agents = await Promise.all((aigne.agents ?? []).map((filename) => loadAgent((0, node_path_1.join)(rootDir, filename))));
-    const skills = await Promise.all((aigne.skills ?? []).map((filename) => loadAgent((0, node_path_1.join)(rootDir, filename))));
+    const agents = await Promise.all((aigne.agents ?? []).map((filename) => loadAgent(nodejs_js_1.nodejs.path.join(rootDir, filename))));
+    const skills = await Promise.all((aigne.skills ?? []).map((filename) => loadAgent(nodejs_js_1.nodejs.path.join(rootDir, filename))));
     return {
         ...aigne,
         model: await loadModel(options.models, aigne.chat_model),
@@ -29,18 +27,21 @@ async function load(options) {
         skills,
     };
 }
-async function loadAgent(path) {
-    if ((0, node_path_1.extname)(path) === ".js") {
+async function loadAgent(path, options) {
+    if (nodejs_js_1.nodejs.path.extname(path) === ".js") {
         const agent = await (0, agent_js_js_1.loadAgentFromJsFile)(path);
         return agent_js_1.FunctionAgent.from(agent);
     }
-    if ((0, node_path_1.extname)(path) === ".yaml" || (0, node_path_1.extname)(path) === ".yml") {
+    if (nodejs_js_1.nodejs.path.extname(path) === ".yaml" || nodejs_js_1.nodejs.path.extname(path) === ".yml") {
         const agent = await (0, agent_yaml_js_1.loadAgentFromYamlFile)(path);
         if (agent.type === "ai") {
             return ai_agent_js_1.AIAgent.from({
                 ...agent,
+                memory: !options?.memories?.length || !agent.memory
+                    ? undefined
+                    : await loadMemory(options.memories, typeof agent.memory === "object" ? agent.memory.provider : undefined, typeof agent.memory === "object" ? agent.memory : {}),
                 skills: agent.skills &&
-                    (await Promise.all(agent.skills.map((filename) => loadAgent((0, node_path_1.join)((0, node_path_1.dirname)(path), filename))))),
+                    (await Promise.all(agent.skills.map((filename) => loadAgent(nodejs_js_1.nodejs.path.join(nodejs_js_1.nodejs.path.dirname(path), filename))))),
             });
         }
         if (agent.type === "mcp") {
@@ -60,7 +61,15 @@ async function loadAgent(path) {
     }
     throw new Error(`Unsupported agent file type: ${path}`);
 }
-const { MODEL_PROVIDER, MODEL_NAME } = process.env;
+async function loadMemory(memories, provider, options) {
+    const M = !provider
+        ? memories[0]
+        : memories.find((i) => i.name.toLowerCase().includes(provider.toLowerCase()));
+    if (!M)
+        throw new Error(`Unsupported memory: ${provider}`);
+    return new M(options);
+}
+const { MODEL_PROVIDER, MODEL_NAME } = nodejs_js_1.nodejs.env;
 const DEFAULT_MODEL_PROVIDER = "openai";
 async function loadModel(models, model, modelOptions) {
     const params = {
@@ -98,17 +107,17 @@ const aigneFileSchema = zod_1.z.object({
     skills: zod_1.z.array(zod_1.z.string()).nullish(),
 });
 async function loadAIGNEFile(path) {
-    const raw = await (0, type_utils_js_1.tryOrThrow)(() => (0, promises_1.readFile)(path, "utf8"), (error) => new Error(`Failed to load aigne.yaml from ${path}: ${error.message}`));
+    const raw = await (0, type_utils_js_1.tryOrThrow)(() => nodejs_js_1.nodejs.fs.readFile(path, "utf8"), (error) => new Error(`Failed to load aigne.yaml from ${path}: ${error.message}`));
     const json = await (0, type_utils_js_1.tryOrThrow)(() => (0, yaml_1.parse)(raw), (error) => new Error(`Failed to parse aigne.yaml from ${path}: ${error.message}`));
     const agent = (0, type_utils_js_1.tryOrThrow)(() => aigneFileSchema.parse({ ...json, skills: json.skills ?? json.tools }), (error) => new Error(`Failed to validate aigne.yaml from ${path}: ${error.message}`));
     return agent;
 }
 async function getAIGNEFilePath(path) {
-    const s = await (0, promises_1.stat)(path);
+    const s = await nodejs_js_1.nodejs.fs.stat(path);
     if (s.isDirectory()) {
         for (const file of AIGNE_FILE_NAME) {
-            const filePath = (0, node_path_1.join)(path, file);
-            if ((await (0, promises_1.stat)(filePath)).isFile())
+            const filePath = nodejs_js_1.nodejs.path.join(path, file);
+            if ((await nodejs_js_1.nodejs.fs.stat(filePath)).isFile())
                 return filePath;
         }
     }

package/lib/cjs/memory/memory.d.ts

@@ -1,10 +1,11 @@
-import { Agent, type AgentOptions, type Message } from "../agents/agent.js";
+import { Agent, type AgentInvokeOptions, type AgentOptions, type Message } from "../agents/agent.js";
 import type { Context } from "../aigne/context.js";
 import type { MessagePayload } from "../aigne/message-queue.js";
 import type { MemoryRecorder, MemoryRecorderInput, MemoryRecorderOutput } from "./recorder.js";
 import type { MemoryRetriever, MemoryRetrieverInput, MemoryRetrieverOutput } from "./retriever.js";
 export interface Memory {
     id: string;
+    sessionId?: string | null;
     content: unknown;
     createdAt: string;
 }
@@ -62,7 +63,7 @@ export declare class MemoryAgent extends Agent {
      * MemoryAgent doesn't directly process messages like other agents, so this method
      * throws an error when called. Use the specialized retrieve() and record() methods instead.
      */
-    process(_input: Message, _context: Context): Promise<Message>;
+    process(_input: Message, _options: AgentInvokeOptions): Promise<Message>;
     /**
      * Retrieves memories based on the provided input criteria.
      *

package/lib/cjs/memory/memory.js

@@ -85,7 +85,7 @@ class MemoryAgent extends agent_js_1.Agent {
      * MemoryAgent doesn't directly process messages like other agents, so this method
      * throws an error when called. Use the specialized retrieve() and record() methods instead.
      */
-    async process(_input, _context) {
+    async process(_input, _options) {
         throw new Error("Method not implemented.");
     }
     /**

package/lib/cjs/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, {
-    search?: string | undefined;
     limit?: number | undefined;
-}, {
     search?: string | undefined;
+}, {
     limit?: number | undefined;
+    search?: string | undefined;
 }>;
 /**
  * @hidden

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

@@ -1,19 +1,21 @@
 import type { GetPromptResult } from "@modelcontextprotocol/sdk/types.js";
-import { Agent, type Message } from "../agents/agent.js";
+import { Agent, type AgentInvokeOptions, 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 { ChatMessagesTemplate } from "./template.js";
 export declare const MESSAGE_KEY = "$message";
-export declare function createMessage<I extends Message>(message: string | I): I;
+export declare function createMessage<V extends Message>(message: string, variables?: V): {
+    [MESSAGE_KEY]: string;
+} & typeof variables;
+export declare function createMessage<I extends Message, V extends Message>(message: I, variables?: V): I & typeof variables;
+export declare function createMessage<I extends Message, V extends Message>(message: string | I, variables?: V): ({
+    [MESSAGE_KEY]: string;
+} | I) & typeof variables;
 export declare function getMessage(input: Message): string | undefined;
 export interface PromptBuilderOptions {
     instructions?: string | ChatMessagesTemplate;
 }
-export interface PromptBuildOptions {
-    memory?: MemoryAgent | MemoryAgent[];
-    context: Context;
+export interface PromptBuildOptions extends AgentInvokeOptions {
     agent?: AIAgent;
     input?: Message;
     model?: ChatModel;

package/lib/cjs/prompt/prompt-builder.js

@@ -3,19 +3,19 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.PromptBuilder = exports.MESSAGE_KEY = void 0;
 exports.createMessage = createMessage;
 exports.getMessage = getMessage;
-const promises_1 = require("node:fs/promises");
 const yaml_1 = require("yaml");
 const zod_1 = require("zod");
 const agent_js_1 = require("../agents/agent.js");
 const json_schema_js_1 = require("../utils/json-schema.js");
+const nodejs_js_1 = require("../utils/nodejs.js");
 const type_utils_js_1 = require("../utils/type-utils.js");
 const memory_message_template_js_1 = require("./prompts/memory-message-template.js");
 const template_js_1 = require("./template.js");
 exports.MESSAGE_KEY = "$message";
-function createMessage(message) {
-    return typeof message === "string"
-        ? { [exports.MESSAGE_KEY]: message }
-        : { ...message };
+function createMessage(message, variables) {
+    return (typeof message === "string"
+        ? { [exports.MESSAGE_KEY]: message, ...variables }
+        : { ...message, ...variables });
 }
 function getMessage(input) {
     const userInputMessage = input[exports.MESSAGE_KEY];
@@ -36,7 +36,7 @@ class PromptBuilder {
         throw new Error(`Invalid instructions ${instructions}`);
     }
     static async fromFile(path) {
-        const text = await (0, promises_1.readFile)(path, "utf-8");
+        const text = await nodejs_js_1.nodejs.fs.readFile(path, "utf-8");
         return PromptBuilder.from(text);
     }
     static fromMCPPromptResult(result) {
@@ -83,11 +83,15 @@ class PromptBuilder {
         const messages = (typeof this.instructions === "string"
             ? template_js_1.ChatMessagesTemplate.from([template_js_1.SystemMessageTemplate.from(this.instructions)])
             : this.instructions)?.format(options.input) ?? [];
-        for (const memory of (0, type_utils_js_1.orArrayToArray)(options.memory ?? options.agent?.memories)) {
-            const memories = (await memory.retrieve({ search: input && getMessage(input) }, options.context))?.memories;
-            if (memories?.length)
-                messages.push(...this.convertMemoriesToMessages(memories, options));
+        const memories = [];
+        if (options.agent) {
+            memories.push(...(await options.agent.retrieveMemories({ search: options.input }, options)));
         }
+        if (options.memories?.length) {
+            memories.push(...options.memories);
+        }
+        if (memories.length)
+            messages.push(...this.convertMemoriesToMessages(memories, options));
         const content = input && getMessage(input);
         // add user input if it's not the same as the last message
         if (content && messages.at(-1)?.content !== content) {

package/lib/cjs/prompt/template.js

@@ -5,10 +5,8 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ChatMessagesTemplate = exports.ToolMessageTemplate = exports.AgentMessageTemplate = exports.UserMessageTemplate = exports.SystemMessageTemplate = exports.ChatMessageTemplate = exports.PromptTemplate = void 0;
 exports.parseChatMessages = parseChatMessages;
-const node_util_1 = require("node:util");
 const mustache_1 = __importDefault(require("mustache"));
 const zod_1 = require("zod");
-const type_utils_js_1 = require("../utils/type-utils.js");
 class PromptTemplate {
     template;
     static from(template) {
@@ -92,7 +90,7 @@ class ToolMessageTemplate extends ChatMessageTemplate {
     constructor(content, toolCallId, name) {
         super("tool", typeof content === "string"
             ? content
-            : (0, type_utils_js_1.tryOrThrow)(() => JSON.stringify(content, (_, value) => typeof value === "bigint" ? value.toString() : value), `Failed to stringify tool content. toolCallId: ${toolCallId}, content: ${(0, node_util_1.inspect)(content)}`), name);
+            : JSON.stringify(content, (_, value) => typeof value === "bigint" ? value.toString() : value), name);
         this.toolCallId = toolCallId;
     }
     format(variables) {

package/lib/cjs/utils/logger.js

@@ -4,8 +4,8 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.logger = exports.Logger = exports.LogLevel = void 0;
-const node_tty_1 = require("node:tty");
 const debug_1 = __importDefault(require("debug"));
+const nodejs_js_1 = require("./nodejs.js");
 var LogLevel;
 (function (LogLevel) {
     LogLevel["ERROR"] = "error";
@@ -23,13 +23,13 @@ class Logger {
         this.errorLogger = (0, debug_1.default)(`${options.ns}:error`);
         for (const logger of [this.debugLogger, this.infoLogger, this.warnLogger]) {
             // @ts-ignore
-            logger.useColors = (0, node_tty_1.isatty)(process.stdout.fd);
+            logger.useColors = nodejs_js_1.nodejs.isStdoutATTY;
             logger.enabled = true;
             logger.log = (...args) => this.logMessage(...args);
         }
         this.errorLogger.log = (...args) => this.logError(...args);
         // @ts-ignore
-        this.errorLogger.useColors = (0, node_tty_1.isatty)(process.stderr.fd);
+        this.errorLogger.useColors = nodejs_js_1.nodejs.isStderrATTY;
         this.errorLogger.enabled = true;
     }
     level;

package/lib/cjs/utils/nodejs.d.ts

@@ -0,0 +1,8 @@
+export declare const nodejs: {
+    customInspect: any;
+    isStdoutATTY: boolean;
+    isStderrATTY: boolean;
+    env: NodeJS.ProcessEnv;
+    readonly fs: typeof import("node:fs/promises");
+    readonly path: typeof import("node:path");
+};

package/lib/cjs/utils/nodejs.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.nodejs = void 0;
+exports.nodejs = {
+    customInspect: isNodejsEnvironment() ? require("node:util").inspect.custom : Symbol("inspect"),
+    isStdoutATTY: isNodejsEnvironment() && process.stdout?.isTTY,
+    isStderrATTY: isNodejsEnvironment() && process.stderr?.isTTY,
+    env: isNodejsEnvironment() ? process.env : {},
+    get fs() {
+        ensureNodejsEnvironment();
+        return require("node:fs/promises");
+    },
+    get path() {
+        ensureNodejsEnvironment();
+        return require("node:path");
+    },
+};
+function isNodejsEnvironment() {
+    return typeof process !== "undefined";
+}
+function ensureNodejsEnvironment() {
+    if (!isNodejsEnvironment())
+        throw new Error("This code must run in a Node.js environment.");
+}

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

@@ -1,4 +1,4 @@
-import { type ZodType } from "zod";
+import { type ZodType, z } 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;
@@ -20,6 +20,6 @@ export declare function orArrayToArray<T>(value?: T | T[]): T[];
 export declare function createAccessorArray<T>(array: T[], accessor: (array: T[], name: string) => T | undefined): T[] & {
     [key: string]: T;
 };
-export declare function checkArguments<T>(prefix: string, schema: ZodType<T>, args: T | unknown): T;
+export declare function checkArguments<T extends ZodType>(prefix: string, schema: T, args: unknown): z.infer<T>;
 export declare function tryOrThrow<P extends PromiseOrValue<unknown>>(fn: () => P, error: string | Error | ((error: Error) => Error)): P;
 export declare function tryOrThrow<P extends PromiseOrValue<unknown>>(fn: () => P, error?: Nullish<string | Error | ((error: Error) => Nullish<Error>)>): P | undefined;

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

@@ -1,8 +1,10 @@
-import { inspect } from "node:util";
 import { ZodObject, type ZodType } from "zod";
-import type { Context } from "../aigne/context.js";
+import type { Context, UserContext } from "../aigne/context.js";
 import type { MessagePayload } from "../aigne/message-queue.js";
-import type { MemoryAgent } from "../memory/memory.js";
+import type { Memory, MemoryAgent } from "../memory/memory.js";
+import type { MemoryRecorderInput } from "../memory/recorder.js";
+import type { MemoryRetrieverInput } from "../memory/retriever.js";
+import { nodejs } from "../utils/nodejs.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";
@@ -95,11 +97,29 @@ export interface AgentOptions<I extends Message = Message, O extends Message = M
      * One or more memory agents this agent can use
      */
     memory?: MemoryAgent | MemoryAgent[];
+    /**
+     * Maximum number of memory items to retrieve
+     */
+    maxRetrieveMemoryCount?: number;
 }
 export declare const agentOptionsSchema: ZodObject<{
     [key in keyof AgentOptions]: ZodType<AgentOptions[key]>;
 }>;
-export interface AgentInvokeOptions {
+export interface AgentInvokeOptions<U extends UserContext = UserContext> {
+    /**
+     * The execution context for the agent
+     *
+     * The context provides the runtime environment for agent execution, including:
+     * - Event emission and subscription management
+     * - Inter-agent communication and message passing
+     * - Resource usage tracking and limits enforcement
+     * - Timeout and status management
+     * - Memory and state management across agent invocations
+     *
+     * Each agent invocation requires a context to coordinate with the broader
+     * agent system and maintain proper isolation and resource control.
+     */
+    context: Context<U>;
     /**
      * Whether to enable streaming response
      *
@@ -111,6 +131,8 @@ export interface AgentInvokeOptions {
      * and returns the final JSON result
      */
     streaming?: boolean;
+    userContext?: U;
+    memories?: Pick<Memory, "content">[];
 }
 /**
  * Agent is the base class for all agents.
@@ -135,11 +157,24 @@ export interface AgentInvokeOptions {
  * {@includeCode ../../test/agents/agent.test.ts#example-custom-agent}
  */
 export declare abstract class Agent<I extends Message = Message, O extends Message = Message> {
+    /**
+     * Custom object inspection behavior
+     *
+     * When using Node.js's util.inspect function to inspect an agent,
+     * only the agent's name will be shown, making output more concise
+     *
+     * @returns Agent name
+     */
+    [nodejs.customInspect]: () => string;
     constructor(options?: AgentOptions<I, O>);
     /**
      * List of memories this agent can use
      */
     readonly memories: MemoryAgent[];
+    /**
+     * Maximum number of memory items to retrieve
+     */
+    maxRetrieveMemoryCount?: number;
     /**
      * Lifecycle hooks for agent processing.
      *
@@ -278,11 +313,15 @@ export declare abstract class Agent<I extends Message = Message, O extends Messa
     /**
      * 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
      */
     private checkContextStatus;
     private newDefaultContext;
+    retrieveMemories(input: Pick<MemoryRetrieverInput, "limit"> & {
+        search?: Message | string;
+    }, options: Pick<AgentInvokeOptions, "context">): Promise<Pick<Memory, "content">[]>;
+    recordMemories(input: MemoryRecorderInput, options: Pick<AgentInvokeOptions, "context">): Promise<void>;
     /**
      * Invoke the agent with regular (non-streaming) response
      *
@@ -290,7 +329,6 @@ export declare abstract class Agent<I extends Message = Message, O extends Messa
      * suitable for scenarios where a complete result is needed at once.
      *
      * @param input Input message to the agent, can be a string or structured object
-     * @param context Execution context, providing environment and resource access
      * @param options Invocation options, must set streaming to false or leave unset
      * @returns Final JSON response
      *
@@ -298,7 +336,7 @@ export declare abstract class Agent<I extends Message = Message, O extends Messa
      * Here's an example of invoking an agent with regular mode:
      * {@includeCode ../../test/agents/agent.test.ts#example-invoke}
      */
-    invoke(input: I | string, context?: Context, options?: AgentInvokeOptions & {
+    invoke(input: I | string, options?: Partial<AgentInvokeOptions> & {
         streaming?: false;
     }): Promise<O>;
     /**
@@ -309,7 +347,6 @@ export declare abstract class Agent<I extends Message = Message, O extends Messa
      * chat bot typing effects.
      *
      * @param input Input message to the agent, can be a string or structured object
-     * @param context Execution context, providing environment and resource access
      * @param options Invocation options, must set streaming to true for this overload
      * @returns Streaming response object
      *
@@ -317,7 +354,7 @@ export declare abstract class Agent<I extends Message = Message, O extends Messa
      * Here's an example of invoking an agent with streaming response:
      * {@includeCode ../../test/agents/agent.test.ts#example-invoke-streaming}
      */
-    invoke(input: I | string, context: Context | undefined, options: {
+    invoke(input: I | string, options: Partial<AgentInvokeOptions> & {
         streaming: true;
     }): Promise<AgentResponseStream<O>>;
     /**
@@ -326,12 +363,11 @@ export declare abstract class Agent<I extends Message = Message, O extends Messa
      * Returns either streaming or regular response based on the streaming parameter in options
      *
      * @param input Input message to the agent
-     * @param context Execution context
      * @param options Invocation options
      * @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>;
+    invoke(input: I | string, options?: Partial<AgentInvokeOptions>): Promise<AgentResponse<O>>;
+    protected invokeSkill<I extends Message, O extends Message>(skill: Agent<I, O>, input: I, options: AgentInvokeOptions): Promise<O>;
     /**
      * Process agent output
      *
@@ -339,7 +375,7 @@ export declare abstract class Agent<I extends Message = Message, O extends Messa
      *
      * @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
      */
     private processAgentOutput;
@@ -349,7 +385,7 @@ export declare abstract class Agent<I extends Message = Message, O extends Messa
      * Logs error information, triggers failure events, and re-throws the error
      *
      * @param error Caught error
-     * @param context Execution context
+     * @param options Invocation options
      */
     private processAgentError;
     /**
@@ -358,10 +394,10 @@ export declare abstract class Agent<I extends Message = Message, O extends Messa
      * 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
      */
-    protected checkAgentInvokesUsage(context: Context): void;
+    protected checkAgentInvokesUsage(options: AgentInvokeOptions): void;
     /**
      * Pre-processing operations before handling input
      *
@@ -370,9 +406,9 @@ export declare abstract class Agent<I extends Message = Message, O extends Messa
      * - Verifying invocation limits
      *
      * @param _ Input message (unused)
-     * @param context Execution context
+     * @param options Options for agent invocation
      */
-    protected preprocess(_: I, context: Context): PromiseOrValue<void>;
+    protected preprocess(_: I, options: AgentInvokeOptions): Promise<void>;
     private checkResponseByGuideRails;
     private runGuideRails;
     /**
@@ -400,10 +436,10 @@ export declare abstract class Agent<I extends Message = Message, O extends Messa
      *
      * @param input Input message
      * @param output Output message
-     * @param context Execution context
+     * @param options Options for agent invocation
      */
-    protected postprocess(input: I, output: O, context: Context): PromiseOrValue<void>;
-    protected publishToTopics(output: Message, context: Context): Promise<void>;
+    protected postprocess(input: I, output: O, options: AgentInvokeOptions): Promise<void>;
+    protected publishToTopics(output: Message, options: AgentInvokeOptions): Promise<void>;
     /**
      * Core processing method of the agent, must be implemented in subclasses
      *
@@ -415,7 +451,7 @@ export declare abstract class Agent<I extends Message = Message, O extends Messa
      * - Another agent instance (transfer agent)
      *
      * @param input Input message
-     * @param context Execution context
+     * @param options Options for agent invocation
      * @returns Processing result
      *
      * @example
@@ -434,7 +470,7 @@ export declare abstract class Agent<I extends Message = Message, O extends Messa
      * Example of transfer to another agent:
      * {@includeCode ../../test/agents/agent.test.ts#example-process-transfer}
      */
-    abstract process(input: I, context: Context): PromiseOrValue<AgentProcessResult<O>>;
+    abstract process(input: I, options: AgentInvokeOptions): PromiseOrValue<AgentProcessResult<O>>;
     /**
      * Shut down the agent and clean up resources
      *
@@ -449,15 +485,6 @@ export declare abstract class Agent<I extends Message = Message, O extends Messa
      * {@includeCode ../../test/agents/agent.test.ts#example-agent-shutdown-by-using}
      */
     shutdown(): Promise<void>;
-    /**
-     * Custom object inspection behavior
-     *
-     * When using Node.js's util.inspect function to inspect an agent,
-     * only the agent's name will be shown, making output more concise
-     *
-     * @returns Agent name
-     */
-    [inspect.custom](): string;
     /**
      * Async dispose method for shutdown the agent
      *
@@ -484,6 +511,7 @@ export interface AgentHooks<I extends Message = Message, O extends Message = Mes
      * @param event Object containing the input message
      */
     onStart?: (event: {
+        context: Context;
         input: I;
     }) => PromiseOrValue<void>;
     /**
@@ -496,6 +524,7 @@ 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<{
+        context: Context;
         input: I;
         output: O;
         error: Error;
@@ -509,6 +538,7 @@ export interface AgentHooks<I extends Message = Message, O extends Message = Mes
      * @param event Object containing the skill being used and input message
      */
     onSkillStart?: (event: {
+        context: Context;
         skill: Agent;
         input: I;
     }) => PromiseOrValue<void>;
@@ -522,6 +552,7 @@ 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<{
+        context: Context;
         skill: Agent;
         input: I;
         output: O;
@@ -537,6 +568,7 @@ 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: {
+        context: Context;
         source: Agent;
         target: Agent;
         input: I;
@@ -587,7 +619,7 @@ export interface AgentResponseDelta<T> {
         }> | Partial<{
             [key: string]: string;
         }>;
-        json?: Partial<T | TransferAgentOutput>;
+        json?: Partial<T> | TransferAgentOutput;
     };
 }
 /**
@@ -619,7 +651,7 @@ export declare function jsonDelta<T extends Message>(jsonDelta: NonNullable<Agen
  *
  * @template O Agent output message type
  */
-export type AgentProcessAsyncGenerator<O extends Message> = AsyncGenerator<AgentResponseChunk<O>, Partial<O | TransferAgentOutput> | undefined | void>;
+export type AgentProcessAsyncGenerator<O extends Message> = AsyncGenerator<AgentResponseChunk<O>, Partial<O> | TransferAgentOutput | undefined | void>;
 /**
  * Result type for agent processing method, can be:
  * - Direct or streaming response
@@ -709,10 +741,10 @@ export declare class FunctionAgent<I extends Message = Message, O extends Messag
      * 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: I, context: Context): PromiseOrValue<AgentProcessResult<O>>;
+    process(input: I, options: AgentInvokeOptions): PromiseOrValue<AgentProcessResult<O>>;
 }
 /**
  * Function type for function agents
@@ -725,4 +757,4 @@ export declare class FunctionAgent<I extends Message = Message, O extends Messag
  * @param context Execution context
  * @returns Processing result, can be synchronous or asynchronous
  */
-export type FunctionAgentFn<I extends Message = any, O extends Message = any> = (input: I, context: Context) => PromiseOrValue<AgentProcessResult<O>>;
+export type FunctionAgentFn<I extends Message = any, O extends Message = any> = (input: I, options: AgentInvokeOptions) => PromiseOrValue<AgentProcessResult<O>>;