@aigne/core 1.13.0 → 1.14.0

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

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

@@ -1,16 +1,33 @@
 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";
+/**
+ * Defines the processing modes available for a TeamAgent.
+ *
+ * The processing mode determines how the agents within a team are executed
+ * and how their outputs are combined.
+ */
 export declare enum ProcessMode {
     /**
      * Process the agents one by one, passing the output of each agent to the next.
+     *
+     * In sequential mode, agents execute in order, with each agent receiving the
+     * combined output from all previous agents as part of its input.
      */
     sequential = "sequential",
     /**
      * Process all agents in parallel, merging the output of all agents.
+     *
+     * In parallel mode, all agents execute simultaneously, each receiving the same
+     * initial input. Their outputs are then combined based on output key ownership.
      */
     parallel = "parallel"
 }
+/**
+ * Configuration options for creating a TeamAgent.
+ *
+ * These options extend the base AgentOptions and add team-specific settings.
+ */
 export interface TeamAgentOptions<I extends Message, O extends Message> extends AgentOptions<I, O> {
     /**
      * The method to process the agents in the team.
@@ -18,11 +35,93 @@ export interface TeamAgentOptions<I extends Message, O extends Message> extends
      */
     mode?: ProcessMode;
 }
+/**
+ * TeamAgent coordinates a group of agents working together to accomplish tasks.
+ *
+ * A TeamAgent manages a collection of agents (its skills) and orchestrates their
+ * execution according to a specified processing mode. It provides mechanisms for
+ * agents to work either sequentially (one after another) or in parallel (all at once),
+ * with appropriate handling of their outputs.
+ *
+ * TeamAgent is particularly useful for:
+ * - Creating agent workflows where output from one agent feeds into another
+ * - Executing multiple agents simultaneously and combining their results
+ * - Building complex agent systems with specialized components working together
+ *
+ * @example
+ * Here's an example of creating a sequential TeamAgent:
+ * {@includeCode ../../test/agents/team-agent.test.ts#example-team-agent-sequential}
+ */
 export declare class TeamAgent<I extends Message, O extends Message> extends Agent<I, O> {
+    /**
+     * Create a TeamAgent from the provided options.
+     *
+     * @param options Configuration options for the TeamAgent
+     * @returns A new TeamAgent instance
+     *
+     * @example
+     * Here's an example of creating a sequential TeamAgent:
+     * {@includeCode ../../test/agents/team-agent.test.ts#example-team-agent-sequential}
+     *
+     * @example
+     * Here's an example of creating a parallel TeamAgent:
+     * {@includeCode ../../test/agents/team-agent.test.ts#example-team-agent-parallel}
+     */
     static from<I extends Message, O extends Message>(options: TeamAgentOptions<I, O>): TeamAgent<I, O>;
+    /**
+     * Create a new TeamAgent instance.
+     *
+     * @param options Configuration options for the TeamAgent
+     */
     constructor(options: TeamAgentOptions<I, O>);
+    /**
+     * The processing mode that determines how agents in the team are executed.
+     *
+     * This can be either sequential (one after another) or parallel (all at once).
+     */
     mode: ProcessMode;
+    /**
+     * Process an input message by routing it through the team's agents.
+     *
+     * Depending on the team's processing mode, this will either:
+     * - In sequential mode: Pass input through each agent in sequence, with each agent
+     *   receiving the combined output from previous agents
+     * - In parallel mode: Process input through all agents simultaneously and combine their outputs
+     *
+     * @param input The message to process
+     * @param context The execution context
+     * @returns A stream of message chunks that collectively form the response
+     */
     process(input: I, context: Context): PromiseOrValue<AgentProcessResult<O>>;
+    /**
+     * Process input sequentially through each agent in the team.
+     *
+     * This method:
+     * 1. Executes each agent in order
+     * 2. Passes the combined output from previous agents to the next agent
+     * 3. Yields output chunks as they become available
+     * 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
+     * @returns A stream of message chunks from all agents
+     *
+     * @private
+     */
     _processSequential(input: I, context: Context): PromiseOrValue<AgentProcessResult<O>>;
+    /**
+     * Process input in parallel through all agents in the team.
+     *
+     * This method:
+     * 1. Executes all agents simultaneously with the same input
+     * 2. Yields combined output chunks
+     * 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
+     * @returns A stream of combined message chunks from all agents
+     *
+     * @private
+     */
     _processParallel(input: I, context: Context): PromiseOrValue<AgentProcessResult<O>>;
 }

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

@@ -1,18 +1,20 @@
 import { ReadableStream } from "node:stream/web";
-import { type Context } from "../aigne/context.js";
-import type { MessagePayload } from "../aigne/message-queue.js";
-import { type Agent, type AgentOptions, type AgentProcessResult, FunctionAgent, type FunctionAgentFn, type Message } from "./agent.js";
+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";
 export interface UserAgentOptions<I extends Message = Message, O extends Message = Message> extends AgentOptions<I, O> {
     context: Context;
     process?: FunctionAgentFn<I, O>;
     activeAgent?: Agent;
 }
-export declare class UserAgent<I extends Message = Message, O extends Message = Message> extends FunctionAgent<I, O> {
+export declare class UserAgent<I extends Message = Message, O extends Message = Message> extends Agent<I, O> {
     static from<I extends Message, O extends Message>(options: UserAgentOptions<I, O>): UserAgent<I, O>;
     constructor(options: UserAgentOptions<I, O>);
     context: Context;
     private _process?;
     private activeAgent?;
+    protected subscribeToTopics(context: Pick<Context, "subscribe">): void;
+    protected publishToTopics(output: O, context: Context): Promise<void>;
     invoke: Agent<I, O>["invoke"];
     process(input: I, context: Context): Promise<AgentProcessResult<O>>;
     publish: Context["publish"];