@aigne/core 1.61.0-beta.2 → 1.61.0-beta.4

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## [1.61.0-beta.4](https://github.com/AIGNE-io/aigne-framework/compare/core-v1.61.0-beta.3...core-v1.61.0-beta.4) (2025-09-25)
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @aigne/observability-api bumped to 0.10.5-beta
+
+## [1.61.0-beta.3](https://github.com/AIGNE-io/aigne-framework/compare/core-v1.61.0-beta.2...core-v1.61.0-beta.3) (2025-09-24)
+
+
+### Features
+
+* **core:** add multi-roles instructions support for agent yaml ([#538](https://github.com/AIGNE-io/aigne-framework/issues/538)) ([97bf77f](https://github.com/AIGNE-io/aigne-framework/commit/97bf77f96b5f69321539311159010499eb3b1b25))
+
 ## [1.61.0-beta.2](https://github.com/AIGNE-io/aigne-framework/compare/core-v1.61.0-beta.1...core-v1.61.0-beta.2) (2025-09-23)
 
 

package/lib/cjs/agents/chat-model.d.ts

@@ -158,6 +158,7 @@ export interface ChatModelInput extends Message {
  * - tool: Tool call responses
  */
 export type Role = "system" | "user" | "agent" | "tool";
+export declare const roleSchema: z.ZodUnion<[z.ZodLiteral<"system">, z.ZodLiteral<"user">, z.ZodLiteral<"agent">, z.ZodLiteral<"tool">]>;
 /**
  * Structure of input messages
  *

package/lib/cjs/agents/chat-model.js

@@ -33,7 +33,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.chatModelOutputUsageSchema = exports.unionContentSchema = exports.textContentSchema = exports.ChatModel = exports.StructuredOutputError = void 0;
+exports.chatModelOutputUsageSchema = exports.unionContentSchema = exports.textContentSchema = exports.roleSchema = exports.ChatModel = exports.StructuredOutputError = void 0;
 const index_js_1 = require("@aigne/platform-helpers/nodejs/index.js");
 const ajv_1 = require("ajv");
 const zod_1 = require("zod");
@@ -257,6 +257,12 @@ class ChatModel extends model_js_1.Model {
     }
 }
 exports.ChatModel = ChatModel;
+exports.roleSchema = zod_1.z.union([
+    zod_1.z.literal("system"),
+    zod_1.z.literal("user"),
+    zod_1.z.literal("agent"),
+    zod_1.z.literal("tool"),
+]);
 exports.textContentSchema = zod_1.z.object({
     type: zod_1.z.literal("text"),
     text: zod_1.z.string(),

package/lib/cjs/loader/agent-yaml.d.ts

@@ -1,6 +1,7 @@
 import { type ZodType, z } from "zod";
 import type { AgentHooks, FunctionAgentFn, TaskRenderMode } from "../agents/agent.js";
 import { AIAgentToolChoice } from "../agents/ai-agent.js";
+import { type Role } from "../agents/chat-model.js";
 import { ProcessMode, type ReflectionMode } from "../agents/team-agent.js";
 import { chatModelSchema, imageModelSchema } from "./schema.js";
 export interface HooksSchema {
@@ -36,9 +37,10 @@ export interface BaseAgentSchema {
     };
 }
 export type Instructions = {
+    role: Exclude<Role, "tool">;
     content: string;
     path: string;
-};
+}[];
 export interface AIAgentSchema extends BaseAgentSchema {
     type: "ai";
     instructions?: Instructions;

package/lib/cjs/loader/agent-yaml.js

@@ -7,6 +7,7 @@ const index_js_1 = require("@aigne/platform-helpers/nodejs/index.js");
 const yaml_1 = require("yaml");
 const zod_1 = require("zod");
 const ai_agent_js_1 = require("../agents/ai-agent.js");
+const chat_model_js_1 = require("../agents/chat-model.js");
 const team_agent_js_1 = require("../agents/team-agent.js");
 const type_utils_js_1 = require("../utils/type-utils.js");
 const schema_js_1 = require("./schema.js");
@@ -52,18 +53,40 @@ async function parseAgentFile(path, data) {
                 })),
             ])),
         });
-        const instructionsSchema = zod_1.z
-            .union([
-            zod_1.z.string(),
+        const instructionItemSchema = zod_1.z.union([
             zod_1.z.object({
+                role: chat_model_js_1.roleSchema.default("system"),
                 url: zod_1.z.string(),
             }),
-        ])
-            .transform((v) => typeof v === "string"
-            ? { content: v, path }
-            : Promise.resolve(index_js_1.nodejs.path.isAbsolute(v.url)
-                ? v.url
-                : index_js_1.nodejs.path.join(index_js_1.nodejs.path.dirname(path), v.url)).then((path) => index_js_1.nodejs.fs.readFile(path, "utf8").then((content) => ({ content, path }))));
+            zod_1.z.object({
+                role: chat_model_js_1.roleSchema.default("system"),
+                content: zod_1.z.string(),
+            }),
+        ]);
+        const parseInstructionItem = async ({ role, ...v }) => {
+            if (role === "tool")
+                throw new Error(`'tool' role is not allowed in instruction item in agent file ${path}`);
+            if ("content" in v && typeof v.content === "string") {
+                return { role, content: v.content, path };
+            }
+            if ("url" in v && typeof v.url === "string") {
+                const url = index_js_1.nodejs.path.isAbsolute(v.url)
+                    ? v.url
+                    : index_js_1.nodejs.path.join(index_js_1.nodejs.path.dirname(path), v.url);
+                return index_js_1.nodejs.fs.readFile(url, "utf8").then((content) => ({ role, content, path: url }));
+            }
+            throw new Error(`Invalid instruction item in agent file ${path}. Expected 'content' or 'url' property`);
+        };
+        const instructionsSchema = zod_1.z
+            .union([zod_1.z.string(), instructionItemSchema, zod_1.z.array(instructionItemSchema)])
+            .transform(async (v) => {
+            if (typeof v === "string")
+                return [{ role: "system", content: v, path }];
+            if (Array.isArray(v)) {
+                return Promise.all(v.map((item) => parseInstructionItem(item)));
+            }
+            return [await parseInstructionItem(v)];
+        });
         return (0, schema_js_1.camelizeSchema)(zod_1.z.discriminatedUnion("type", [
             zod_1.z
                 .object({

package/lib/cjs/loader/index.js

@@ -13,6 +13,7 @@ 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 template_js_1 = require("../prompt/template.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");
@@ -111,8 +112,11 @@ async function parseAgent(path, agent, options, agentOptions) {
     };
     let instructions;
     if ("instructions" in agent && agent.instructions) {
-        instructions = prompt_builder_js_1.PromptBuilder.from(agent.instructions.content, {
-            workingDir: index_js_1.nodejs.path.dirname(agent.instructions.path),
+        instructions = new prompt_builder_js_1.PromptBuilder({
+            instructions: template_js_1.ChatMessagesTemplate.from((0, template_js_1.parseChatMessages)(agent.instructions.map((i) => ({
+                ...i,
+                options: { workingDir: index_js_1.nodejs.path.dirname(i.path) },
+            })))),
         });
     }
     switch (agent.type) {

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

@@ -1,4 +1,5 @@
 import nunjucks, { type Callback, type LoaderSource } from "nunjucks";
+import { z } from "zod";
 import type { ChatModelInputMessage, ChatModelInputMessageContent, ChatModelOutputToolCall } from "../agents/chat-model.js";
 export interface FormatOptions {
     workingDir?: string;
@@ -25,19 +26,20 @@ 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);
+    options?: FormatOptions | undefined;
+    constructor(role: "system" | "user" | "agent" | "tool", content?: ChatModelInputMessage["content"], name?: string | undefined, options?: FormatOptions | undefined);
     format(variables?: Record<string, unknown>, options?: FormatOptions): Promise<ChatModelInputMessage>;
 }
 export declare class SystemMessageTemplate extends ChatMessageTemplate {
-    static from(content: string, name?: string): SystemMessageTemplate;
+    static from(content: string, name?: string, options?: FormatOptions): SystemMessageTemplate;
 }
 export declare class UserMessageTemplate extends ChatMessageTemplate {
-    static from(template: ChatModelInputMessageContent, name?: string): UserMessageTemplate;
+    static from(template: ChatModelInputMessageContent, name?: string, options?: FormatOptions): UserMessageTemplate;
 }
 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);
+    static from(template?: ChatModelInputMessage["content"], toolCalls?: ChatModelOutputToolCall[], name?: string, options?: FormatOptions): AgentMessageTemplate;
+    constructor(content?: ChatModelInputMessage["content"], toolCalls?: ChatModelOutputToolCall[] | undefined, name?: string, options?: FormatOptions);
     format(variables?: Record<string, unknown>, options?: FormatOptions): Promise<{
         toolCalls: ChatModelOutputToolCall[] | undefined;
         role: import("../agents/chat-model.js").Role;
@@ -48,8 +50,8 @@ export declare class AgentMessageTemplate extends ChatMessageTemplate {
 }
 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);
+    static from(content: object | string, toolCallId: string, name?: string, options?: FormatOptions): ToolMessageTemplate;
+    constructor(content: object | string, toolCallId: string, name?: string, options?: FormatOptions);
     format(variables?: Record<string, unknown>, options?: FormatOptions): Promise<{
         toolCallId: string;
         role: import("../agents/chat-model.js").Role;
@@ -71,4 +73,104 @@ export declare class ChatMessagesTemplate {
     constructor(messages: ChatMessageTemplate[]);
     format(variables?: Record<string, unknown>, options?: FormatOptions): Promise<ChatModelInputMessage[]>;
 }
-export declare function parseChatMessages(messages: unknown): ChatMessageTemplate[] | undefined;
+declare const chatMessageSchema: z.ZodUnion<[z.ZodObject<{
+    role: z.ZodLiteral<"system">;
+    content: z.ZodString;
+    name: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    role: "system";
+    content: string;
+    name?: string | undefined;
+}, {
+    role: "system";
+    content: string;
+    name?: string | undefined;
+}>, z.ZodObject<{
+    role: z.ZodLiteral<"user">;
+    content: z.ZodString;
+    name: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    role: "user";
+    content: string;
+    name?: string | undefined;
+}, {
+    role: "user";
+    content: string;
+    name?: string | undefined;
+}>, z.ZodObject<{
+    role: z.ZodLiteral<"agent">;
+    content: z.ZodOptional<z.ZodString>;
+    toolCalls: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        type: z.ZodLiteral<"function">;
+        function: z.ZodObject<{
+            name: z.ZodString;
+            arguments: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        }, "strip", z.ZodTypeAny, {
+            name: string;
+            arguments: Record<string, unknown>;
+        }, {
+            name: string;
+            arguments: Record<string, unknown>;
+        }>;
+    }, "strip", z.ZodTypeAny, {
+        function: {
+            name: string;
+            arguments: Record<string, unknown>;
+        };
+        type: "function";
+        id: string;
+    }, {
+        function: {
+            name: string;
+            arguments: Record<string, unknown>;
+        };
+        type: "function";
+        id: string;
+    }>, "many">>;
+    name: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    role: "agent";
+    name?: string | undefined;
+    content?: string | undefined;
+    toolCalls?: {
+        function: {
+            name: string;
+            arguments: Record<string, unknown>;
+        };
+        type: "function";
+        id: string;
+    }[] | undefined;
+}, {
+    role: "agent";
+    name?: string | undefined;
+    content?: string | undefined;
+    toolCalls?: {
+        function: {
+            name: string;
+            arguments: Record<string, unknown>;
+        };
+        type: "function";
+        id: string;
+    }[] | undefined;
+}>, z.ZodObject<{
+    role: z.ZodLiteral<"tool">;
+    content: z.ZodEffects<z.ZodUnion<[z.ZodString, z.ZodRecord<z.ZodString, z.ZodUnknown>]>, string, string | Record<string, unknown>>;
+    toolCallId: z.ZodString;
+    name: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    role: "tool";
+    content: string;
+    toolCallId: string;
+    name?: string | undefined;
+}, {
+    role: "tool";
+    content: string | Record<string, unknown>;
+    toolCallId: string;
+    name?: string | undefined;
+}>]>;
+export declare function safeParseChatMessages(messages: unknown): ChatMessageTemplate[] | undefined;
+export declare function parseChatMessages(messages: (z.infer<typeof chatMessageSchema> & {
+    options?: FormatOptions;
+})[]): ChatMessageTemplate[];
+export {};

package/lib/cjs/prompt/template.js

@@ -4,6 +4,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ChatMessagesTemplate = exports.ToolMessageTemplate = exports.AgentMessageTemplate = exports.UserMessageTemplate = exports.SystemMessageTemplate = exports.ChatMessageTemplate = exports.CustomLoader = exports.PromptTemplate = void 0;
+exports.safeParseChatMessages = safeParseChatMessages;
 exports.parseChatMessages = parseChatMessages;
 const index_js_1 = require("@aigne/platform-helpers/nodejs/index.js");
 const nunjucks_1 = __importDefault(require("nunjucks"));
@@ -75,12 +76,15 @@ class ChatMessageTemplate {
     role;
     content;
     name;
-    constructor(role, content, name) {
+    options;
+    constructor(role, content, name, options) {
         this.role = role;
         this.content = content;
         this.name = name;
+        this.options = options;
     }
     async format(variables, options) {
+        options = { ...this.options, ...(0, type_utils_js_1.omitBy)(options ?? {}, (v) => (0, type_utils_js_1.isNil)(v)) };
         let { content } = this;
         if (Array.isArray(content)) {
             content = await Promise.all(content.map(async (i) => {
@@ -101,24 +105,24 @@ class ChatMessageTemplate {
 }
 exports.ChatMessageTemplate = ChatMessageTemplate;
 class SystemMessageTemplate extends ChatMessageTemplate {
-    static from(content, name) {
-        return new SystemMessageTemplate("system", content, name);
+    static from(content, name, options) {
+        return new SystemMessageTemplate("system", content, name, options);
     }
 }
 exports.SystemMessageTemplate = SystemMessageTemplate;
 class UserMessageTemplate extends ChatMessageTemplate {
-    static from(template, name) {
-        return new UserMessageTemplate("user", template, name);
+    static from(template, name, options) {
+        return new UserMessageTemplate("user", template, name, options);
     }
 }
 exports.UserMessageTemplate = UserMessageTemplate;
 class AgentMessageTemplate extends ChatMessageTemplate {
     toolCalls;
-    static from(template, toolCalls, name) {
-        return new AgentMessageTemplate(template, toolCalls, name);
+    static from(template, toolCalls, name, options) {
+        return new AgentMessageTemplate(template, toolCalls, name, options);
     }
-    constructor(content, toolCalls, name) {
-        super("agent", content, name);
+    constructor(content, toolCalls, name, options) {
+        super("agent", content, name, options);
         this.toolCalls = toolCalls;
     }
     async format(variables, options) {
@@ -131,13 +135,13 @@ class AgentMessageTemplate extends ChatMessageTemplate {
 exports.AgentMessageTemplate = AgentMessageTemplate;
 class ToolMessageTemplate extends ChatMessageTemplate {
     toolCallId;
-    static from(content, toolCallId, name) {
-        return new ToolMessageTemplate(content, toolCallId, name);
+    static from(content, toolCallId, name, options) {
+        return new ToolMessageTemplate(content, toolCallId, name, options);
     }
-    constructor(content, toolCallId, name) {
+    constructor(content, toolCallId, name, options) {
         super("tool", typeof content === "string"
             ? content
-            : JSON.stringify(content, (_, value) => typeof value === "bigint" ? value.toString() : value), name);
+            : JSON.stringify(content, (_, value) => typeof value === "bigint" ? value.toString() : value), name, options);
         this.toolCallId = toolCallId;
     }
     async format(variables, options) {
@@ -200,20 +204,23 @@ const chatMessageSchema = zod_1.z.union([
     toolChatMessageSchema,
 ]);
 const chatMessagesSchema = zod_1.z.array(chatMessageSchema);
-function parseChatMessages(messages) {
+function safeParseChatMessages(messages) {
     const result = chatMessagesSchema.safeParse(messages);
     if (!result.success)
         return undefined;
-    return result.data.map((message) => {
+    return parseChatMessages(result.data);
+}
+function parseChatMessages(messages) {
+    return messages.map((message) => {
         switch (message.role) {
             case "system":
-                return SystemMessageTemplate.from(message.content, message.name);
+                return SystemMessageTemplate.from(message.content, message.name, message.options);
             case "user":
-                return UserMessageTemplate.from(message.content, message.name);
+                return UserMessageTemplate.from(message.content, message.name, message.options);
             case "agent":
-                return AgentMessageTemplate.from(message.content, message.toolCalls, message.name);
+                return AgentMessageTemplate.from(message.content, message.toolCalls, message.name, message.options);
             case "tool":
-                return ToolMessageTemplate.from(message.content, message.toolCallId, message.name);
+                return ToolMessageTemplate.from(message.content, message.toolCallId, message.name, message.options);
         }
     });
 }

package/lib/dts/agents/chat-model.d.ts

@@ -158,6 +158,7 @@ export interface ChatModelInput extends Message {
  * - tool: Tool call responses
  */
 export type Role = "system" | "user" | "agent" | "tool";
+export declare const roleSchema: z.ZodUnion<[z.ZodLiteral<"system">, z.ZodLiteral<"user">, z.ZodLiteral<"agent">, z.ZodLiteral<"tool">]>;
 /**
  * Structure of input messages
  *

package/lib/dts/loader/agent-yaml.d.ts

@@ -1,6 +1,7 @@
 import { type ZodType, z } from "zod";
 import type { AgentHooks, FunctionAgentFn, TaskRenderMode } from "../agents/agent.js";
 import { AIAgentToolChoice } from "../agents/ai-agent.js";
+import { type Role } from "../agents/chat-model.js";
 import { ProcessMode, type ReflectionMode } from "../agents/team-agent.js";
 import { chatModelSchema, imageModelSchema } from "./schema.js";
 export interface HooksSchema {
@@ -36,9 +37,10 @@ export interface BaseAgentSchema {
     };
 }
 export type Instructions = {
+    role: Exclude<Role, "tool">;
     content: string;
     path: string;
-};
+}[];
 export interface AIAgentSchema extends BaseAgentSchema {
     type: "ai";
     instructions?: Instructions;

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

@@ -1,4 +1,5 @@
 import nunjucks, { type Callback, type LoaderSource } from "nunjucks";
+import { z } from "zod";
 import type { ChatModelInputMessage, ChatModelInputMessageContent, ChatModelOutputToolCall } from "../agents/chat-model.js";
 export interface FormatOptions {
     workingDir?: string;
@@ -25,19 +26,20 @@ 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);
+    options?: FormatOptions | undefined;
+    constructor(role: "system" | "user" | "agent" | "tool", content?: ChatModelInputMessage["content"], name?: string | undefined, options?: FormatOptions | undefined);
     format(variables?: Record<string, unknown>, options?: FormatOptions): Promise<ChatModelInputMessage>;
 }
 export declare class SystemMessageTemplate extends ChatMessageTemplate {
-    static from(content: string, name?: string): SystemMessageTemplate;
+    static from(content: string, name?: string, options?: FormatOptions): SystemMessageTemplate;
 }
 export declare class UserMessageTemplate extends ChatMessageTemplate {
-    static from(template: ChatModelInputMessageContent, name?: string): UserMessageTemplate;
+    static from(template: ChatModelInputMessageContent, name?: string, options?: FormatOptions): UserMessageTemplate;
 }
 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);
+    static from(template?: ChatModelInputMessage["content"], toolCalls?: ChatModelOutputToolCall[], name?: string, options?: FormatOptions): AgentMessageTemplate;
+    constructor(content?: ChatModelInputMessage["content"], toolCalls?: ChatModelOutputToolCall[] | undefined, name?: string, options?: FormatOptions);
     format(variables?: Record<string, unknown>, options?: FormatOptions): Promise<{
         toolCalls: ChatModelOutputToolCall[] | undefined;
         role: import("../agents/chat-model.js").Role;
@@ -48,8 +50,8 @@ export declare class AgentMessageTemplate extends ChatMessageTemplate {
 }
 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);
+    static from(content: object | string, toolCallId: string, name?: string, options?: FormatOptions): ToolMessageTemplate;
+    constructor(content: object | string, toolCallId: string, name?: string, options?: FormatOptions);
     format(variables?: Record<string, unknown>, options?: FormatOptions): Promise<{
         toolCallId: string;
         role: import("../agents/chat-model.js").Role;
@@ -71,4 +73,104 @@ export declare class ChatMessagesTemplate {
     constructor(messages: ChatMessageTemplate[]);
     format(variables?: Record<string, unknown>, options?: FormatOptions): Promise<ChatModelInputMessage[]>;
 }
-export declare function parseChatMessages(messages: unknown): ChatMessageTemplate[] | undefined;
+declare const chatMessageSchema: z.ZodUnion<[z.ZodObject<{
+    role: z.ZodLiteral<"system">;
+    content: z.ZodString;
+    name: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    role: "system";
+    content: string;
+    name?: string | undefined;
+}, {
+    role: "system";
+    content: string;
+    name?: string | undefined;
+}>, z.ZodObject<{
+    role: z.ZodLiteral<"user">;
+    content: z.ZodString;
+    name: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    role: "user";
+    content: string;
+    name?: string | undefined;
+}, {
+    role: "user";
+    content: string;
+    name?: string | undefined;
+}>, z.ZodObject<{
+    role: z.ZodLiteral<"agent">;
+    content: z.ZodOptional<z.ZodString>;
+    toolCalls: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        type: z.ZodLiteral<"function">;
+        function: z.ZodObject<{
+            name: z.ZodString;
+            arguments: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        }, "strip", z.ZodTypeAny, {
+            name: string;
+            arguments: Record<string, unknown>;
+        }, {
+            name: string;
+            arguments: Record<string, unknown>;
+        }>;
+    }, "strip", z.ZodTypeAny, {
+        function: {
+            name: string;
+            arguments: Record<string, unknown>;
+        };
+        type: "function";
+        id: string;
+    }, {
+        function: {
+            name: string;
+            arguments: Record<string, unknown>;
+        };
+        type: "function";
+        id: string;
+    }>, "many">>;
+    name: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    role: "agent";
+    name?: string | undefined;
+    content?: string | undefined;
+    toolCalls?: {
+        function: {
+            name: string;
+            arguments: Record<string, unknown>;
+        };
+        type: "function";
+        id: string;
+    }[] | undefined;
+}, {
+    role: "agent";
+    name?: string | undefined;
+    content?: string | undefined;
+    toolCalls?: {
+        function: {
+            name: string;
+            arguments: Record<string, unknown>;
+        };
+        type: "function";
+        id: string;
+    }[] | undefined;
+}>, z.ZodObject<{
+    role: z.ZodLiteral<"tool">;
+    content: z.ZodEffects<z.ZodUnion<[z.ZodString, z.ZodRecord<z.ZodString, z.ZodUnknown>]>, string, string | Record<string, unknown>>;
+    toolCallId: z.ZodString;
+    name: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    role: "tool";
+    content: string;
+    toolCallId: string;
+    name?: string | undefined;
+}, {
+    role: "tool";
+    content: string | Record<string, unknown>;
+    toolCallId: string;
+    name?: string | undefined;
+}>]>;
+export declare function safeParseChatMessages(messages: unknown): ChatMessageTemplate[] | undefined;
+export declare function parseChatMessages(messages: (z.infer<typeof chatMessageSchema> & {
+    options?: FormatOptions;
+})[]): ChatMessageTemplate[];
+export {};

package/lib/esm/agents/chat-model.d.ts

@@ -158,6 +158,7 @@ export interface ChatModelInput extends Message {
  * - tool: Tool call responses
  */
 export type Role = "system" | "user" | "agent" | "tool";
+export declare const roleSchema: z.ZodUnion<[z.ZodLiteral<"system">, z.ZodLiteral<"user">, z.ZodLiteral<"agent">, z.ZodLiteral<"tool">]>;
 /**
  * Structure of input messages
  *

package/lib/esm/agents/chat-model.js

@@ -219,6 +219,12 @@ export class ChatModel extends Model {
         return super.processAgentOutput(input, output, options);
     }
 }
+export const roleSchema = z.union([
+    z.literal("system"),
+    z.literal("user"),
+    z.literal("agent"),
+    z.literal("tool"),
+]);
 export const textContentSchema = z.object({
     type: z.literal("text"),
     text: z.string(),

package/lib/esm/loader/agent-yaml.d.ts

@@ -1,6 +1,7 @@
 import { type ZodType, z } from "zod";
 import type { AgentHooks, FunctionAgentFn, TaskRenderMode } from "../agents/agent.js";
 import { AIAgentToolChoice } from "../agents/ai-agent.js";
+import { type Role } from "../agents/chat-model.js";
 import { ProcessMode, type ReflectionMode } from "../agents/team-agent.js";
 import { chatModelSchema, imageModelSchema } from "./schema.js";
 export interface HooksSchema {
@@ -36,9 +37,10 @@ export interface BaseAgentSchema {
     };
 }
 export type Instructions = {
+    role: Exclude<Role, "tool">;
     content: string;
     path: string;
-};
+}[];
 export interface AIAgentSchema extends BaseAgentSchema {
     type: "ai";
     instructions?: Instructions;

package/lib/esm/loader/agent-yaml.js

@@ -3,6 +3,7 @@ import { nodejs } from "@aigne/platform-helpers/nodejs/index.js";
 import { parse } from "yaml";
 import { z } from "zod";
 import { AIAgentToolChoice } from "../agents/ai-agent.js";
+import { roleSchema } from "../agents/chat-model.js";
 import { ProcessMode } from "../agents/team-agent.js";
 import { tryOrThrow } from "../utils/type-utils.js";
 import { camelizeSchema, chatModelSchema, defaultInputSchema, imageModelSchema, inputOutputSchema, optionalize, } from "./schema.js";
@@ -48,18 +49,40 @@ export async function parseAgentFile(path, data) {
                 })),
             ])),
         });
-        const instructionsSchema = z
-            .union([
-            z.string(),
+        const instructionItemSchema = z.union([
             z.object({
+                role: roleSchema.default("system"),
                 url: z.string(),
             }),
-        ])
-            .transform((v) => typeof v === "string"
-            ? { content: v, path }
-            : Promise.resolve(nodejs.path.isAbsolute(v.url)
-                ? v.url
-                : nodejs.path.join(nodejs.path.dirname(path), v.url)).then((path) => nodejs.fs.readFile(path, "utf8").then((content) => ({ content, path }))));
+            z.object({
+                role: roleSchema.default("system"),
+                content: z.string(),
+            }),
+        ]);
+        const parseInstructionItem = async ({ role, ...v }) => {
+            if (role === "tool")
+                throw new Error(`'tool' role is not allowed in instruction item in agent file ${path}`);
+            if ("content" in v && typeof v.content === "string") {
+                return { role, content: v.content, path };
+            }
+            if ("url" in v && typeof v.url === "string") {
+                const url = nodejs.path.isAbsolute(v.url)
+                    ? v.url
+                    : nodejs.path.join(nodejs.path.dirname(path), v.url);
+                return nodejs.fs.readFile(url, "utf8").then((content) => ({ role, content, path: url }));
+            }
+            throw new Error(`Invalid instruction item in agent file ${path}. Expected 'content' or 'url' property`);
+        };
+        const instructionsSchema = z
+            .union([z.string(), instructionItemSchema, z.array(instructionItemSchema)])
+            .transform(async (v) => {
+            if (typeof v === "string")
+                return [{ role: "system", content: v, path }];
+            if (Array.isArray(v)) {
+                return Promise.all(v.map((item) => parseInstructionItem(item)));
+            }
+            return [await parseInstructionItem(v)];
+        });
         return camelizeSchema(z.discriminatedUnion("type", [
             z
                 .object({

package/lib/esm/loader/index.js

@@ -8,6 +8,7 @@ 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 { ChatMessagesTemplate, parseChatMessages } from "../prompt/template.js";
 import { flat, isNonNullable, tryOrThrow } from "../utils/type-utils.js";
 import { loadAgentFromJsFile } from "./agent-js.js";
 import { loadAgentFromYamlFile } from "./agent-yaml.js";
@@ -106,8 +107,11 @@ async function parseAgent(path, agent, options, agentOptions) {
     };
     let instructions;
     if ("instructions" in agent && agent.instructions) {
-        instructions = PromptBuilder.from(agent.instructions.content, {
-            workingDir: nodejs.path.dirname(agent.instructions.path),
+        instructions = new PromptBuilder({
+            instructions: ChatMessagesTemplate.from(parseChatMessages(agent.instructions.map((i) => ({
+                ...i,
+                options: { workingDir: nodejs.path.dirname(i.path) },
+            })))),
         });
     }
     switch (agent.type) {

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

@@ -1,4 +1,5 @@
 import nunjucks, { type Callback, type LoaderSource } from "nunjucks";
+import { z } from "zod";
 import type { ChatModelInputMessage, ChatModelInputMessageContent, ChatModelOutputToolCall } from "../agents/chat-model.js";
 export interface FormatOptions {
     workingDir?: string;
@@ -25,19 +26,20 @@ 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);
+    options?: FormatOptions | undefined;
+    constructor(role: "system" | "user" | "agent" | "tool", content?: ChatModelInputMessage["content"], name?: string | undefined, options?: FormatOptions | undefined);
     format(variables?: Record<string, unknown>, options?: FormatOptions): Promise<ChatModelInputMessage>;
 }
 export declare class SystemMessageTemplate extends ChatMessageTemplate {
-    static from(content: string, name?: string): SystemMessageTemplate;
+    static from(content: string, name?: string, options?: FormatOptions): SystemMessageTemplate;
 }
 export declare class UserMessageTemplate extends ChatMessageTemplate {
-    static from(template: ChatModelInputMessageContent, name?: string): UserMessageTemplate;
+    static from(template: ChatModelInputMessageContent, name?: string, options?: FormatOptions): UserMessageTemplate;
 }
 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);
+    static from(template?: ChatModelInputMessage["content"], toolCalls?: ChatModelOutputToolCall[], name?: string, options?: FormatOptions): AgentMessageTemplate;
+    constructor(content?: ChatModelInputMessage["content"], toolCalls?: ChatModelOutputToolCall[] | undefined, name?: string, options?: FormatOptions);
     format(variables?: Record<string, unknown>, options?: FormatOptions): Promise<{
         toolCalls: ChatModelOutputToolCall[] | undefined;
         role: import("../agents/chat-model.js").Role;
@@ -48,8 +50,8 @@ export declare class AgentMessageTemplate extends ChatMessageTemplate {
 }
 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);
+    static from(content: object | string, toolCallId: string, name?: string, options?: FormatOptions): ToolMessageTemplate;
+    constructor(content: object | string, toolCallId: string, name?: string, options?: FormatOptions);
     format(variables?: Record<string, unknown>, options?: FormatOptions): Promise<{
         toolCallId: string;
         role: import("../agents/chat-model.js").Role;
@@ -71,4 +73,104 @@ export declare class ChatMessagesTemplate {
     constructor(messages: ChatMessageTemplate[]);
     format(variables?: Record<string, unknown>, options?: FormatOptions): Promise<ChatModelInputMessage[]>;
 }
-export declare function parseChatMessages(messages: unknown): ChatMessageTemplate[] | undefined;
+declare const chatMessageSchema: z.ZodUnion<[z.ZodObject<{
+    role: z.ZodLiteral<"system">;
+    content: z.ZodString;
+    name: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    role: "system";
+    content: string;
+    name?: string | undefined;
+}, {
+    role: "system";
+    content: string;
+    name?: string | undefined;
+}>, z.ZodObject<{
+    role: z.ZodLiteral<"user">;
+    content: z.ZodString;
+    name: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    role: "user";
+    content: string;
+    name?: string | undefined;
+}, {
+    role: "user";
+    content: string;
+    name?: string | undefined;
+}>, z.ZodObject<{
+    role: z.ZodLiteral<"agent">;
+    content: z.ZodOptional<z.ZodString>;
+    toolCalls: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        type: z.ZodLiteral<"function">;
+        function: z.ZodObject<{
+            name: z.ZodString;
+            arguments: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        }, "strip", z.ZodTypeAny, {
+            name: string;
+            arguments: Record<string, unknown>;
+        }, {
+            name: string;
+            arguments: Record<string, unknown>;
+        }>;
+    }, "strip", z.ZodTypeAny, {
+        function: {
+            name: string;
+            arguments: Record<string, unknown>;
+        };
+        type: "function";
+        id: string;
+    }, {
+        function: {
+            name: string;
+            arguments: Record<string, unknown>;
+        };
+        type: "function";
+        id: string;
+    }>, "many">>;
+    name: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    role: "agent";
+    name?: string | undefined;
+    content?: string | undefined;
+    toolCalls?: {
+        function: {
+            name: string;
+            arguments: Record<string, unknown>;
+        };
+        type: "function";
+        id: string;
+    }[] | undefined;
+}, {
+    role: "agent";
+    name?: string | undefined;
+    content?: string | undefined;
+    toolCalls?: {
+        function: {
+            name: string;
+            arguments: Record<string, unknown>;
+        };
+        type: "function";
+        id: string;
+    }[] | undefined;
+}>, z.ZodObject<{
+    role: z.ZodLiteral<"tool">;
+    content: z.ZodEffects<z.ZodUnion<[z.ZodString, z.ZodRecord<z.ZodString, z.ZodUnknown>]>, string, string | Record<string, unknown>>;
+    toolCallId: z.ZodString;
+    name: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    role: "tool";
+    content: string;
+    toolCallId: string;
+    name?: string | undefined;
+}, {
+    role: "tool";
+    content: string | Record<string, unknown>;
+    toolCallId: string;
+    name?: string | undefined;
+}>]>;
+export declare function safeParseChatMessages(messages: unknown): ChatMessageTemplate[] | undefined;
+export declare function parseChatMessages(messages: (z.infer<typeof chatMessageSchema> & {
+    options?: FormatOptions;
+})[]): ChatMessageTemplate[];
+export {};

package/lib/esm/prompt/template.js

@@ -1,7 +1,7 @@
 import { nodejs } from "@aigne/platform-helpers/nodejs/index.js";
 import nunjucks from "nunjucks";
 import { z } from "zod";
-import { isNil } from "../utils/type-utils.js";
+import { isNil, omitBy } from "../utils/type-utils.js";
 nunjucks.runtime.suppressValue = (v) => {
     if (isNil(v))
         return "";
@@ -66,12 +66,15 @@ export class ChatMessageTemplate {
     role;
     content;
     name;
-    constructor(role, content, name) {
+    options;
+    constructor(role, content, name, options) {
         this.role = role;
         this.content = content;
         this.name = name;
+        this.options = options;
     }
     async format(variables, options) {
+        options = { ...this.options, ...omitBy(options ?? {}, (v) => isNil(v)) };
         let { content } = this;
         if (Array.isArray(content)) {
             content = await Promise.all(content.map(async (i) => {
@@ -91,22 +94,22 @@ export class ChatMessageTemplate {
     }
 }
 export class SystemMessageTemplate extends ChatMessageTemplate {
-    static from(content, name) {
-        return new SystemMessageTemplate("system", content, name);
+    static from(content, name, options) {
+        return new SystemMessageTemplate("system", content, name, options);
     }
 }
 export class UserMessageTemplate extends ChatMessageTemplate {
-    static from(template, name) {
-        return new UserMessageTemplate("user", template, name);
+    static from(template, name, options) {
+        return new UserMessageTemplate("user", template, name, options);
     }
 }
 export class AgentMessageTemplate extends ChatMessageTemplate {
     toolCalls;
-    static from(template, toolCalls, name) {
-        return new AgentMessageTemplate(template, toolCalls, name);
+    static from(template, toolCalls, name, options) {
+        return new AgentMessageTemplate(template, toolCalls, name, options);
     }
-    constructor(content, toolCalls, name) {
-        super("agent", content, name);
+    constructor(content, toolCalls, name, options) {
+        super("agent", content, name, options);
         this.toolCalls = toolCalls;
     }
     async format(variables, options) {
@@ -118,13 +121,13 @@ export class AgentMessageTemplate extends ChatMessageTemplate {
 }
 export class ToolMessageTemplate extends ChatMessageTemplate {
     toolCallId;
-    static from(content, toolCallId, name) {
-        return new ToolMessageTemplate(content, toolCallId, name);
+    static from(content, toolCallId, name, options) {
+        return new ToolMessageTemplate(content, toolCallId, name, options);
     }
-    constructor(content, toolCallId, name) {
+    constructor(content, toolCallId, name, options) {
         super("tool", typeof content === "string"
             ? content
-            : JSON.stringify(content, (_, value) => typeof value === "bigint" ? value.toString() : value), name);
+            : JSON.stringify(content, (_, value) => typeof value === "bigint" ? value.toString() : value), name, options);
         this.toolCallId = toolCallId;
     }
     async format(variables, options) {
@@ -185,20 +188,23 @@ const chatMessageSchema = z.union([
     toolChatMessageSchema,
 ]);
 const chatMessagesSchema = z.array(chatMessageSchema);
-export function parseChatMessages(messages) {
+export function safeParseChatMessages(messages) {
     const result = chatMessagesSchema.safeParse(messages);
     if (!result.success)
         return undefined;
-    return result.data.map((message) => {
+    return parseChatMessages(result.data);
+}
+export function parseChatMessages(messages) {
+    return messages.map((message) => {
         switch (message.role) {
             case "system":
-                return SystemMessageTemplate.from(message.content, message.name);
+                return SystemMessageTemplate.from(message.content, message.name, message.options);
             case "user":
-                return UserMessageTemplate.from(message.content, message.name);
+                return UserMessageTemplate.from(message.content, message.name, message.options);
             case "agent":
-                return AgentMessageTemplate.from(message.content, message.toolCalls, message.name);
+                return AgentMessageTemplate.from(message.content, message.toolCalls, message.name, message.options);
             case "tool":
-                return ToolMessageTemplate.from(message.content, message.toolCallId, message.name);
+                return ToolMessageTemplate.from(message.content, message.toolCallId, message.name, message.options);
         }
     });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aigne/core",
-  "version": "1.61.0-beta.2",
+  "version": "1.61.0-beta.4",
   "description": "The functional core of agentic AI",
   "publishConfig": {
     "access": "public"
@@ -92,7 +92,7 @@
     "yaml": "^2.8.1",
     "zod": "^3.25.67",
     "zod-to-json-schema": "^3.24.6",
-    "@aigne/observability-api": "^0.10.4",
+    "@aigne/observability-api": "^0.10.5-beta",
     "@aigne/platform-helpers": "^0.6.3-beta"
   },
   "devDependencies": {