agent-swarm-kit 1.0.231 → 1.0.233

package/README.md

@@ -22,7 +22,11 @@ Unleash the power of collaborative AI with `agent-swarm-kit`! This library empow
 
 ## 🚀 Getting Started
 
-**Want a real-world demo?** Check out our **[Binance Candle Chat](https://github.com/tripolskypetr/agent-swarm-kit/blob/master/demo/binance-candle-chat/src/lib/swarm.ts)**—a practical example of a sales agent in action!
+> **Want a real-world demo?** Check out our **[Binance Candle Chat](https://github.com/tripolskypetr/agent-swarm-kit/blob/master/demo/binance-candle-chat/src/lib/swarm.ts)**—a practical example of a sales agent in action!
+
+### First Look
+
+Read the [briefing article by the link](https://agent-swarm.github.io/documents/app_getting-started.html)
 
 ### Installation
 

package/build/index.cjs

@@ -3339,7 +3339,7 @@ const RUN_FN = async (incoming, self) => {
         self.params.logger.debug(`ClientAgent agentName=${self.params.agentName} clientId=${self.params.clientId} run begin`, { incoming });
     self.params.onRun &&
         self.params.onRun(self.params.clientId, self.params.agentName, incoming);
-    const messages = await self.params.history.toArrayForAgent(self.params.prompt, self.params.system);
+    const messages = await self.params.history.toArrayForAgent(self.params.prompt, await self._resolveSystemPrompt());
     messages.push({
         agentName: self.params.agentName,
         content: incoming,
@@ -3634,6 +3634,29 @@ class ClientAgent {
             });
         this.params.onInit && this.params.onInit(params.clientId, params.agentName);
     }
+    /**
+     * Resolves the system prompt by combining static and dynamic system messages.
+     * Static messages are directly included from the `systemStatic` parameter, while dynamic messages
+     * are fetched asynchronously using the `systemDynamic` function.
+     *
+     * This method is used to construct the system-level context for the agent, which can include
+     * predefined static messages and dynamically generated messages based on the agent's state or configuration.
+     *
+     * @returns {Promise<string[]>} A promise that resolves to an array of system messages,
+     * including both static and dynamically generated messages.
+     */
+    async _resolveSystemPrompt() {
+        GLOBAL_CONFIG.CC_LOGGER_ENABLE_DEBUG &&
+            this.params.logger.debug(`ClientAgent agentName=${this.params.agentName} clientId=${this.params.clientId} _resolveSystemPrompt`);
+        const system = [];
+        if (this.params.systemStatic) {
+            system.push(...this.params.systemStatic);
+        }
+        if (this.params.systemDynamic) {
+            system.push(...(await this.params.systemDynamic(this.params.clientId, this.params.agentName)));
+        }
+        return system;
+    }
     /**
      * Emits the transformed output after validation, invoking callbacks and emitting events via BusService.
      * Attempts model resurrection via _resurrectModel if validation fails, throwing an error if unrecoverable.
@@ -3793,7 +3816,7 @@ class ClientAgent {
     async getCompletion(mode) {
         GLOBAL_CONFIG.CC_LOGGER_ENABLE_DEBUG &&
             this.params.logger.debug(`ClientAgent agentName=${this.params.agentName} clientId=${this.params.clientId} getCompletion`);
-        const messages = await this.params.history.toArrayForAgent(this.params.prompt, this.params.system);
+        const messages = await this.params.history.toArrayForAgent(this.params.prompt, await this._resolveSystemPrompt());
         const args = {
             clientId: this.params.clientId,
             agentName: this.params.agentName,
@@ -3837,7 +3860,7 @@ class ClientAgent {
                 agentName: this.params.agentName,
                 content: GLOBAL_CONFIG.CC_TOOL_CALL_EXCEPTION_RECOMPLETE_PROMPT,
             });
-            const messages = await this.params.history.toArrayForAgent(this.params.prompt, this.params.system);
+            const messages = await this.params.history.toArrayForAgent(this.params.prompt, await this._resolveSystemPrompt());
             const args = {
                 clientId: this.params.clientId,
                 agentName: this.params.agentName,
@@ -4175,7 +4198,7 @@ class AgentConnectionService {
          * @returns {ClientAgent} The memoized ClientAgent instance configured for the client and agent.
          */
         this.getAgent = functoolsKit.memoize(([clientId, agentName]) => `${clientId}-${agentName}`, (clientId, agentName) => {
-            const { prompt, system, tools, transform = GLOBAL_CONFIG.CC_AGENT_OUTPUT_TRANSFORM, map = GLOBAL_CONFIG.CC_AGENT_OUTPUT_MAP, maxToolCalls = GLOBAL_CONFIG.CC_MAX_TOOL_CALLS, mapToolCalls = GLOBAL_CONFIG.CC_AGENT_MAP_TOOLS, callbacks, storages, states, completion: completionName, validate = validateDefault, } = this.agentSchemaService.get(agentName);
+            const { prompt, system, systemStatic = system, systemDynamic, tools, transform = GLOBAL_CONFIG.CC_AGENT_OUTPUT_TRANSFORM, map = GLOBAL_CONFIG.CC_AGENT_OUTPUT_MAP, maxToolCalls = GLOBAL_CONFIG.CC_MAX_TOOL_CALLS, mapToolCalls = GLOBAL_CONFIG.CC_AGENT_MAP_TOOLS, callbacks, storages, states, completion: completionName, validate = validateDefault, } = this.agentSchemaService.get(agentName);
             const completion = this.completionSchemaService.get(completionName);
             this.sessionValidationService.addAgentUsage(clientId, agentName);
             storages?.forEach((storageName) => this.storageConnectionService
@@ -4194,7 +4217,8 @@ class AgentConnectionService {
                 bus: this.busService,
                 history: this.historyConnectionService.getHistory(clientId, agentName),
                 prompt,
-                system,
+                systemStatic,
+                systemDynamic,
                 transform,
                 map,
                 tools: tools?.map(this.toolSchemaService.get),

package/build/index.mjs

@@ -3337,7 +3337,7 @@ const RUN_FN = async (incoming, self) => {
         self.params.logger.debug(`ClientAgent agentName=${self.params.agentName} clientId=${self.params.clientId} run begin`, { incoming });
     self.params.onRun &&
         self.params.onRun(self.params.clientId, self.params.agentName, incoming);
-    const messages = await self.params.history.toArrayForAgent(self.params.prompt, self.params.system);
+    const messages = await self.params.history.toArrayForAgent(self.params.prompt, await self._resolveSystemPrompt());
     messages.push({
         agentName: self.params.agentName,
         content: incoming,
@@ -3632,6 +3632,29 @@ class ClientAgent {
             });
         this.params.onInit && this.params.onInit(params.clientId, params.agentName);
     }
+    /**
+     * Resolves the system prompt by combining static and dynamic system messages.
+     * Static messages are directly included from the `systemStatic` parameter, while dynamic messages
+     * are fetched asynchronously using the `systemDynamic` function.
+     *
+     * This method is used to construct the system-level context for the agent, which can include
+     * predefined static messages and dynamically generated messages based on the agent's state or configuration.
+     *
+     * @returns {Promise<string[]>} A promise that resolves to an array of system messages,
+     * including both static and dynamically generated messages.
+     */
+    async _resolveSystemPrompt() {
+        GLOBAL_CONFIG.CC_LOGGER_ENABLE_DEBUG &&
+            this.params.logger.debug(`ClientAgent agentName=${this.params.agentName} clientId=${this.params.clientId} _resolveSystemPrompt`);
+        const system = [];
+        if (this.params.systemStatic) {
+            system.push(...this.params.systemStatic);
+        }
+        if (this.params.systemDynamic) {
+            system.push(...(await this.params.systemDynamic(this.params.clientId, this.params.agentName)));
+        }
+        return system;
+    }
     /**
      * Emits the transformed output after validation, invoking callbacks and emitting events via BusService.
      * Attempts model resurrection via _resurrectModel if validation fails, throwing an error if unrecoverable.
@@ -3791,7 +3814,7 @@ class ClientAgent {
     async getCompletion(mode) {
         GLOBAL_CONFIG.CC_LOGGER_ENABLE_DEBUG &&
             this.params.logger.debug(`ClientAgent agentName=${this.params.agentName} clientId=${this.params.clientId} getCompletion`);
-        const messages = await this.params.history.toArrayForAgent(this.params.prompt, this.params.system);
+        const messages = await this.params.history.toArrayForAgent(this.params.prompt, await this._resolveSystemPrompt());
         const args = {
             clientId: this.params.clientId,
             agentName: this.params.agentName,
@@ -3835,7 +3858,7 @@ class ClientAgent {
                 agentName: this.params.agentName,
                 content: GLOBAL_CONFIG.CC_TOOL_CALL_EXCEPTION_RECOMPLETE_PROMPT,
             });
-            const messages = await this.params.history.toArrayForAgent(this.params.prompt, this.params.system);
+            const messages = await this.params.history.toArrayForAgent(this.params.prompt, await this._resolveSystemPrompt());
             const args = {
                 clientId: this.params.clientId,
                 agentName: this.params.agentName,
@@ -4173,7 +4196,7 @@ class AgentConnectionService {
          * @returns {ClientAgent} The memoized ClientAgent instance configured for the client and agent.
          */
         this.getAgent = memoize(([clientId, agentName]) => `${clientId}-${agentName}`, (clientId, agentName) => {
-            const { prompt, system, tools, transform = GLOBAL_CONFIG.CC_AGENT_OUTPUT_TRANSFORM, map = GLOBAL_CONFIG.CC_AGENT_OUTPUT_MAP, maxToolCalls = GLOBAL_CONFIG.CC_MAX_TOOL_CALLS, mapToolCalls = GLOBAL_CONFIG.CC_AGENT_MAP_TOOLS, callbacks, storages, states, completion: completionName, validate = validateDefault, } = this.agentSchemaService.get(agentName);
+            const { prompt, system, systemStatic = system, systemDynamic, tools, transform = GLOBAL_CONFIG.CC_AGENT_OUTPUT_TRANSFORM, map = GLOBAL_CONFIG.CC_AGENT_OUTPUT_MAP, maxToolCalls = GLOBAL_CONFIG.CC_MAX_TOOL_CALLS, mapToolCalls = GLOBAL_CONFIG.CC_AGENT_MAP_TOOLS, callbacks, storages, states, completion: completionName, validate = validateDefault, } = this.agentSchemaService.get(agentName);
             const completion = this.completionSchemaService.get(completionName);
             this.sessionValidationService.addAgentUsage(clientId, agentName);
             storages?.forEach((storageName) => this.storageConnectionService
@@ -4192,7 +4215,8 @@ class AgentConnectionService {
                 bus: this.busService,
                 history: this.historyConnectionService.getHistory(clientId, agentName),
                 prompt,
-                system,
+                systemStatic,
+                systemDynamic,
                 transform,
                 map,
                 tools: tools?.map(this.toolSchemaService.get),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-swarm-kit",
-  "version": "1.0.231",
+  "version": "1.0.233",
   "description": "A TypeScript library for building orchestrated framework-agnostic multi-agent AI systems",
   "author": {
     "name": "Petr Tripolsky",

package/types.d.ts

@@ -3014,6 +3014,7 @@ interface IAgentTool<T = Record<string, ToolValue>> extends ITool {
  * @extends {IAgentSchemaCallbacks}
  */
 interface IAgentParams extends Omit<IAgentSchema, keyof {
+    system: never;
     tools: never;
     completion: never;
     validate: never;
@@ -3153,6 +3154,10 @@ interface IAgentSchema {
     prompt: string;
     /** Optional array of system prompts, typically used for tool-calling protocols. */
     system?: string[];
+    /** Optional array of system prompts, alias for `system` */
+    systemStatic?: string[];
+    /** Optional dynamic array of system prompts from the callback */
+    systemDynamic?: (clientId: string, agentName: AgentName) => (Promise<string[]> | string[]);
     /** Optional array of tool names available to the agent. */
     tools?: ToolName[];
     /** Optional array of storage names utilized by the agent. */
@@ -3573,6 +3578,18 @@ declare class ClientAgent implements IAgent {
      * @param {IAgentParams} params - The parameters for agent initialization, including clientId, agentName, completion, tools, etc.
      */
     constructor(params: IAgentParams);
+    /**
+     * Resolves the system prompt by combining static and dynamic system messages.
+     * Static messages are directly included from the `systemStatic` parameter, while dynamic messages
+     * are fetched asynchronously using the `systemDynamic` function.
+     *
+     * This method is used to construct the system-level context for the agent, which can include
+     * predefined static messages and dynamically generated messages based on the agent's state or configuration.
+     *
+     * @returns {Promise<string[]>} A promise that resolves to an array of system messages,
+     * including both static and dynamically generated messages.
+     */
+    _resolveSystemPrompt(): Promise<string[]>;
     /**
      * Emits the transformed output after validation, invoking callbacks and emitting events via BusService.
      * Attempts model resurrection via _resurrectModel if validation fails, throwing an error if unrecoverable.