@aigne/core 1.13.0 → 1.14.0

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

@@ -1,70 +1,228 @@
-import { z } from "zod";
+import { type ZodObject, type ZodType, z } from "zod";
 import type { Context } from "../aigne/context.js";
+import { type DefaultMemoryOptions } from "../memory/default-memory.js";
 import { ChatModel } from "../models/chat-model.js";
 import type { ChatModelInput } from "../models/chat-model.js";
 import { PromptBuilder } from "../prompt/prompt-builder.js";
 import { Agent, type AgentOptions, type AgentProcessAsyncGenerator, type Message } from "./agent.js";
-export interface AIAgentOptions<I extends Message = Message, O extends Message = Message> extends AgentOptions<I, O> {
+/**
+ * Configuration options for an AI Agent
+ *
+ * These options extend the base agent options with AI-specific parameters
+ * like model configuration, prompt instructions, and tool choice.
+ *
+ * @template I The input message type the agent accepts
+ * @template O The output message type the agent returns
+ */
+export interface AIAgentOptions<I extends Message = Message, O extends Message = Message> extends Omit<AgentOptions<I, O>, "memory"> {
+    /**
+     * The language model to use for this agent
+     *
+     * If not provided, the agent will use the model from the context
+     */
     model?: ChatModel;
+    /**
+     * Instructions to guide the AI model's behavior
+     *
+     * Can be a simple string or a full PromptBuilder instance for
+     * more complex prompt templates
+     */
     instructions?: string | PromptBuilder;
+    /**
+     * Custom key to use for text output in the response
+     *
+     * Defaults to $message if not specified
+     */
     outputKey?: string;
-    toolChoice?: AIAgentToolChoice;
+    /**
+     * Controls how the agent uses tools during execution
+     *
+     * @default AIAgentToolChoice.auto
+     */
+    toolChoice?: AIAgentToolChoice | Agent;
+    /**
+     * Whether to catch errors from tool execution and continue processing.
+     * If set to false, the agent will throw an error if a tool fails.
+     *
+     * @default true
+     */
+    catchToolsError?: boolean;
+    /**
+     * Whether to include memory agents as tools for the AI model
+     *
+     * When set to true, memory agents will be made available as tools
+     * that the model can call directly to retrieve or store information.
+     * This enables the agent to explicitly interact with its memories.
+     *
+     * @default false
+     */
+    memoryAgentsAsTools?: boolean;
+    /**
+     * Custom prompt template for formatting memory content
+     *
+     * Allows customization of how memories are presented to the AI model.
+     * If not provided, the default template from MEMORY_MESSAGE_TEMPLATE will be used.
+     *
+     * The template receives a {{memories}} variable containing serialized memory content.
+     */
+    memoryPromptTemplate?: string;
+    memory?: AgentOptions<I, O>["memory"] | DefaultMemoryOptions | true;
 }
-export type AIAgentToolChoice = "auto" | "none" | "required" | "router" | Agent;
-export declare const aiAgentToolChoiceSchema: z.ZodUnion<[z.ZodLiteral<"auto">, z.ZodLiteral<"none">, z.ZodLiteral<"required">, z.ZodLiteral<"router">, z.ZodType<Agent<Message, Message>, z.ZodTypeDef, Agent<Message, Message>>]>;
-export declare const aiAgentOptionsSchema: z.ZodObject<{
-    model: z.ZodOptional<z.ZodType<ChatModel, z.ZodTypeDef, ChatModel>>;
-    instructions: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodType<PromptBuilder, z.ZodTypeDef, PromptBuilder>]>>;
-    outputKey: z.ZodOptional<z.ZodString>;
-    toolChoice: z.ZodOptional<z.ZodUnion<[z.ZodLiteral<"auto">, z.ZodLiteral<"none">, z.ZodLiteral<"required">, z.ZodLiteral<"router">, z.ZodType<Agent<Message, Message>, z.ZodTypeDef, Agent<Message, Message>>]>>;
-    enableHistory: z.ZodOptional<z.ZodBoolean>;
-    maxHistoryMessages: z.ZodOptional<z.ZodNumber>;
-    includeInputInOutput: z.ZodOptional<z.ZodBoolean>;
-    subscribeTopic: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodArray<z.ZodString, "many">]>>;
-    publishTopic: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodArray<z.ZodString, "many">, z.ZodFunction<z.ZodTuple<[], z.ZodUnknown>, z.ZodUnknown>]>>;
-    name: z.ZodOptional<z.ZodString>;
-    description: z.ZodOptional<z.ZodString>;
-    skills: z.ZodOptional<z.ZodArray<z.ZodUnion<[z.ZodType<Agent<Message, Message>, z.ZodTypeDef, Agent<Message, Message>>, z.ZodFunction<z.ZodTuple<[], z.ZodUnknown>, z.ZodUnknown>]>, "many">>;
-    disableLogging: z.ZodOptional<z.ZodBoolean>;
-    memory: z.ZodOptional<z.ZodUnion<[z.ZodBoolean, z.ZodAny, z.ZodAny]>>;
-}, "strip", z.ZodTypeAny, {
-    description?: string | undefined;
-    memory?: any;
-    name?: string | undefined;
-    includeInputInOutput?: boolean | undefined;
-    subscribeTopic?: string | string[] | undefined;
-    publishTopic?: string | string[] | ((...args: unknown[]) => unknown) | undefined;
-    skills?: (Agent<Message, Message> | ((...args: unknown[]) => unknown))[] | undefined;
-    toolChoice?: Agent<Message, Message> | "auto" | "none" | "required" | "router" | undefined;
-    model?: ChatModel | undefined;
-    instructions?: string | PromptBuilder | undefined;
-    outputKey?: string | undefined;
-    enableHistory?: boolean | undefined;
-    maxHistoryMessages?: number | undefined;
-    disableLogging?: boolean | undefined;
-}, {
-    description?: string | undefined;
-    memory?: any;
-    name?: string | undefined;
-    includeInputInOutput?: boolean | undefined;
-    subscribeTopic?: string | string[] | undefined;
-    publishTopic?: string | string[] | ((...args: unknown[]) => unknown) | undefined;
-    skills?: (Agent<Message, Message> | ((...args: unknown[]) => unknown))[] | undefined;
-    toolChoice?: Agent<Message, Message> | "auto" | "none" | "required" | "router" | undefined;
-    model?: ChatModel | undefined;
-    instructions?: string | PromptBuilder | undefined;
-    outputKey?: string | undefined;
-    enableHistory?: boolean | undefined;
-    maxHistoryMessages?: number | undefined;
-    disableLogging?: boolean | undefined;
+/**
+ * Tool choice options for AI agents
+ *
+ * Controls how the agent decides to use tools during execution
+ */
+export declare enum AIAgentToolChoice {
+    /**
+     * Let the model decide when to use tools
+     */
+    auto = "auto",
+    /**
+     * Disable tool usage
+     */
+    none = "none",
+    /**
+     * Force tool usage
+     */
+    required = "required",
+    /**
+     * Choose exactly one tool and route directly to it
+     */
+    router = "router"
+}
+/**
+ * Zod schema for validating AIAgentToolChoice values
+ *
+ * Used to ensure that toolChoice receives valid values
+ *
+ * @hidden
+ */
+export declare const aiAgentToolChoiceSchema: z.ZodUnion<[z.ZodNativeEnum<typeof AIAgentToolChoice>, ZodType<Agent<Message, Message>, z.ZodTypeDef, Agent<Message, Message>>]>;
+/**
+ * Zod schema for validating AIAgentOptions
+ *
+ * Extends the base agent options schema with AI-specific parameters
+ *
+ * @hidden
+ */
+export declare const aiAgentOptionsSchema: ZodObject<{
+    [key in keyof AIAgentOptions]: ZodType<AIAgentOptions[key]>;
 }>;
+/**
+ * AI-powered agent that leverages language models
+ *
+ * AIAgent connects to language models to process inputs and generate responses,
+ * with support for streaming, function calling, and tool usage.
+ *
+ * Key features:
+ * - Connect to any language model
+ * - Use customizable instructions and prompts
+ * - Execute tools/function calls
+ * - Support streaming responses
+ * - Router mode for specialized agents
+ *
+ * @template I The input message type the agent accepts
+ * @template O The output message type the agent returns
+ *
+ * @example
+ * Basic AIAgent creation:
+ * {@includeCode ../../test/agents/ai-agent.test.ts#example-ai-agent-basic}
+ */
 export declare class AIAgent<I extends Message = Message, O extends Message = Message> extends Agent<I, O> {
+    /**
+     * Create an AIAgent with the specified options
+     *
+     * Factory method that provides a convenient way to create new AI agents
+     *
+     * @param options Configuration options for the AI agent
+     * @returns A new AIAgent instance
+     *
+     * @example
+     * AI agent with custom instructions:
+     * {@includeCode ../../test/agents/ai-agent.test.ts#example-ai-agent-instructions}
+     */
     static from<I extends Message, O extends Message>(options: AIAgentOptions<I, O>): AIAgent<I, O>;
+    /**
+     * Create an AIAgent instance
+     *
+     * @param options Configuration options for the AI agent
+     */
     constructor(options: AIAgentOptions<I, O>);
+    /**
+     * The language model used by this agent
+     *
+     * If not set on the agent, the model from the context will be used
+     */
     model?: ChatModel;
+    /**
+     * Instructions for the language model
+     *
+     * Contains system messages, user templates, and other prompt elements
+     * that guide the model's behavior
+     *
+     * @example
+     * Custom prompt builder:
+     * {@includeCode ../../test/agents/ai-agent.test.ts#example-ai-agent-prompt-builder}
+     */
     instructions: PromptBuilder;
+    /**
+     * Custom key to use for text output in the response
+     *
+     * @example
+     * Setting a custom output key:
+     * {@includeCode ../../test/agents/ai-agent.test.ts#example-ai-agent-custom-output-key}
+     */
     outputKey?: string;
-    toolChoice?: AIAgentToolChoice;
+    /**
+     * Controls how the agent uses tools during execution
+     *
+     * @example
+     * Automatic tool choice:
+     * {@includeCode ../../test/agents/ai-agent.test.ts#example-ai-agent-tool-choice-auto}
+     *
+     * @example
+     * Router tool choice:
+     * {@includeCode ../../test/agents/ai-agent.test.ts#example-ai-agent-router}
+     */
+    toolChoice?: AIAgentToolChoice | Agent;
+    /**
+     * Whether to include memory agents as tools for the AI model
+     *
+     * When set to true, memory agents will be made available as tools
+     * that the model can call directly to retrieve or store information.
+     * This enables the agent to explicitly interact with its memories.
+     */
+    memoryAgentsAsTools?: boolean;
+    /**
+     * Custom prompt template for formatting memory content
+     *
+     * Allows customization of how memories are presented to the AI model.
+     * If not provided, the default template from MEMORY_MESSAGE_TEMPLATE will be used.
+     *
+     * The template receives a {{memories}} variable containing serialized memory content.
+     */
+    memoryPromptTemplate?: string;
+    /**
+     * Whether to catch error from tool execution and continue processing.
+     * If set to false, the agent will throw an error if a tool fails
+     *
+     * @default true
+     */
+    catchToolsError: boolean;
+    /**
+     * Process an input message and generate a response
+     *
+     * @protected
+     */
     process(input: I, context: Context): AgentProcessAsyncGenerator<O>;
-    processRouter(input: I, model: ChatModel, modelInput: ChatModelInput, context: Context, toolsMap: Map<string, Agent>): AgentProcessAsyncGenerator<O>;
+    /**
+     * Process router mode requests
+     *
+     * In router mode, the agent sends a single request to the model to determine
+     * which tool to use, then routes the request directly to that tool
+     *
+     * @protected
+     */
+    _processRouter(input: I, model: ChatModel, modelInput: ChatModelInput, context: Context, toolsMap: Map<string, Agent>): AgentProcessAsyncGenerator<O>;
 }

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

@@ -1,7 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.AIAgent = exports.aiAgentOptionsSchema = exports.aiAgentToolChoiceSchema = void 0;
+exports.AIAgent = exports.aiAgentOptionsSchema = exports.aiAgentToolChoiceSchema = exports.AIAgentToolChoice = void 0;
 const zod_1 = require("zod");
+const default_memory_js_1 = require("../memory/default-memory.js");
+const memory_js_1 = require("../memory/memory.js");
 const chat_model_js_1 = require("../models/chat-model.js");
 const prompt_builder_js_1 = require("../prompt/prompt-builder.js");
 const template_js_1 = require("../prompt/template.js");
@@ -9,36 +11,106 @@ const stream_utils_js_1 = require("../utils/stream-utils.js");
 const type_utils_js_1 = require("../utils/type-utils.js");
 const agent_js_1 = require("./agent.js");
 const types_js_1 = require("./types.js");
-exports.aiAgentToolChoiceSchema = zod_1.z.union([
-    zod_1.z.literal("auto"),
-    zod_1.z.literal("none"),
-    zod_1.z.literal("required"),
-    zod_1.z.literal("router"),
-    zod_1.z.instanceof(agent_js_1.Agent),
-], { message: "aiAgentToolChoice must be 'auto', 'none', 'required', 'router', or an Agent" });
-exports.aiAgentOptionsSchema = zod_1.z.object({
+/**
+ * Tool choice options for AI agents
+ *
+ * Controls how the agent decides to use tools during execution
+ */
+var AIAgentToolChoice;
+(function (AIAgentToolChoice) {
+    /**
+     * Let the model decide when to use tools
+     */
+    AIAgentToolChoice["auto"] = "auto";
+    /**
+     * Disable tool usage
+     */
+    AIAgentToolChoice["none"] = "none";
+    /**
+     * Force tool usage
+     */
+    AIAgentToolChoice["required"] = "required";
+    /**
+     * Choose exactly one tool and route directly to it
+     */
+    AIAgentToolChoice["router"] = "router";
+})(AIAgentToolChoice || (exports.AIAgentToolChoice = AIAgentToolChoice = {}));
+/**
+ * Zod schema for validating AIAgentToolChoice values
+ *
+ * Used to ensure that toolChoice receives valid values
+ *
+ * @hidden
+ */
+exports.aiAgentToolChoiceSchema = zod_1.z.union([zod_1.z.nativeEnum(AIAgentToolChoice), zod_1.z.instanceof(agent_js_1.Agent)], {
+    message: `aiAgentToolChoice must be ${Object.values(AIAgentToolChoice).join(", ")}, or an Agent`,
+});
+/**
+ * Zod schema for validating AIAgentOptions
+ *
+ * Extends the base agent options schema with AI-specific parameters
+ *
+ * @hidden
+ */
+exports.aiAgentOptionsSchema = agent_js_1.agentOptionsSchema.extend({
     model: zod_1.z.instanceof(chat_model_js_1.ChatModel).optional(),
     instructions: zod_1.z.union([zod_1.z.string(), zod_1.z.instanceof(prompt_builder_js_1.PromptBuilder)]).optional(),
     outputKey: zod_1.z.string().optional(),
     toolChoice: exports.aiAgentToolChoiceSchema.optional(),
-    enableHistory: zod_1.z.boolean().optional(),
-    maxHistoryMessages: zod_1.z.number().optional(),
-    includeInputInOutput: zod_1.z.boolean().optional(),
-    subscribeTopic: zod_1.z.union([zod_1.z.string(), zod_1.z.array(zod_1.z.string())]).optional(),
-    publishTopic: zod_1.z.union([zod_1.z.string(), zod_1.z.array(zod_1.z.string()), zod_1.z.function()]).optional(),
-    name: zod_1.z.string().optional(),
-    description: zod_1.z.string().optional(),
-    skills: zod_1.z.array(zod_1.z.union([zod_1.z.instanceof(agent_js_1.Agent), zod_1.z.function()])).optional(),
-    disableLogging: zod_1.z.boolean().optional(),
-    memory: zod_1.z.union([zod_1.z.boolean(), zod_1.z.any(), zod_1.z.any()]).optional(),
+    memoryAgentsAsTools: zod_1.z.boolean().optional(),
+    memoryPromptTemplate: zod_1.z.string().optional(),
 });
+/**
+ * AI-powered agent that leverages language models
+ *
+ * AIAgent connects to language models to process inputs and generate responses,
+ * with support for streaming, function calling, and tool usage.
+ *
+ * Key features:
+ * - Connect to any language model
+ * - Use customizable instructions and prompts
+ * - Execute tools/function calls
+ * - Support streaming responses
+ * - Router mode for specialized agents
+ *
+ * @template I The input message type the agent accepts
+ * @template O The output message type the agent returns
+ *
+ * @example
+ * Basic AIAgent creation:
+ * {@includeCode ../../test/agents/ai-agent.test.ts#example-ai-agent-basic}
+ */
 class AIAgent extends agent_js_1.Agent {
+    /**
+     * Create an AIAgent with the specified options
+     *
+     * Factory method that provides a convenient way to create new AI agents
+     *
+     * @param options Configuration options for the AI agent
+     * @returns A new AIAgent instance
+     *
+     * @example
+     * AI agent with custom instructions:
+     * {@includeCode ../../test/agents/ai-agent.test.ts#example-ai-agent-instructions}
+     */
     static from(options) {
         return new AIAgent(options);
     }
+    /**
+     * Create an AIAgent instance
+     *
+     * @param options Configuration options for the AI agent
+     */
     constructor(options) {
-        exports.aiAgentOptionsSchema.parse(options);
-        super(options);
+        super({
+            ...options,
+            memory: !options.memory
+                ? undefined
+                : Array.isArray(options.memory) || options.memory instanceof memory_js_1.MemoryAgent
+                    ? options.memory
+                    : new default_memory_js_1.DefaultMemory(options.memory === true ? {} : options.memory),
+        });
+        (0, type_utils_js_1.checkArguments)("AIAgent", exports.aiAgentOptionsSchema, options);
         this.model = options.model;
         this.instructions =
             typeof options.instructions === "string"
@@ -46,11 +118,77 @@ class AIAgent extends agent_js_1.Agent {
                 : (options.instructions ?? new prompt_builder_js_1.PromptBuilder());
         this.outputKey = options.outputKey;
         this.toolChoice = options.toolChoice;
+        this.memoryAgentsAsTools = options.memoryAgentsAsTools;
+        this.memoryPromptTemplate = options.memoryPromptTemplate;
+        if (typeof options.catchToolsError === "boolean")
+            this.catchToolsError = options.catchToolsError;
     }
+    /**
+     * The language model used by this agent
+     *
+     * If not set on the agent, the model from the context will be used
+     */
     model;
+    /**
+     * Instructions for the language model
+     *
+     * Contains system messages, user templates, and other prompt elements
+     * that guide the model's behavior
+     *
+     * @example
+     * Custom prompt builder:
+     * {@includeCode ../../test/agents/ai-agent.test.ts#example-ai-agent-prompt-builder}
+     */
     instructions;
+    /**
+     * Custom key to use for text output in the response
+     *
+     * @example
+     * Setting a custom output key:
+     * {@includeCode ../../test/agents/ai-agent.test.ts#example-ai-agent-custom-output-key}
+     */
     outputKey;
+    /**
+     * Controls how the agent uses tools during execution
+     *
+     * @example
+     * Automatic tool choice:
+     * {@includeCode ../../test/agents/ai-agent.test.ts#example-ai-agent-tool-choice-auto}
+     *
+     * @example
+     * Router tool choice:
+     * {@includeCode ../../test/agents/ai-agent.test.ts#example-ai-agent-router}
+     */
     toolChoice;
+    /**
+     * Whether to include memory agents as tools for the AI model
+     *
+     * When set to true, memory agents will be made available as tools
+     * that the model can call directly to retrieve or store information.
+     * This enables the agent to explicitly interact with its memories.
+     */
+    memoryAgentsAsTools;
+    /**
+     * Custom prompt template for formatting memory content
+     *
+     * Allows customization of how memories are presented to the AI model.
+     * If not provided, the default template from MEMORY_MESSAGE_TEMPLATE will be used.
+     *
+     * The template receives a {{memories}} variable containing serialized memory content.
+     */
+    memoryPromptTemplate;
+    /**
+     * Whether to catch error from tool execution and continue processing.
+     * If set to false, the agent will throw an error if a tool fails
+     *
+     * @default true
+     */
+    catchToolsError = true;
+    /**
+     * Process an input message and generate a response
+     *
+     * @protected
+     */
     async *process(input, context) {
         const model = this.model ?? context.model;
         if (!model)
@@ -63,7 +201,7 @@ class AIAgent extends agent_js_1.Agent {
         });
         const toolsMap = new Map(toolAgents?.map((i) => [i.name, i]));
         if (this.toolChoice === "router") {
-            yield* this.processRouter(input, model, modelInput, context, toolsMap);
+            yield* this._processRouter(input, model, modelInput, context, toolsMap);
             return;
         }
         const toolCallMessages = [];
@@ -88,7 +226,19 @@ class AIAgent extends agent_js_1.Agent {
                     if (!tool)
                         throw new Error(`Tool not found: ${call.function.name}`);
                     // NOTE: should pass both arguments (model generated) and input (user provided) to the tool
-                    const output = await context.invoke(tool, { ...call.function.arguments, ...input }, { disableTransfer: true });
+                    const output = await context
+                        .invoke(tool, { ...input, ...call.function.arguments }, { disableTransfer: true })
+                        .catch((error) => {
+                        if (!this.catchToolsError) {
+                            return Promise.reject(error);
+                        }
+                        return {
+                            isError: true,
+                            error: {
+                                message: error.message,
+                            },
+                        };
+                    });
                     // NOTE: Return transfer output immediately
                     if ((0, types_js_1.isTransferAgentOutput)(output)) {
                         return output;
@@ -114,7 +264,15 @@ class AIAgent extends agent_js_1.Agent {
             return;
         }
     }
-    async *processRouter(input, model, modelInput, context, toolsMap) {
+    /**
+     * Process router mode requests
+     *
+     * In router mode, the agent sends a single request to the model to determine
+     * which tool to use, then routes the request directly to that tool
+     *
+     * @protected
+     */
+    async *_processRouter(input, model, modelInput, context, toolsMap) {
         const { toolCalls: [call] = [], } = await context.invoke(model, modelInput);
         if (!call) {
             throw new Error("Router toolChoice requires exactly one tool to be executed");

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

@@ -42,20 +42,132 @@ export type SSEServerParameters = {
      */
     shouldReconnect?: (error: Error) => boolean;
 };
+/**
+ * MCPAgent is a specialized agent for interacting with MCP (Model Context Protocol) servers.
+ * It provides the ability to connect to remote MCP servers using different transport methods,
+ * and access their tools, prompts, and resources.
+ *
+ * MCPAgent serves as a bridge between your application and MCP servers, allowing you to:
+ * - Connect to MCP servers over HTTP/SSE or stdio
+ * - Access server tools as agent skills
+ * - Utilize server prompts and resources
+ * - Manage server connections with automatic reconnection
+ *
+ * @example
+ * Here's an example of creating an MCPAgent with SSE transport:
+ * {@includeCode ../../test/agents/mcp-agent.test.ts#example-mcp-agent-from-sse}
+ */
 export declare class MCPAgent extends Agent {
+    /**
+     * Create an MCPAgent from a connection to an SSE server.
+     *
+     * This overload establishes a Server-Sent Events connection to an MCP server
+     * and automatically discovers its available tools, prompts, and resources.
+     *
+     * @param options SSE server connection parameters
+     * @returns Promise resolving to a new MCPAgent instance
+     *
+     * @example
+     * Here's an example of creating an MCPAgent with StreamableHTTP transport:
+     * {@includeCode ../../test/agents/mcp-agent.test.ts#example-mcp-agent-from-streamable-http}
+     *
+     * @example
+     * Here's an example of creating an MCPAgent with SSE transport:
+     * {@includeCode ../../test/agents/mcp-agent.test.ts#example-mcp-agent-from-sse}
+     *
+     * @example
+     * Here's an example of creating an MCPAgent with Stdio transport:
+     * {@includeCode ../../test/agents/mcp-agent.test.ts#example-mcp-agent-from-stdio}
+     */
     static from(options: MCPServerOptions): Promise<MCPAgent>;
+    /**
+     * Create an MCPAgent from a pre-configured MCP client.
+     *
+     * This overload uses an existing MCP client instance and optionally
+     * pre-defined prompts and resources.
+     *
+     * @param options MCPAgent configuration with client instance
+     * @returns A new MCPAgent instance
+     *
+     * @example
+     * Here's an example of creating an MCPAgent with a client instance:
+     * {@includeCode ../../test/agents/mcp-agent.test.ts#example-mcp-agent-direct}
+     */
     static from(options: MCPAgentOptions): MCPAgent;
     private static fromTransport;
+    /**
+     * Create an MCPAgent instance directly with a configured client.
+     *
+     * @param options MCPAgent configuration options, including client instance
+     *
+     * @example
+     * Here's an example of creating an MCPAgent with an existing client:
+     * {@includeCode ../../test/agents/mcp-agent.test.ts#example-mcp-agent-direct}
+     */
     constructor(options: MCPAgentOptions);
+    /**
+     * The MCP client instance used for communication with the MCP server.
+     *
+     * This client manages the connection to the MCP server and provides
+     * methods for interacting with server-provided functionality.
+     */
     client: Client;
+    /**
+     * Array of MCP prompts available from the connected server.
+     *
+     * Prompts can be accessed by index or by name.
+     *
+     * @example
+     * Here's an example of accessing prompts:
+     * {@includeCode ../../test/agents/mcp-agent.test.ts#example-mcp-agent-prompts}
+     */
     readonly prompts: MCPPrompt[] & {
         [key: string]: MCPPrompt;
     };
+    /**
+     * Array of MCP resources available from the connected server.
+     *
+     * Resources can be accessed by index or by name.
+     *
+     * @example
+     * Here's an example of accessing resources:
+     * {@includeCode ../../test/agents/mcp-agent.test.ts#example-mcp-agent-resources}
+     */
     readonly resources: MCPResource[] & {
         [key: string]: MCPResource;
     };
+    /**
+     * Check if the agent is invokable.
+     *
+     * MCPAgent itself is not directly invokable as it acts as a container
+     * for tools, prompts, and resources. Always returns false.
+     */
     get isInvokable(): boolean;
+    /**
+     * Process method required by Agent interface.
+     *
+     * Since MCPAgent itself is not directly invokable, this method
+     * throws an error if called.
+     *
+     * @param _input Input message (unused)
+     * @param _context Execution context (unused)
+     * @throws Error This method always throws an error since MCPAgent is not directly invokable
+     */
     process(_input: Message, _context?: Context): Promise<Message>;
+    /**
+     * Shut down the agent and close the MCP connection.
+     *
+     * This method cleans up resources and closes the connection
+     * to the MCP server.
+     *
+     * @example
+     * Here's an example of shutting down an MCPAgent:
+     * {@includeCode ../../test/agents/mcp-agent.test.ts#example-mcp-agent-shutdown}
+     *
+     * @example
+     * Here's an example of shutting down an MCPAgent by using statement:
+     * {@includeCode ../../test/agents/mcp-agent.test.ts#example-mcp-agent-shutdown-by-using}
+     */
     shutdown(): Promise<void>;
 }
 export interface ClientWithReconnectOptions {