@aigne/core 1.15.0 → 1.17.0

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

@@ -1,9 +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 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
      *
@@ -98,7 +99,21 @@ export interface AgentOptions<I extends Message = Message, O extends Message = M
 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
      *
@@ -139,6 +154,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
      *
@@ -248,7 +292,7 @@ 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;
@@ -260,7 +304,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
      *
@@ -268,7 +311,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>;
     /**
@@ -279,7 +322,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
      *
@@ -287,7 +329,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>>;
     /**
@@ -296,11 +338,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>>;
+    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
      *
@@ -308,7 +350,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;
@@ -318,8 +360,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
-     * @throws Always throws the received error
+     * @param options Invocation options
      */
     private processAgentError;
     /**
@@ -328,10 +369,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
      *
@@ -340,9 +381,27 @@ 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): void;
+    protected preprocess(_: I, options: AgentInvokeOptions): Promise<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
      *
@@ -352,10 +411,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): 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
      *
@@ -367,7 +426,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
@@ -386,7 +445,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
      *
@@ -419,6 +478,86 @@ 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: {
+        context: Context;
+        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<{
+        context: Context;
+        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: {
+        context: Context;
+        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<{
+        context: Context;
+        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: {
+        context: Context;
+        source: Agent;
+        target: Agent;
+        input: I;
+    }) => PromiseOrValue<void>;
+}
 /**
  * Response type for an agent, can be:
  * - Direct response object
@@ -427,7 +566,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
  *
@@ -464,7 +603,7 @@ export interface AgentResponseDelta<T> {
         }> | Partial<{
             [key: string]: string;
         }>;
-        json?: Partial<T | TransferAgentOutput>;
+        json?: Partial<T> | TransferAgentOutput;
     };
 }
 /**
@@ -496,7 +635,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
@@ -586,10 +725,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
@@ -602,4 +741,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>>;

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

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

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

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

package/lib/dts/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/dts/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/dts/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>>;
 }