@aigne/core 1.15.0 → 1.17.0

package/lib/esm/{models → agents}/chat-model.js

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { Agent } from "../agents/agent.js";
+import { Agent } from "./agent.js";
 /**
  * ChatModel is an abstract base class for interacting with Large Language Models (LLMs).
  *
@@ -9,19 +9,19 @@ import { Agent } from "../agents/agent.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 class ChatModel extends Agent {
     constructor() {
@@ -56,23 +56,51 @@ export class ChatModel extends Agent {
             }
         }
     }
+    /**
+     * 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
+     */
+    async normalizeToolName(name) {
+        return name.replaceAll(/[-\s]/g, "_");
+    }
     /**
      * 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
      */
-    preprocess(input, context) {
-        super.preprocess(input, context);
-        const { limits, usage } = context;
+    async preprocess(input, options) {
+        super.preprocess(input, options);
+        const { limits, usage } = options.context;
         const usedTokens = usage.outputTokens + usage.inputTokens;
         if (limits?.maxTokens && usedTokens >= limits.maxTokens) {
             throw new Error(`Exceeded max tokens ${usedTokens}/${limits.maxTokens}`);
         }
-        this.validateToolNames(input.tools);
+        // Automatically convert tool names to a valid format
+        if (input.tools?.length) {
+            const toolsMap = {};
+            const tools = [];
+            for (const originalTool of input.tools) {
+                const name = await this.normalizeToolName(originalTool.function.name);
+                const tool = {
+                    ...originalTool,
+                    function: { ...originalTool.function, name },
+                };
+                tools.push(tool);
+                toolsMap[name] = originalTool;
+            }
+            this.validateToolNames(tools);
+            Object.assign(input, { _toolsMap: toolsMap, tools });
+        }
     }
     /**
      * Performs postprocessing operations after handling output
@@ -81,14 +109,27 @@ export class ChatModel extends Agent {
      *
      * @param input Input message
      * @param output Output message
-     * @param context Execution context
+     * @param options Options for invoking the agent
      */
-    postprocess(input, output, context) {
-        super.postprocess(input, output, context);
+    async postprocess(input, output, options) {
+        // Restore original tool names in the output
+        if (output.toolCalls?.length) {
+            const toolsMap = input._toolsMap;
+            if (toolsMap) {
+                for (const toolCall of output.toolCalls) {
+                    const originalTool = toolsMap[toolCall.function.name];
+                    if (!originalTool) {
+                        throw new Error(`Tool "${toolCall.function.name}" not found in tools map`);
+                    }
+                    toolCall.function.name = originalTool.function.name;
+                }
+            }
+        }
+        super.postprocess(input, output, options);
         const { usage } = output;
         if (usage) {
-            context.usage.outputTokens += usage.outputTokens;
-            context.usage.inputTokens += usage.inputTokens;
+            options.context.usage.outputTokens += usage.outputTokens;
+            options.context.usage.inputTokens += usage.inputTokens;
         }
     }
 }

package/lib/esm/agents/guide-rail-agent.d.ts

@@ -0,0 +1,62 @@
+import type { Agent, AgentOptions, Message } from "./agent.js";
+/**
+ * Input interface for GuideRail agents
+ *
+ * GuideRail agents receive both input and expected output, allowing them to
+ * validate, transform, or control the flow of messages between other agents.
+ */
+export interface GuideRailAgentInput extends Message {
+    /**
+     * The input data to be processed
+     *
+     * This is the original message that would be sent to the target agent
+     */
+    input?: unknown;
+    /**
+     * The expected output data
+     *
+     * This is what the target agent is expected to produce, allowing
+     * the GuideRail agent to validate or transform the data flow
+     */
+    output?: unknown;
+}
+/**
+ * Output interface for GuideRail agents
+ *
+ * GuideRail agents can either allow the process to continue or abort it with a reason.
+ * This provides a mechanism for enforcing rules, validating data, and controlling
+ * the execution flow of the agent system.
+ */
+export interface GuideRailAgentOutput extends Message {
+    /**
+     * Whether to abort the current process
+     *
+     * When true, the agent system should stop the current execution flow
+     * and prevent further processing based on this input/output pair
+     *
+     * @default false
+     */
+    abort?: boolean;
+    /**
+     * Reason for aborting the process
+     *
+     * When abort is true, this provides a human-readable explanation
+     * for why the process was stopped
+     */
+    reason?: string;
+}
+/**
+ * GuideRail agent type definition
+ *
+ * GuideRail agents act as validators, transformers, or controllers for the message
+ * flow between agents. They can enforce rules, perform safety checks, ensure data
+ * quality, or implement business logic validations.
+ *
+ * Use GuideRail agents when you need to:
+ * - Validate inputs or outputs against specific criteria
+ * - Enforce security or safety policies
+ * - Implement business rules that control agent interactions
+ * - Monitor and audit agent behavior
+ */
+export type GuideRailAgent = Agent<GuideRailAgentInput, GuideRailAgentOutput>;
+export declare const guideRailAgentOptions: AgentOptions<GuideRailAgentInput, GuideRailAgentOutput>;

package/lib/esm/agents/guide-rail-agent.js

@@ -0,0 +1,11 @@
+import { z } from "zod";
+export const guideRailAgentOptions = {
+    inputSchema: z.object({
+        input: z.unknown(),
+        output: z.unknown(),
+    }),
+    outputSchema: z.object({
+        abort: z.boolean().optional().describe("Whether to abort the current process"),
+        reason: z.string().optional().describe("Reason for aborting the process"),
+    }),
+};

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

@@ -6,9 +6,8 @@ import type { RequestOptions } from "@modelcontextprotocol/sdk/shared/protocol.j
 import type { Transport } from "@modelcontextprotocol/sdk/shared/transport.js";
 import type { CallToolResult, GetPromptResult, Implementation, ReadResourceResult, Request } from "@modelcontextprotocol/sdk/types.js";
 import { type ZodType, z } from "zod";
-import type { Context } from "../aigne/context.js";
 import { type PromiseOrValue } from "../utils/type-utils.js";
-import { Agent, type AgentOptions, type Message } from "./agent.js";
+import { Agent, type AgentInvokeOptions, type AgentOptions, type Message } from "./agent.js";
 export interface MCPAgentOptions extends AgentOptions {
     client: Client;
     prompts?: MCPPrompt[];
@@ -150,10 +149,10 @@ export declare class MCPAgent extends Agent {
      * throws an error if called.
      *
      * @param _input Input message (unused)
-     * @param _context Execution context (unused)
+     * @param _options AgentInvokeOptions (unused)
      * @throws Error This method always throws an error since MCPAgent is not directly invokable
      */
-    process(_input: Message, _context?: Context): Promise<Message>;
+    process(_input: Message, _options: AgentInvokeOptions): Promise<Message>;
     /**
      * Shut down the agent and close the MCP connection.
      *

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

@@ -78,25 +78,25 @@ export class MCPAgent extends Agent {
             version: MCP_AGENT_CLIENT_VERSION,
         }, undefined, isSSEServerParameters(options) ? { transportCreator, ...options } : undefined);
         const transport = transportCreator();
-        logger.mcp(`Connecting to MCP server: ${getMCPServerString(options)}`);
+        logger.debug(`Connecting to MCP server: ${getMCPServerString(options)}`);
         await client.connect(transport);
         const mcpServer = getMCPServerName(client);
         const { tools: isToolsAvailable, prompts: isPromptsAvailable, resources: isResourcesAvailable, } = client.getServerCapabilities() ?? {};
-        logger.mcp(`Listing tools from ${mcpServer}`);
+        logger.debug(`Listing tools from ${mcpServer}`);
         const skills = isToolsAvailable
             ? await client.listTools().then(({ tools }) => {
-                logger.mcp(`Listing tools from ${mcpServer} completed %O`, tools?.map((i) => i.name));
+                logger.debug(`Listing tools from ${mcpServer} completed %O`, tools?.map((i) => i.name));
                 return tools.map((tool) => toolFromMCPTool(tool, { client }));
             })
             : undefined;
-        logger.mcp(`Listing prompts from ${mcpServer}`);
+        logger.debug(`Listing prompts from ${mcpServer}`);
         const prompts = isPromptsAvailable
             ? await client.listPrompts().then(({ prompts }) => {
-                logger.mcp(`Listing prompts from ${mcpServer} completed %O`, prompts?.map((i) => i.name));
+                logger.debug(`Listing prompts from ${mcpServer} completed %O`, prompts?.map((i) => i.name));
                 return prompts.map((prompt) => promptFromMCPPrompt(prompt, { client }));
             })
             : undefined;
-        logger.mcp(`Listing resources from ${mcpServer}`);
+        logger.debug(`Listing resources from ${mcpServer}`);
         // TODO: should conditionally call listResourceTemplates based on the server capabilities
         // but the capability is not correct in the current SDK version
         const resources = isResourcesAvailable
@@ -105,7 +105,7 @@ export class MCPAgent extends Agent {
                 client.listResourceTemplates().catch(() => ({ resourceTemplates: [] })),
             ]).then(([{ resources }, { resourceTemplates }]) => {
                 const result = [...resources, ...resourceTemplates].map((resource) => resourceFromMCPResource(resource, { client }));
-                logger.mcp(`Listing resources from ${mcpServer} completed %O`, result.map((i) => i.name));
+                logger.debug(`Listing resources from ${mcpServer} completed %O`, result.map((i) => i.name));
                 return result;
             })
             : undefined;
@@ -177,10 +177,10 @@ export class MCPAgent extends Agent {
      * throws an error if called.
      *
      * @param _input Input message (unused)
-     * @param _context Execution context (unused)
+     * @param _options AgentInvokeOptions (unused)
      * @throws Error This method always throws an error since MCPAgent is not directly invokable
      */
-    async process(_input, _context) {
+    async process(_input, _options) {
         throw new Error("Method not implemented.");
     }
     /**
@@ -228,7 +228,7 @@ class ClientWithReconnect extends Client {
         }, {
             retries: this.reconnectOptions?.maxReconnects ?? DEFAULT_MAX_RECONNECTS,
             shouldRetry: this.shouldReconnect,
-            onFailedAttempt: (error) => logger.mcp("Reconnect attempt failed: %O", error),
+            onFailedAttempt: (error) => logger.error("Reconnect attempt failed: %O", error),
         });
     }
     async request(request, resultSchema, options) {
@@ -241,7 +241,7 @@ class ClientWithReconnect extends Client {
         }
         catch (error) {
             if (this.shouldReconnect(error)) {
-                logger.mcp("Error occurred, reconnecting to MCP server: %O", error);
+                logger.error("Error occurred, reconnecting to MCP server: %O", error);
                 await this.reconnect();
                 return await super.request(request, resultSchema, mergedOptions);
             }

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

@@ -1,6 +1,5 @@
-import type { Context } from "../aigne/context.js";
 import { type PromiseOrValue } from "../utils/type-utils.js";
-import { Agent, type AgentOptions, type AgentProcessResult, type Message } from "./agent.js";
+import { Agent, type AgentInvokeOptions, type AgentOptions, type AgentProcessResult, type Message } from "./agent.js";
 /**
  * Defines the processing modes available for a TeamAgent.
  *
@@ -89,10 +88,10 @@ export declare class TeamAgent<I extends Message, O extends Message> extends Age
      * - In parallel mode: Process input through all agents simultaneously and combine their outputs
      *
      * @param input The message to process
-     * @param context The execution context
+     * @param options The invocation options
      * @returns A stream of message chunks that collectively form the response
      */
-    process(input: I, context: Context): PromiseOrValue<AgentProcessResult<O>>;
+    process(input: I, options: AgentInvokeOptions): PromiseOrValue<AgentProcessResult<O>>;
     /**
      * Process input sequentially through each agent in the team.
      *
@@ -103,12 +102,12 @@ export declare class TeamAgent<I extends Message, O extends Message> extends Age
      * 4. Updates the team's agent list with any changes that occurred during processing
      *
      * @param input The message to process
-     * @param context The execution context
+     * @param options The invocation options
      * @returns A stream of message chunks from all agents
      *
      * @private
      */
-    _processSequential(input: I, context: Context): PromiseOrValue<AgentProcessResult<O>>;
+    _processSequential(input: I, options: AgentInvokeOptions): PromiseOrValue<AgentProcessResult<O>>;
     /**
      * Process input in parallel through all agents in the team.
      *
@@ -118,10 +117,10 @@ export declare class TeamAgent<I extends Message, O extends Message> extends Age
      * 3. Updates the team's agent list with any changes that occurred during processing
      *
      * @param input The message to process
-     * @param context The execution context
+     * @param options The invocation options
      * @returns A stream of combined message chunks from all agents
      *
      * @private
      */
-    _processParallel(input: I, context: Context): PromiseOrValue<AgentProcessResult<O>>;
+    _processParallel(input: I, options: AgentInvokeOptions): PromiseOrValue<AgentProcessResult<O>>;
 }

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

@@ -83,15 +83,15 @@ export class TeamAgent extends Agent {
      * - In parallel mode: Process input through all agents simultaneously and combine their outputs
      *
      * @param input The message to process
-     * @param context The execution context
+     * @param options The invocation options
      * @returns A stream of message chunks that collectively form the response
      */
-    process(input, context) {
+    process(input, options) {
         switch (this.mode) {
             case ProcessMode.sequential:
-                return this._processSequential(input, context);
+                return this._processSequential(input, options);
             case ProcessMode.parallel:
-                return this._processParallel(input, context);
+                return this._processParallel(input, options);
         }
     }
     /**
@@ -104,18 +104,18 @@ export class TeamAgent extends Agent {
      * 4. Updates the team's agent list with any changes that occurred during processing
      *
      * @param input The message to process
-     * @param context The execution context
+     * @param options The invocation options
      * @returns A stream of message chunks from all agents
      *
      * @private
      */
-    async *_processSequential(input, context) {
+    async *_processSequential(input, options) {
         const output = {};
         // Clone the agents to run, so that we can update the agents list during the loop
         const agents = [...this.skills];
         const newAgents = [];
         for (const agent of agents) {
-            const [o, transferToAgent] = await context.invoke(agent, { ...input, ...output }, { returnActiveAgent: true, streaming: true });
+            const [o, transferToAgent] = await options.context.invoke(agent, { ...input, ...output }, { returnActiveAgent: true, streaming: true });
             for await (const chunk of o) {
                 yield chunk;
                 mergeAgentResponseChunk(output, chunk);
@@ -134,13 +134,13 @@ export class TeamAgent extends Agent {
      * 3. Updates the team's agent list with any changes that occurred during processing
      *
      * @param input The message to process
-     * @param context The execution context
+     * @param options The invocation options
      * @returns A stream of combined message chunks from all agents
      *
      * @private
      */
-    async *_processParallel(input, context) {
-        const result = await Promise.all(this.skills.map((agent) => context.invoke(agent, input, { returnActiveAgent: true, streaming: true })));
+    async *_processParallel(input, options) {
+        const result = await Promise.all(this.skills.map((agent) => options.context.invoke(agent, input, { returnActiveAgent: true, streaming: true })));
         const streams = result.map((i) => i[0]);
         const read = async (index, reader) => {
             const promise = reader.read();

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

@@ -1,7 +1,7 @@
 import { ReadableStream } from "node:stream/web";
 import type { Context } from "../aigne/context.js";
 import { type MessagePayload } from "../aigne/message-queue.js";
-import { Agent, type AgentOptions, type AgentProcessResult, type FunctionAgentFn, type Message } from "./agent.js";
+import { Agent, type AgentInvokeOptions, type AgentOptions, type AgentProcessResult, type FunctionAgentFn, type Message } from "./agent.js";
 export interface UserAgentOptions<I extends Message = Message, O extends Message = Message> extends AgentOptions<I, O> {
     context: Context;
     process?: FunctionAgentFn<I, O>;
@@ -14,14 +14,14 @@ export declare class UserAgent<I extends Message = Message, O extends Message =
     private _process?;
     private activeAgent?;
     protected subscribeToTopics(context: Pick<Context, "subscribe">): void;
-    protected publishToTopics(output: O, context: Context): Promise<void>;
+    protected publishToTopics(output: O, options: AgentInvokeOptions): Promise<void>;
     invoke: Agent<I, O>["invoke"];
-    process(input: I, context: Context): Promise<AgentProcessResult<O>>;
+    process(input: I, options: AgentInvokeOptions): Promise<AgentProcessResult<O>>;
     publish: Context["publish"];
     subscribe: Context["subscribe"];
     unsubscribe: Context["unsubscribe"];
     get stream(): ReadableStream<MessagePayload & {
         topic: string;
     }>;
-    protected checkAgentInvokesUsage(_context: Context): void;
+    protected checkAgentInvokesUsage(_options: AgentInvokeOptions): void;
 }

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

@@ -19,21 +19,21 @@ export class UserAgent extends Agent {
         if (this._process)
             super.subscribeToTopics(context);
     }
-    async publishToTopics(output, context) {
+    async publishToTopics(output, options) {
         if (this._process)
-            super.publishToTopics(output, context);
+            super.publishToTopics(output, options);
     }
-    invoke = ((input, context, options) => {
-        if (!context)
+    invoke = ((input, options = {}) => {
+        if (!options.context)
             this.context = this.context.newContext({ reset: true });
-        return super.invoke(input, context ?? this.context, options);
+        return super.invoke(input, { ...options, context: this.context });
     });
-    async process(input, context) {
+    async process(input, options) {
         if (this._process) {
-            return this._process(input, context);
+            return this._process(input, options);
         }
         if (this.activeAgent) {
-            const [output, agent] = await context.invoke(this.activeAgent, input, {
+            const [output, agent] = await options.context.invoke(this.activeAgent, input, {
                 returnActiveAgent: true,
                 streaming: true,
             });
@@ -44,7 +44,7 @@ export class UserAgent extends Agent {
         }
         const publicTopic = typeof this.publishTopic === "function" ? await this.publishTopic(input) : this.publishTopic;
         if (publicTopic?.length) {
-            context.publish(publicTopic, input);
+            options.context.publish(publicTopic, input);
             if (this.subscribeTopic) {
                 return this.subscribe(this.subscribeTopic).then((res) => res.message);
             }
@@ -77,7 +77,7 @@ export class UserAgent extends Agent {
             },
         });
     }
-    checkAgentInvokesUsage(_context) {
+    checkAgentInvokesUsage(_options) {
         // ignore calls usage check for UserAgent
     }
 }

package/lib/esm/aigne/aigne.d.ts

@@ -1,7 +1,8 @@
 import { Agent, type AgentResponse, type AgentResponseStream, type Message } from "../agents/agent.js";
+import { ChatModel } from "../agents/chat-model.js";
 import type { UserAgent } from "../agents/user-agent.js";
-import { ChatModel } from "../models/chat-model.js";
-import { AIGNEContext, type InvokeOptions } from "./context.js";
+import { type LoadOptions } from "../loader/index.js";
+import { AIGNEContext, type Context, type InvokeOptions, type UserContext } from "./context.js";
 import { type MessagePayload, MessageQueue, type MessageQueueListener, type Unsubscribe } from "./message-queue.js";
 import type { ContextLimits } from "./usage.js";
 /**
@@ -45,7 +46,7 @@ export interface AIGNEOptions {
  * Here's an example of how to use AIGNE with streaming response:
  * {@includeCode ../../test/aigne/aigne.test.ts#example-streaming}
  */
-export declare class AIGNE {
+export declare class AIGNE<U extends UserContext = UserContext> {
     /**
      * Loads an AIGNE instance from a directory containing an aigne.yaml file and agent definitions.
      * This static method provides a convenient way to initialize an AIGNE system from configuration files.
@@ -54,7 +55,7 @@ export declare class AIGNE {
      * @param options - Options to override the loaded configuration.
      * @returns A fully initialized AIGNE instance with configured agents and skills.
      */
-    static load(path: string, options?: AIGNEOptions): Promise<AIGNE>;
+    static load(path: string, options: AIGNEOptions & Pick<LoadOptions, "models">): Promise<AIGNE>;
     /**
      * Creates a new AIGNE instance with the specified options.
      *
@@ -110,7 +111,7 @@ export declare class AIGNE {
      *
      * @returns A new AIGNEContext instance bound to this AIGNE.
      */
-    newContext(): AIGNEContext;
+    newContext(options?: Partial<Context>): AIGNEContext;
     /**
      * Creates a user agent for consistent interactions with a specified agent.
      * This method allows you to create a wrapper around an agent for repeated invocations.
@@ -133,7 +134,7 @@ export declare class AIGNE {
      * @param options.streaming - Must be false to return a response stream
      * @returns A promise resolving to a tuple containing the agent's response and the final active agent
      */
-    invoke<I extends Message, O extends Message>(agent: Agent<I, O>, message: I | string, options: InvokeOptions & {
+    invoke<I extends Message, O extends Message>(agent: Agent<I, O>, message: I | string, options: InvokeOptions<U> & {
         returnActiveAgent: true;
         streaming?: false;
     }): Promise<[O, Agent]>;
@@ -147,7 +148,7 @@ export declare class AIGNE {
      * @param options.streaming - Must be true to return a response stream
      * @returns A promise resolving to a tuple containing the agent's response stream and a promise for the final agent
      */
-    invoke<I extends Message, O extends Message>(agent: Agent<I, O>, message: I | string, options: InvokeOptions & {
+    invoke<I extends Message, O extends Message>(agent: Agent<I, O>, message: I | string, options: InvokeOptions<U> & {
         returnActiveAgent: true;
         streaming: true;
     }): Promise<[AgentResponseStream<O>, Promise<Agent>]>;
@@ -164,7 +165,7 @@ export declare class AIGNE {
      * Here's a simple example of how to invoke an agent:
      * {@includeCode ../../test/aigne/aigne.test.ts#example-simple}
      */
-    invoke<I extends Message, O extends Message>(agent: Agent<I, O>, message: I | string, options?: InvokeOptions & {
+    invoke<I extends Message, O extends Message>(agent: Agent<I, O>, message: I | string, options?: InvokeOptions<U> & {
         returnActiveAgent?: false;
         streaming?: false;
     }): Promise<O>;
@@ -181,7 +182,7 @@ export declare class AIGNE {
      * Here's an example of how to invoke an agent with streaming response:
      * {@includeCode ../../test/aigne/aigne.test.ts#example-streaming}
      */
-    invoke<I extends Message, O extends Message>(agent: Agent<I, O>, message: I | string, options: InvokeOptions & {
+    invoke<I extends Message, O extends Message>(agent: Agent<I, O>, message: I | string, options: InvokeOptions<U> & {
         returnActiveAgent?: false;
         streaming: true;
     }): Promise<AgentResponseStream<O>>;
@@ -195,7 +196,7 @@ export declare class AIGNE {
      * @returns Either a UserAgent (when no message provided) or a promise resolving to the agent's response
      * with optional active agent information based on the provided options
      */
-    invoke<I extends Message, O extends Message>(agent: Agent<I, O>, message?: I | string, options?: InvokeOptions): UserAgent<I, O> | Promise<AgentResponse<O> | [AgentResponse<O>, Agent]>;
+    invoke<I extends Message, O extends Message>(agent: Agent<I, O>, message?: I | string, options?: InvokeOptions<U>): UserAgent<I, O> | Promise<AgentResponse<O> | [AgentResponse<O>, Agent]>;
     /**
      * Publishes a message to the message queue for inter-agent communication.
      * This method broadcasts a message to all subscribers of the specified topic(s).
@@ -203,12 +204,13 @@ export declare class AIGNE {
      *
      * @param topic - The topic or array of topics to publish the message to
      * @param payload - The message payload to be delivered to subscribers
+     * @param options - Optional configuration parameters for the publish operation
      *
      * @example
      * Here's an example of how to publish a message:
      * {@includeCode ../../test/aigne/aigne.test.ts#example-publish-message}
      */
-    publish(topic: string | string[], payload: Omit<MessagePayload, "context"> | Message | string): void;
+    publish(topic: string | string[], payload: Omit<MessagePayload, "context"> | Message | string, options?: InvokeOptions<U>): void;
     /**
      * Subscribes to receive the next message on a specific topic.
      * This overload returns a Promise that resolves with the next message published to the topic.

package/lib/esm/aigne/aigne.js

@@ -1,7 +1,7 @@
 import { z } from "zod";
 import { Agent, } from "../agents/agent.js";
+import { ChatModel } from "../agents/chat-model.js";
 import { load } from "../loader/index.js";
-import { ChatModel } from "../models/chat-model.js";
 import { checkArguments, createAccessorArray } from "../utils/type-utils.js";
 import { AIGNEContext } from "./context.js";
 import { MessageQueue, } from "./message-queue.js";
@@ -27,7 +27,7 @@ export class AIGNE {
      * @returns A fully initialized AIGNE instance with configured agents and skills.
      */
     static async load(path, options) {
-        const { model, agents, skills, ...aigne } = await load({ path });
+        const { model, agents, skills, ...aigne } = await load({ models: options.models, path });
         return new AIGNE({
             ...options,
             model: options?.model || model,
@@ -106,8 +106,8 @@ export class AIGNE {
      *
      * @returns A new AIGNEContext instance bound to this AIGNE.
      */
-    newContext() {
-        return new AIGNEContext(this);
+    newContext(options) {
+        return new AIGNEContext(this, options);
     }
     invoke(agent, message, options) {
         return new AIGNEContext(this).invoke(agent, message, options);
@@ -119,13 +119,14 @@ export class AIGNE {
      *
      * @param topic - The topic or array of topics to publish the message to
      * @param payload - The message payload to be delivered to subscribers
+     * @param options - Optional configuration parameters for the publish operation
      *
      * @example
      * Here's an example of how to publish a message:
      * {@includeCode ../../test/aigne/aigne.test.ts#example-publish-message}
      */
-    publish(topic, payload) {
-        return new AIGNEContext(this).publish(topic, payload);
+    publish(topic, payload, options) {
+        return new AIGNEContext(this).publish(topic, payload, options);
     }
     subscribe(topic, listener) {
         return this.messageQueue.subscribe(topic, listener);