@aigne/core 1.13.0 → 1.14.0

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

@@ -32,6 +32,21 @@ function getMCPServerString(options) {
     }
     return "unknown";
 }
+/**
+ * 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 class MCPAgent extends Agent {
     static from(options) {
         checkArguments("MCPAgent.from", mcpAgentOptionsSchema, options);
@@ -102,6 +117,15 @@ export class MCPAgent extends Agent {
             resources,
         });
     }
+    /**
+     * 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) {
         super(options);
         this.client = options.client;
@@ -110,17 +134,71 @@ export class MCPAgent extends Agent {
         if (options.resources?.length)
             this.resources.push(...options.resources);
     }
+    /**
+     * 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;
+    /**
+     * 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}
+     */
     prompts = createAccessorArray([], (arr, name) => arr.find((i) => i.name === name));
+    /**
+     * 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}
+     */
     resources = createAccessorArray([], (arr, name) => arr.find((i) => i.name === name));
+    /**
+     * 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() {
         return false;
     }
+    /**
+     * 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
+     */
     async process(_input, _context) {
         throw new Error("Method not implemented.");
     }
+    /**
+     * 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}
+     */
     async shutdown() {
-        super.shutdown();
+        await super.shutdown();
         await this.client.close();
     }
 }

package/lib/esm/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/esm/agents/team-agent.js

@@ -1,26 +1,91 @@
 import { mergeAgentResponseChunk, readableStreamToAsyncIterator } from "../utils/stream-utils.js";
 import { isEmpty } from "../utils/type-utils.js";
 import { Agent, } 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 var ProcessMode;
 (function (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.
      */
     ProcessMode["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.
      */
     ProcessMode["parallel"] = "parallel";
 })(ProcessMode || (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 class TeamAgent extends Agent {
+    /**
+     * 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(options) {
         return new TeamAgent(options);
     }
+    /**
+     * Create a new TeamAgent instance.
+     *
+     * @param options Configuration options for the TeamAgent
+     */
     constructor(options) {
         super(options);
         this.mode = options.mode ?? ProcessMode.sequential;
     }
+    /**
+     * 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;
+    /**
+     * 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, context) {
         switch (this.mode) {
             case ProcessMode.sequential:
@@ -29,6 +94,21 @@ export class TeamAgent extends Agent {
                 return this._processParallel(input, context);
         }
     }
+    /**
+     * 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
+     */
     async *_processSequential(input, context) {
         const output = {};
         // Clone the agents to run, so that we can update the agents list during the loop
@@ -45,6 +125,20 @@ export class TeamAgent extends Agent {
         this.skills.splice(0);
         this.skills.push(...newAgents);
     }
+    /**
+     * 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
+     */
     async *_processParallel(input, context) {
         const result = await Promise.all(this.skills.map((agent) => context.invoke(agent, input, { returnActiveAgent: true, streaming: true })));
         const streams = result.map((i) => i[0]);

package/lib/esm/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"];

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

@@ -1,8 +1,8 @@
 import { ReadableStream } from "node:stream/web";
-import { createPublishMessage } from "../aigne/context.js";
+import { toMessagePayload } from "../aigne/message-queue.js";
 import { orArrayToArray } from "../utils/type-utils.js";
-import { FunctionAgent, } from "./agent.js";
-export class UserAgent extends FunctionAgent {
+import { Agent, } from "./agent.js";
+export class UserAgent extends Agent {
     static from(options) {
         return new UserAgent(options);
     }
@@ -15,6 +15,14 @@ export class UserAgent extends FunctionAgent {
     context;
     _process;
     activeAgent;
+    subscribeToTopics(context) {
+        if (this._process)
+            super.subscribeToTopics(context);
+    }
+    async publishToTopics(output, context) {
+        if (this._process)
+            super.publishToTopics(output, context);
+    }
     invoke = ((input, context, options) => {
         if (!context)
             this.context = this.context.newContext({ reset: true });
@@ -36,13 +44,16 @@ export class UserAgent extends FunctionAgent {
         }
         const publicTopic = typeof this.publishTopic === "function" ? await this.publishTopic(input) : this.publishTopic;
         if (publicTopic?.length) {
-            context.publish(publicTopic, createPublishMessage(input, this));
+            context.publish(publicTopic, input);
+            if (this.subscribeTopic) {
+                return this.subscribe(this.subscribeTopic).then((res) => res.message);
+            }
             return {};
         }
         throw new Error("UserAgent must have a process function or a publishTopic");
     }
-    publish = ((...args) => {
-        return this.context.publish(...args);
+    publish = ((topic, payload) => {
+        return this.context.publish(topic, toMessagePayload(payload, { role: "user", source: this.name }));
     });
     subscribe = ((...args) => {
         return this.context.subscribe(...args);