@aigne/core 1.31.0 → 1.32.1

package/CHANGELOG.md

@@ -12,6 +12,35 @@
   * dependencies
     * @aigne/observability bumped to 0.1.0
 
+## [1.32.1](https://github.com/AIGNE-io/aigne-framework/compare/core-v1.32.0...core-v1.32.1) (2025-07-09)
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @aigne/observability-api bumped to 0.7.0
+
+## [1.32.0](https://github.com/AIGNE-io/aigne-framework/compare/core-v1.31.0...core-v1.32.0) (2025-07-08)
+
+
+### Features
+
+* **core:** add jinja syntax support for prompt builder ([#230](https://github.com/AIGNE-io/aigne-framework/issues/230)) ([74436a7](https://github.com/AIGNE-io/aigne-framework/commit/74436a7faac0c59a32b0153481386162649f4357))
+* support setting component id to different component data ([#226](https://github.com/AIGNE-io/aigne-framework/issues/226)) ([c7b3224](https://github.com/AIGNE-io/aigne-framework/commit/c7b32240e6660f34974615bcb9b91978a1191e3e))
+
+
+### Bug Fixes
+
+* **core:** ensure output is a record type ([#228](https://github.com/AIGNE-io/aigne-framework/issues/228)) ([dfd9104](https://github.com/AIGNE-io/aigne-framework/commit/dfd910451e5f1f9edd94a719857e36d34fadbe45))
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @aigne/observability-api bumped to 0.6.0
+
 ## [1.31.0](https://github.com/AIGNE-io/aigne-framework/compare/core-v1.30.0...core-v1.31.0) (2025-07-04)
 
 

package/lib/cjs/agents/agent.js

@@ -394,6 +394,9 @@ class Agent {
      */
     async processAgentOutput(input, output, options) {
         const { context } = options;
+        if (!(0, type_utils_js_1.isRecord)(output)) {
+            throw new Error(`expect to return a record type such as {result: ...}, but got (${typeof output}): ${output}`);
+        }
         const parsedOutput = (0, type_utils_js_1.checkArguments)(`Agent ${this.name} output`, this.outputSchema, output);
         const finalOutput = this.includeInputInOutput ? { ...input, ...parsedOutput } : parsedOutput;
         await this.postprocess(input, finalOutput, options);

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

@@ -286,7 +286,7 @@ class AIAgent extends agent_js_1.Agent {
                 }
                 // Continue LLM function calling loop if any tools were executed
                 if (executedToolCalls.length) {
-                    toolCallMessages.push(template_js_1.AgentMessageTemplate.from(undefined, executedToolCalls.map(({ call }) => call)).format(), ...executedToolCalls.map(({ call, output }) => template_js_1.ToolMessageTemplate.from(output, call.id).format()));
+                    toolCallMessages.push(await template_js_1.AgentMessageTemplate.from(undefined, executedToolCalls.map(({ call }) => call)).format(), ...(await Promise.all(executedToolCalls.map(({ call, output }) => template_js_1.ToolMessageTemplate.from(output, call.id).format()))));
                     continue;
                 }
             }

package/lib/cjs/aigne/context.js

@@ -237,22 +237,12 @@ class AIGNEContext {
                         span.setAttribute("output", JSON.stringify({}));
                     }
                     span.setStatus({ code: api_1.SpanStatusCode.OK });
-                    await this.observer?.traceExporter
-                        ?.upsertInitialSpan?.(span)
-                        .catch((err) => {
-                        logger_js_1.logger.error("upsertInitialSpan error", err?.message || err);
-                    });
                     span.end();
                     break;
                 }
                 case "agentFailed": {
                     const { error } = args[0];
                     span.setStatus({ code: api_1.SpanStatusCode.ERROR, message: error.message });
-                    await this.observer?.traceExporter
-                        ?.upsertInitialSpan?.(span)
-                        .catch((err) => {
-                        logger_js_1.logger.error("upsertInitialSpan error", err?.message || err);
-                    });
                     span.end();
                     break;
                 }

package/lib/cjs/loader/index.js

@@ -12,6 +12,7 @@ const ai_agent_js_1 = require("../agents/ai-agent.js");
 const mcp_agent_js_1 = require("../agents/mcp-agent.js");
 const team_agent_js_1 = require("../agents/team-agent.js");
 const transform_agent_js_1 = require("../agents/transform-agent.js");
+const prompt_builder_js_1 = require("../prompt/prompt-builder.js");
 const type_utils_js_1 = require("../utils/type-utils.js");
 const agent_js_js_1 = require("./agent-js.js");
 const agent_yaml_js_1 = require("./agent-yaml.js");
@@ -61,6 +62,8 @@ async function parseAgent(path, agent, options) {
         case "ai": {
             return ai_agent_js_1.AIAgent.from({
                 ...agent,
+                instructions: agent.instructions &&
+                    prompt_builder_js_1.PromptBuilder.from(agent.instructions, { workingDir: index_js_1.nodejs.path.dirname(path) }),
                 memory,
                 skills,
             });

package/lib/cjs/prompt/prompt-builder.d.ts

@@ -5,6 +5,7 @@ import type { ChatModel, ChatModelInput } from "../agents/chat-model.js";
 import { ChatMessagesTemplate } from "./template.js";
 export interface PromptBuilderOptions {
     instructions?: string | ChatMessagesTemplate;
+    workingDir?: string;
 }
 export interface PromptBuildOptions extends Partial<Pick<AgentInvokeOptions, "context">> {
     agent?: AIAgent;
@@ -15,11 +16,14 @@ export interface PromptBuildOptions extends Partial<Pick<AgentInvokeOptions, "co
 export declare class PromptBuilder {
     static from(instructions: string | {
         path: string;
-    } | GetPromptResult): PromptBuilder;
+    } | GetPromptResult, { workingDir }?: {
+        workingDir?: string;
+    }): PromptBuilder;
     private static fromFile;
     private static fromMCPPromptResult;
     constructor(options?: PromptBuilderOptions);
     instructions?: string | ChatMessagesTemplate;
+    workingDir?: string;
     build(options: PromptBuildOptions): Promise<ChatModelInput & {
         toolAgents?: Agent[];
     }>;

package/lib/cjs/prompt/prompt-builder.js

@@ -12,18 +12,18 @@ const memory_message_template_js_1 = require("./prompts/memory-message-template.
 const structured_stream_instructions_js_1 = require("./prompts/structured-stream-instructions.js");
 const template_js_1 = require("./template.js");
 class PromptBuilder {
-    static from(instructions) {
+    static from(instructions, { workingDir } = {}) {
         if (typeof instructions === "string")
-            return new PromptBuilder({ instructions });
+            return new PromptBuilder({ instructions, workingDir: workingDir });
         if (isFromPromptResult(instructions))
             return PromptBuilder.fromMCPPromptResult(instructions);
         if (isFromPath(instructions))
-            return PromptBuilder.fromFile(instructions.path);
+            return PromptBuilder.fromFile(instructions.path, { workingDir });
         throw new Error(`Invalid instructions ${instructions}`);
     }
-    static fromFile(path) {
+    static fromFile(path, { workingDir }) {
         const text = index_js_1.nodejs.fsSync.readFileSync(path, "utf-8");
-        return PromptBuilder.from(text);
+        return PromptBuilder.from(text, { workingDir: workingDir || index_js_1.nodejs.path.dirname(path) });
     }
     static fromMCPPromptResult(result) {
         return new PromptBuilder({
@@ -55,8 +55,10 @@ class PromptBuilder {
     }
     constructor(options) {
         this.instructions = options?.instructions;
+        this.workingDir = options?.workingDir;
     }
     instructions;
+    workingDir;
     async build(options) {
         return {
             messages: await this.buildMessages(options),
@@ -70,9 +72,9 @@ class PromptBuilder {
         const { input } = options;
         const inputKey = options.agent?.inputKey;
         const message = inputKey && typeof input?.[inputKey] === "string" ? input[inputKey] : undefined;
-        const messages = (typeof this.instructions === "string"
+        const messages = (await (typeof this.instructions === "string"
             ? template_js_1.ChatMessagesTemplate.from([template_js_1.SystemMessageTemplate.from(this.instructions)])
-            : this.instructions)?.format(options.input) ?? [];
+            : this.instructions)?.format(options.input, { workingDir: this.workingDir })) ?? [];
         const memories = [];
         if (options.agent && options.context) {
             memories.push(...(await options.agent.retrieveMemories({ search: message }, { context: options.context })));
@@ -81,7 +83,7 @@ class PromptBuilder {
             memories.push(...options.context.memories);
         }
         if (memories.length)
-            messages.push(...this.convertMemoriesToMessages(memories, options));
+            messages.push(...(await this.convertMemoriesToMessages(memories, options)));
         // if the agent is using structured stream mode, add the instructions
         const { structuredStreamMode, outputSchema } = options.agent || {};
         if (structuredStreamMode && outputSchema) {
@@ -102,7 +104,7 @@ class PromptBuilder {
         }
         return messages;
     }
-    convertMemoriesToMessages(memories, options) {
+    async convertMemoriesToMessages(memories, options) {
         const messages = [];
         const other = [];
         const stringOrStringify = (value) => typeof value === "string" ? value : (0, yaml_1.stringify)(value);
@@ -117,7 +119,7 @@ class PromptBuilder {
         if (other.length) {
             messages.unshift({
                 role: "system",
-                content: template_js_1.PromptTemplate.from(options.agent?.memoryPromptTemplate || memory_message_template_js_1.MEMORY_MESSAGE_TEMPLATE).format({ memories: (0, yaml_1.stringify)(other) }),
+                content: await template_js_1.PromptTemplate.from(options.agent?.memoryPromptTemplate || memory_message_template_js_1.MEMORY_MESSAGE_TEMPLATE).format({ memories: (0, yaml_1.stringify)(other) }),
             });
         }
         return messages;

package/lib/cjs/prompt/template.d.ts

@@ -1,16 +1,30 @@
+import nunjucks, { type Callback, type LoaderSource } from "nunjucks";
 import type { ChatModelInputMessage, ChatModelInputMessageContent, ChatModelOutputToolCall } from "../agents/chat-model.js";
+export interface FormatOptions {
+    workingDir?: string;
+}
 export declare class PromptTemplate {
     template: string;
     static from(template: string): PromptTemplate;
     constructor(template: string);
-    format(variables?: Record<string, unknown>): string;
+    format(variables?: Record<string, unknown>, options?: FormatOptions): Promise<string>;
+}
+export declare class CustomLoader extends nunjucks.Loader {
+    options: {
+        workingDir: string;
+    };
+    constructor(options: {
+        workingDir: string;
+    });
+    async: boolean;
+    getSource(name: string, callback: Callback<Error, LoaderSource>): LoaderSource;
 }
 export declare class ChatMessageTemplate {
     role: "system" | "user" | "agent" | "tool";
     content?: ChatModelInputMessage["content"];
     name?: string | undefined;
     constructor(role: "system" | "user" | "agent" | "tool", content?: ChatModelInputMessage["content"], name?: string | undefined);
-    format(variables?: Record<string, unknown>): ChatModelInputMessage;
+    format(variables?: Record<string, unknown>, options?: FormatOptions): Promise<ChatModelInputMessage>;
 }
 export declare class SystemMessageTemplate extends ChatMessageTemplate {
     static from(content: string, name?: string): SystemMessageTemplate;
@@ -22,19 +36,19 @@ export declare class AgentMessageTemplate extends ChatMessageTemplate {
     toolCalls?: ChatModelOutputToolCall[] | undefined;
     static from(template?: ChatModelInputMessage["content"], toolCalls?: ChatModelOutputToolCall[], name?: string): AgentMessageTemplate;
     constructor(content?: ChatModelInputMessage["content"], toolCalls?: ChatModelOutputToolCall[] | undefined, name?: string);
-    format(variables?: Record<string, unknown>): {
+    format(variables?: Record<string, unknown>, options?: FormatOptions): Promise<{
         toolCalls: ChatModelOutputToolCall[] | undefined;
         role: import("../agents/chat-model.js").Role;
         content?: ChatModelInputMessageContent;
         toolCallId?: string;
         name?: string;
-    };
+    }>;
 }
 export declare class ToolMessageTemplate extends ChatMessageTemplate {
     toolCallId: string;
     static from(content: object | string, toolCallId: string, name?: string): ToolMessageTemplate;
     constructor(content: object | string, toolCallId: string, name?: string);
-    format(variables?: Record<string, unknown>): {
+    format(variables?: Record<string, unknown>, options?: FormatOptions): Promise<{
         toolCallId: string;
         role: import("../agents/chat-model.js").Role;
         content?: ChatModelInputMessageContent;
@@ -47,12 +61,12 @@ export declare class ToolMessageTemplate extends ChatMessageTemplate {
             };
         }[];
         name?: string;
-    };
+    }>;
 }
 export declare class ChatMessagesTemplate {
     messages: ChatMessageTemplate[];
     static from(messages: ChatMessageTemplate[] | string): ChatMessagesTemplate;
     constructor(messages: ChatMessageTemplate[]);
-    format(variables?: Record<string, unknown>): ChatModelInputMessage[];
+    format(variables?: Record<string, unknown>, options?: FormatOptions): Promise<ChatModelInputMessage[]>;
 }
 export declare function parseChatMessages(messages: unknown): ChatMessageTemplate[] | undefined;

package/lib/cjs/prompt/template.js

@@ -3,10 +3,17 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ChatMessagesTemplate = exports.ToolMessageTemplate = exports.AgentMessageTemplate = exports.UserMessageTemplate = exports.SystemMessageTemplate = exports.ChatMessageTemplate = exports.PromptTemplate = void 0;
+exports.ChatMessagesTemplate = exports.ToolMessageTemplate = exports.AgentMessageTemplate = exports.UserMessageTemplate = exports.SystemMessageTemplate = exports.ChatMessageTemplate = exports.CustomLoader = exports.PromptTemplate = void 0;
 exports.parseChatMessages = parseChatMessages;
-const mustache_1 = __importDefault(require("mustache"));
+const index_js_1 = require("@aigne/platform-helpers/nodejs/index.js");
+const nunjucks_1 = __importDefault(require("nunjucks"));
 const zod_1 = require("zod");
+const type_utils_js_1 = require("../utils/type-utils.js");
+nunjucks_1.default.runtime.suppressValue = (v) => {
+    if ((0, type_utils_js_1.isNil)(v))
+        return "";
+    return typeof v === "object" ? JSON.stringify(v) : v;
+};
 class PromptTemplate {
     template;
     static from(template) {
@@ -15,15 +22,46 @@ class PromptTemplate {
     constructor(template) {
         this.template = template;
     }
-    format(variables) {
-        return mustache_1.default.render(this.template, variables, undefined, {
-            escape: (v) => {
-                return typeof v === "object" ? JSON.stringify(v) : v;
-            },
-        });
+    async format(variables = {}, options) {
+        let env = new nunjucks_1.default.Environment();
+        if (options?.workingDir) {
+            env = new nunjucks_1.default.Environment(new CustomLoader({ workingDir: options.workingDir }));
+        }
+        return new Promise((resolve, reject) => env.renderString(this.template, variables, (err, res) => {
+            if (err || !res) {
+                reject(err || new Error(`Failed to render template: ${this.template}`));
+            }
+            else {
+                resolve(res);
+            }
+        }));
     }
 }
 exports.PromptTemplate = PromptTemplate;
+class CustomLoader extends nunjucks_1.default.Loader {
+    options;
+    constructor(options) {
+        super();
+        this.options = options;
+    }
+    async = true;
+    getSource(name, callback) {
+        let result = null;
+        index_js_1.nodejs.fs.readFile(index_js_1.nodejs.path.join(this.options.workingDir, name), "utf-8").then((content) => {
+            result = {
+                src: content,
+                path: name,
+                noCache: true,
+            };
+            callback(null, result);
+        }, (error) => {
+            callback(error, null);
+        });
+        // nunjucks expects return LoaderSource synchronously, but we handle it asynchronously.
+        return result;
+    }
+}
+exports.CustomLoader = CustomLoader;
 class ChatMessageTemplate {
     role;
     content;
@@ -33,17 +71,17 @@ class ChatMessageTemplate {
         this.content = content;
         this.name = name;
     }
-    format(variables) {
+    async format(variables, options) {
         let { content } = this;
         if (Array.isArray(content)) {
-            content = content.map((i) => {
+            content = await Promise.all(content.map(async (i) => {
                 if (i.type === "text")
-                    return { ...i, text: PromptTemplate.from(i.text).format(variables) };
+                    return { ...i, text: await PromptTemplate.from(i.text).format(variables, options) };
                 return i;
-            });
+            }));
         }
         else if (typeof content === "string") {
-            content = PromptTemplate.from(content).format(variables);
+            content = await PromptTemplate.from(content).format(variables, options);
         }
         return {
             role: this.role,
@@ -74,9 +112,9 @@ class AgentMessageTemplate extends ChatMessageTemplate {
         super("agent", content, name);
         this.toolCalls = toolCalls;
     }
-    format(variables) {
+    async format(variables, options) {
         return {
-            ...super.format(variables),
+            ...(await super.format(variables, options)),
             toolCalls: this.toolCalls,
         };
     }
@@ -93,9 +131,9 @@ class ToolMessageTemplate extends ChatMessageTemplate {
             : JSON.stringify(content, (_, value) => typeof value === "bigint" ? value.toString() : value), name);
         this.toolCallId = toolCallId;
     }
-    format(variables) {
+    async format(variables, options) {
         return {
-            ...super.format(variables),
+            ...(await super.format(variables, options)),
             toolCallId: this.toolCallId,
         };
     }
@@ -109,8 +147,8 @@ class ChatMessagesTemplate {
     constructor(messages) {
         this.messages = messages;
     }
-    format(variables) {
-        return this.messages.map((message) => message.format(variables));
+    async format(variables, options) {
+        return Promise.all(this.messages.map((message) => message.format(variables, options)));
     }
 }
 exports.ChatMessagesTemplate = ChatMessagesTemplate;

package/lib/cjs/utils/stream-utils.js

@@ -21,6 +21,9 @@ const agent_js_1 = require("../agents/agent.js");
 const type_utils_js_1 = require("./type-utils.js");
 require("./stream-polyfill.js");
 function objectToAgentResponseStream(json) {
+    if (!(0, type_utils_js_1.isRecord)(json)) {
+        throw new Error(`expect to return a record type such as {result: ...}, but got (${typeof json}): ${json}`);
+    }
     return new ReadableStream({
         pull(controller) {
             controller.enqueue({ delta: { json } });

package/lib/dts/prompt/prompt-builder.d.ts

@@ -5,6 +5,7 @@ import type { ChatModel, ChatModelInput } from "../agents/chat-model.js";
 import { ChatMessagesTemplate } from "./template.js";
 export interface PromptBuilderOptions {
     instructions?: string | ChatMessagesTemplate;
+    workingDir?: string;
 }
 export interface PromptBuildOptions extends Partial<Pick<AgentInvokeOptions, "context">> {
     agent?: AIAgent;
@@ -15,11 +16,14 @@ export interface PromptBuildOptions extends Partial<Pick<AgentInvokeOptions, "co
 export declare class PromptBuilder {
     static from(instructions: string | {
         path: string;
-    } | GetPromptResult): PromptBuilder;
+    } | GetPromptResult, { workingDir }?: {
+        workingDir?: string;
+    }): PromptBuilder;
     private static fromFile;
     private static fromMCPPromptResult;
     constructor(options?: PromptBuilderOptions);
     instructions?: string | ChatMessagesTemplate;
+    workingDir?: string;
     build(options: PromptBuildOptions): Promise<ChatModelInput & {
         toolAgents?: Agent[];
     }>;

package/lib/dts/prompt/template.d.ts

@@ -1,16 +1,30 @@
+import nunjucks, { type Callback, type LoaderSource } from "nunjucks";
 import type { ChatModelInputMessage, ChatModelInputMessageContent, ChatModelOutputToolCall } from "../agents/chat-model.js";
+export interface FormatOptions {
+    workingDir?: string;
+}
 export declare class PromptTemplate {
     template: string;
     static from(template: string): PromptTemplate;
     constructor(template: string);
-    format(variables?: Record<string, unknown>): string;
+    format(variables?: Record<string, unknown>, options?: FormatOptions): Promise<string>;
+}
+export declare class CustomLoader extends nunjucks.Loader {
+    options: {
+        workingDir: string;
+    };
+    constructor(options: {
+        workingDir: string;
+    });
+    async: boolean;
+    getSource(name: string, callback: Callback<Error, LoaderSource>): LoaderSource;
 }
 export declare class ChatMessageTemplate {
     role: "system" | "user" | "agent" | "tool";
     content?: ChatModelInputMessage["content"];
     name?: string | undefined;
     constructor(role: "system" | "user" | "agent" | "tool", content?: ChatModelInputMessage["content"], name?: string | undefined);
-    format(variables?: Record<string, unknown>): ChatModelInputMessage;
+    format(variables?: Record<string, unknown>, options?: FormatOptions): Promise<ChatModelInputMessage>;
 }
 export declare class SystemMessageTemplate extends ChatMessageTemplate {
     static from(content: string, name?: string): SystemMessageTemplate;
@@ -22,19 +36,19 @@ export declare class AgentMessageTemplate extends ChatMessageTemplate {
     toolCalls?: ChatModelOutputToolCall[] | undefined;
     static from(template?: ChatModelInputMessage["content"], toolCalls?: ChatModelOutputToolCall[], name?: string): AgentMessageTemplate;
     constructor(content?: ChatModelInputMessage["content"], toolCalls?: ChatModelOutputToolCall[] | undefined, name?: string);
-    format(variables?: Record<string, unknown>): {
+    format(variables?: Record<string, unknown>, options?: FormatOptions): Promise<{
         toolCalls: ChatModelOutputToolCall[] | undefined;
         role: import("../agents/chat-model.js").Role;
         content?: ChatModelInputMessageContent;
         toolCallId?: string;
         name?: string;
-    };
+    }>;
 }
 export declare class ToolMessageTemplate extends ChatMessageTemplate {
     toolCallId: string;
     static from(content: object | string, toolCallId: string, name?: string): ToolMessageTemplate;
     constructor(content: object | string, toolCallId: string, name?: string);
-    format(variables?: Record<string, unknown>): {
+    format(variables?: Record<string, unknown>, options?: FormatOptions): Promise<{
         toolCallId: string;
         role: import("../agents/chat-model.js").Role;
         content?: ChatModelInputMessageContent;
@@ -47,12 +61,12 @@ export declare class ToolMessageTemplate extends ChatMessageTemplate {
             };
         }[];
         name?: string;
-    };
+    }>;
 }
 export declare class ChatMessagesTemplate {
     messages: ChatMessageTemplate[];
     static from(messages: ChatMessageTemplate[] | string): ChatMessagesTemplate;
     constructor(messages: ChatMessageTemplate[]);
-    format(variables?: Record<string, unknown>): ChatModelInputMessage[];
+    format(variables?: Record<string, unknown>, options?: FormatOptions): Promise<ChatModelInputMessage[]>;
 }
 export declare function parseChatMessages(messages: unknown): ChatMessageTemplate[] | undefined;

package/lib/esm/agents/agent.js

@@ -2,7 +2,7 @@ import { nodejs } from "@aigne/platform-helpers/nodejs/index.js";
 import { ZodObject, z } from "zod";
 import { logger } from "../utils/logger.js";
 import { agentResponseStreamToObject, asyncGeneratorToReadableStream, isAsyncGenerator, objectToAgentResponseStream, onAgentResponseStreamEnd, } from "../utils/stream-utils.js";
-import { checkArguments, createAccessorArray, flat, isEmpty, } from "../utils/type-utils.js";
+import { checkArguments, createAccessorArray, flat, isEmpty, isRecord, } from "../utils/type-utils.js";
 import { replaceTransferAgentToName, transferToAgentOutput, } from "./types.js";
 export * from "./types.js";
 export const agentOptionsSchema = z.object({
@@ -349,6 +349,9 @@ export class Agent {
      */
     async processAgentOutput(input, output, options) {
         const { context } = options;
+        if (!isRecord(output)) {
+            throw new Error(`expect to return a record type such as {result: ...}, but got (${typeof output}): ${output}`);
+        }
         const parsedOutput = checkArguments(`Agent ${this.name} output`, this.outputSchema, output);
         const finalOutput = this.includeInputInOutput ? { ...input, ...parsedOutput } : parsedOutput;
         await this.postprocess(input, finalOutput, options);

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

@@ -283,7 +283,7 @@ export class AIAgent extends Agent {
                 }
                 // Continue LLM function calling loop if any tools were executed
                 if (executedToolCalls.length) {
-                    toolCallMessages.push(AgentMessageTemplate.from(undefined, executedToolCalls.map(({ call }) => call)).format(), ...executedToolCalls.map(({ call, output }) => ToolMessageTemplate.from(output, call.id).format()));
+                    toolCallMessages.push(await AgentMessageTemplate.from(undefined, executedToolCalls.map(({ call }) => call)).format(), ...(await Promise.all(executedToolCalls.map(({ call, output }) => ToolMessageTemplate.from(output, call.id).format()))));
                     continue;
                 }
             }

package/lib/esm/aigne/context.js

@@ -231,22 +231,12 @@ export class AIGNEContext {
                         span.setAttribute("output", JSON.stringify({}));
                     }
                     span.setStatus({ code: SpanStatusCode.OK });
-                    await this.observer?.traceExporter
-                        ?.upsertInitialSpan?.(span)
-                        .catch((err) => {
-                        logger.error("upsertInitialSpan error", err?.message || err);
-                    });
                     span.end();
                     break;
                 }
                 case "agentFailed": {
                     const { error } = args[0];
                     span.setStatus({ code: SpanStatusCode.ERROR, message: error.message });
-                    await this.observer?.traceExporter
-                        ?.upsertInitialSpan?.(span)
-                        .catch((err) => {
-                        logger.error("upsertInitialSpan error", err?.message || err);
-                    });
                     span.end();
                     break;
                 }

package/lib/esm/loader/index.js

@@ -6,6 +6,7 @@ import { AIAgent } from "../agents/ai-agent.js";
 import { MCPAgent } from "../agents/mcp-agent.js";
 import { TeamAgent } from "../agents/team-agent.js";
 import { TransformAgent } from "../agents/transform-agent.js";
+import { PromptBuilder } from "../prompt/prompt-builder.js";
 import { tryOrThrow } from "../utils/type-utils.js";
 import { loadAgentFromJsFile } from "./agent-js.js";
 import { loadAgentFromYamlFile } from "./agent-yaml.js";
@@ -55,6 +56,8 @@ async function parseAgent(path, agent, options) {
         case "ai": {
             return AIAgent.from({
                 ...agent,
+                instructions: agent.instructions &&
+                    PromptBuilder.from(agent.instructions, { workingDir: nodejs.path.dirname(path) }),
                 memory,
                 skills,
             });

package/lib/esm/prompt/prompt-builder.d.ts

@@ -5,6 +5,7 @@ import type { ChatModel, ChatModelInput } from "../agents/chat-model.js";
 import { ChatMessagesTemplate } from "./template.js";
 export interface PromptBuilderOptions {
     instructions?: string | ChatMessagesTemplate;
+    workingDir?: string;
 }
 export interface PromptBuildOptions extends Partial<Pick<AgentInvokeOptions, "context">> {
     agent?: AIAgent;
@@ -15,11 +16,14 @@ export interface PromptBuildOptions extends Partial<Pick<AgentInvokeOptions, "co
 export declare class PromptBuilder {
     static from(instructions: string | {
         path: string;
-    } | GetPromptResult): PromptBuilder;
+    } | GetPromptResult, { workingDir }?: {
+        workingDir?: string;
+    }): PromptBuilder;
     private static fromFile;
     private static fromMCPPromptResult;
     constructor(options?: PromptBuilderOptions);
     instructions?: string | ChatMessagesTemplate;
+    workingDir?: string;
     build(options: PromptBuildOptions): Promise<ChatModelInput & {
         toolAgents?: Agent[];
     }>;

package/lib/esm/prompt/prompt-builder.js

@@ -9,18 +9,18 @@ import { MEMORY_MESSAGE_TEMPLATE } from "./prompts/memory-message-template.js";
 import { STRUCTURED_STREAM_INSTRUCTIONS } from "./prompts/structured-stream-instructions.js";
 import { AgentMessageTemplate, ChatMessagesTemplate, PromptTemplate, SystemMessageTemplate, UserMessageTemplate, } from "./template.js";
 export class PromptBuilder {
-    static from(instructions) {
+    static from(instructions, { workingDir } = {}) {
         if (typeof instructions === "string")
-            return new PromptBuilder({ instructions });
+            return new PromptBuilder({ instructions, workingDir: workingDir });
         if (isFromPromptResult(instructions))
             return PromptBuilder.fromMCPPromptResult(instructions);
         if (isFromPath(instructions))
-            return PromptBuilder.fromFile(instructions.path);
+            return PromptBuilder.fromFile(instructions.path, { workingDir });
         throw new Error(`Invalid instructions ${instructions}`);
     }
-    static fromFile(path) {
+    static fromFile(path, { workingDir }) {
         const text = nodejs.fsSync.readFileSync(path, "utf-8");
-        return PromptBuilder.from(text);
+        return PromptBuilder.from(text, { workingDir: workingDir || nodejs.path.dirname(path) });
     }
     static fromMCPPromptResult(result) {
         return new PromptBuilder({
@@ -52,8 +52,10 @@ export class PromptBuilder {
     }
     constructor(options) {
         this.instructions = options?.instructions;
+        this.workingDir = options?.workingDir;
     }
     instructions;
+    workingDir;
     async build(options) {
         return {
             messages: await this.buildMessages(options),
@@ -67,9 +69,9 @@ export class PromptBuilder {
         const { input } = options;
         const inputKey = options.agent?.inputKey;
         const message = inputKey && typeof input?.[inputKey] === "string" ? input[inputKey] : undefined;
-        const messages = (typeof this.instructions === "string"
+        const messages = (await (typeof this.instructions === "string"
             ? ChatMessagesTemplate.from([SystemMessageTemplate.from(this.instructions)])
-            : this.instructions)?.format(options.input) ?? [];
+            : this.instructions)?.format(options.input, { workingDir: this.workingDir })) ?? [];
         const memories = [];
         if (options.agent && options.context) {
             memories.push(...(await options.agent.retrieveMemories({ search: message }, { context: options.context })));
@@ -78,7 +80,7 @@ export class PromptBuilder {
             memories.push(...options.context.memories);
         }
         if (memories.length)
-            messages.push(...this.convertMemoriesToMessages(memories, options));
+            messages.push(...(await this.convertMemoriesToMessages(memories, options)));
         // if the agent is using structured stream mode, add the instructions
         const { structuredStreamMode, outputSchema } = options.agent || {};
         if (structuredStreamMode && outputSchema) {
@@ -99,7 +101,7 @@ export class PromptBuilder {
         }
         return messages;
     }
-    convertMemoriesToMessages(memories, options) {
+    async convertMemoriesToMessages(memories, options) {
         const messages = [];
         const other = [];
         const stringOrStringify = (value) => typeof value === "string" ? value : stringify(value);
@@ -114,7 +116,7 @@ export class PromptBuilder {
         if (other.length) {
             messages.unshift({
                 role: "system",
-                content: PromptTemplate.from(options.agent?.memoryPromptTemplate || MEMORY_MESSAGE_TEMPLATE).format({ memories: stringify(other) }),
+                content: await PromptTemplate.from(options.agent?.memoryPromptTemplate || MEMORY_MESSAGE_TEMPLATE).format({ memories: stringify(other) }),
             });
         }
         return messages;

package/lib/esm/prompt/template.d.ts

@@ -1,16 +1,30 @@
+import nunjucks, { type Callback, type LoaderSource } from "nunjucks";
 import type { ChatModelInputMessage, ChatModelInputMessageContent, ChatModelOutputToolCall } from "../agents/chat-model.js";
+export interface FormatOptions {
+    workingDir?: string;
+}
 export declare class PromptTemplate {
     template: string;
     static from(template: string): PromptTemplate;
     constructor(template: string);
-    format(variables?: Record<string, unknown>): string;
+    format(variables?: Record<string, unknown>, options?: FormatOptions): Promise<string>;
+}
+export declare class CustomLoader extends nunjucks.Loader {
+    options: {
+        workingDir: string;
+    };
+    constructor(options: {
+        workingDir: string;
+    });
+    async: boolean;
+    getSource(name: string, callback: Callback<Error, LoaderSource>): LoaderSource;
 }
 export declare class ChatMessageTemplate {
     role: "system" | "user" | "agent" | "tool";
     content?: ChatModelInputMessage["content"];
     name?: string | undefined;
     constructor(role: "system" | "user" | "agent" | "tool", content?: ChatModelInputMessage["content"], name?: string | undefined);
-    format(variables?: Record<string, unknown>): ChatModelInputMessage;
+    format(variables?: Record<string, unknown>, options?: FormatOptions): Promise<ChatModelInputMessage>;
 }
 export declare class SystemMessageTemplate extends ChatMessageTemplate {
     static from(content: string, name?: string): SystemMessageTemplate;
@@ -22,19 +36,19 @@ export declare class AgentMessageTemplate extends ChatMessageTemplate {
     toolCalls?: ChatModelOutputToolCall[] | undefined;
     static from(template?: ChatModelInputMessage["content"], toolCalls?: ChatModelOutputToolCall[], name?: string): AgentMessageTemplate;
     constructor(content?: ChatModelInputMessage["content"], toolCalls?: ChatModelOutputToolCall[] | undefined, name?: string);
-    format(variables?: Record<string, unknown>): {
+    format(variables?: Record<string, unknown>, options?: FormatOptions): Promise<{
         toolCalls: ChatModelOutputToolCall[] | undefined;
         role: import("../agents/chat-model.js").Role;
         content?: ChatModelInputMessageContent;
         toolCallId?: string;
         name?: string;
-    };
+    }>;
 }
 export declare class ToolMessageTemplate extends ChatMessageTemplate {
     toolCallId: string;
     static from(content: object | string, toolCallId: string, name?: string): ToolMessageTemplate;
     constructor(content: object | string, toolCallId: string, name?: string);
-    format(variables?: Record<string, unknown>): {
+    format(variables?: Record<string, unknown>, options?: FormatOptions): Promise<{
         toolCallId: string;
         role: import("../agents/chat-model.js").Role;
         content?: ChatModelInputMessageContent;
@@ -47,12 +61,12 @@ export declare class ToolMessageTemplate extends ChatMessageTemplate {
             };
         }[];
         name?: string;
-    };
+    }>;
 }
 export declare class ChatMessagesTemplate {
     messages: ChatMessageTemplate[];
     static from(messages: ChatMessageTemplate[] | string): ChatMessagesTemplate;
     constructor(messages: ChatMessageTemplate[]);
-    format(variables?: Record<string, unknown>): ChatModelInputMessage[];
+    format(variables?: Record<string, unknown>, options?: FormatOptions): Promise<ChatModelInputMessage[]>;
 }
 export declare function parseChatMessages(messages: unknown): ChatMessageTemplate[] | undefined;

package/lib/esm/prompt/template.js

@@ -1,5 +1,12 @@
-import Mustache from "mustache";
+import { nodejs } from "@aigne/platform-helpers/nodejs/index.js";
+import nunjucks from "nunjucks";
 import { z } from "zod";
+import { isNil } from "../utils/type-utils.js";
+nunjucks.runtime.suppressValue = (v) => {
+    if (isNil(v))
+        return "";
+    return typeof v === "object" ? JSON.stringify(v) : v;
+};
 export class PromptTemplate {
     template;
     static from(template) {
@@ -8,12 +15,42 @@ export class PromptTemplate {
     constructor(template) {
         this.template = template;
     }
-    format(variables) {
-        return Mustache.render(this.template, variables, undefined, {
-            escape: (v) => {
-                return typeof v === "object" ? JSON.stringify(v) : v;
-            },
+    async format(variables = {}, options) {
+        let env = new nunjucks.Environment();
+        if (options?.workingDir) {
+            env = new nunjucks.Environment(new CustomLoader({ workingDir: options.workingDir }));
+        }
+        return new Promise((resolve, reject) => env.renderString(this.template, variables, (err, res) => {
+            if (err || !res) {
+                reject(err || new Error(`Failed to render template: ${this.template}`));
+            }
+            else {
+                resolve(res);
+            }
+        }));
+    }
+}
+export class CustomLoader extends nunjucks.Loader {
+    options;
+    constructor(options) {
+        super();
+        this.options = options;
+    }
+    async = true;
+    getSource(name, callback) {
+        let result = null;
+        nodejs.fs.readFile(nodejs.path.join(this.options.workingDir, name), "utf-8").then((content) => {
+            result = {
+                src: content,
+                path: name,
+                noCache: true,
+            };
+            callback(null, result);
+        }, (error) => {
+            callback(error, null);
         });
+        // nunjucks expects return LoaderSource synchronously, but we handle it asynchronously.
+        return result;
     }
 }
 export class ChatMessageTemplate {
@@ -25,17 +62,17 @@ export class ChatMessageTemplate {
         this.content = content;
         this.name = name;
     }
-    format(variables) {
+    async format(variables, options) {
         let { content } = this;
         if (Array.isArray(content)) {
-            content = content.map((i) => {
+            content = await Promise.all(content.map(async (i) => {
                 if (i.type === "text")
-                    return { ...i, text: PromptTemplate.from(i.text).format(variables) };
+                    return { ...i, text: await PromptTemplate.from(i.text).format(variables, options) };
                 return i;
-            });
+            }));
         }
         else if (typeof content === "string") {
-            content = PromptTemplate.from(content).format(variables);
+            content = await PromptTemplate.from(content).format(variables, options);
         }
         return {
             role: this.role,
@@ -63,9 +100,9 @@ export class AgentMessageTemplate extends ChatMessageTemplate {
         super("agent", content, name);
         this.toolCalls = toolCalls;
     }
-    format(variables) {
+    async format(variables, options) {
         return {
-            ...super.format(variables),
+            ...(await super.format(variables, options)),
             toolCalls: this.toolCalls,
         };
     }
@@ -81,9 +118,9 @@ export class ToolMessageTemplate extends ChatMessageTemplate {
             : JSON.stringify(content, (_, value) => typeof value === "bigint" ? value.toString() : value), name);
         this.toolCallId = toolCallId;
     }
-    format(variables) {
+    async format(variables, options) {
         return {
-            ...super.format(variables),
+            ...(await super.format(variables, options)),
             toolCallId: this.toolCallId,
         };
     }
@@ -96,8 +133,8 @@ export class ChatMessagesTemplate {
     constructor(messages) {
         this.messages = messages;
     }
-    format(variables) {
-        return this.messages.map((message) => message.format(variables));
+    async format(variables, options) {
+        return Promise.all(this.messages.map((message) => message.format(variables, options)));
     }
 }
 const systemChatMessageSchema = z.object({

package/lib/esm/utils/stream-utils.js

@@ -1,8 +1,11 @@
 import equal from "fast-deep-equal";
 import { isAgentResponseDelta, isEmptyChunk, } from "../agents/agent.js";
-import { omitBy } from "./type-utils.js";
+import { isRecord, omitBy } from "./type-utils.js";
 import "./stream-polyfill.js";
 export function objectToAgentResponseStream(json) {
+    if (!isRecord(json)) {
+        throw new Error(`expect to return a record type such as {result: ...}, but got (${typeof json}): ${json}`);
+    }
     return new ReadableStream({
         pull(controller) {
             controller.enqueue({ delta: { json } });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aigne/core",
-  "version": "1.31.0",
+  "version": "1.32.1",
   "description": "AIGNE core library for building AI-powered applications",
   "publishConfig": {
     "access": "public"
@@ -74,6 +74,7 @@
     "jsonata": "^2.0.6",
     "mustache": "^4.2.0",
     "nanoid": "^5.1.5",
+    "nunjucks": "^3.2.4",
     "p-retry": "^6.2.1",
     "raw-body": "^3.0.0",
     "strict-event-emitter": "^0.5.1",
@@ -82,7 +83,7 @@
     "yaml": "^2.8.0",
     "zod": "^3.25.67",
     "zod-to-json-schema": "^3.24.6",
-    "@aigne/observability-api": "^0.5.0",
+    "@aigne/observability-api": "^0.7.0",
     "@aigne/platform-helpers": "^0.3.0"
   },
   "devDependencies": {
@@ -92,6 +93,7 @@
     "@types/express": "^5.0.3",
     "@types/mustache": "^4.2.6",
     "@types/node": "^24.0.10",
+    "@types/nunjucks": "^3.2.6",
     "compression": "^1.8.0",
     "detect-port": "^2.1.0",
     "express": "^5.1.0",