@aigne/core 1.29.0 → 1.31.0

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

@@ -50,6 +50,48 @@ export interface AIAgentOptions<I extends Message = Message, O extends Message =
      * @default true
      */
     catchToolsError?: boolean;
+    /**
+     * Whether to enable structured stream mode
+     *
+     * When enabled, the AI model's streaming response will be processed to extract
+     * structured metadata. The model needs to include specific format metadata tags
+     * (like <metadata></metadata>) in its response, which will be parsed as JSON
+     * objects and passed through the stream.
+     *
+     * This is useful for scenarios that need to extract structured information
+     * (like classifications, scores, tags, etc.) from AI responses.
+     *
+     * @default false
+     */
+    structuredStreamMode?: boolean;
+    /**
+     * Custom structured stream instructions configuration
+     *
+     * Allows customization of structured stream mode behavior, including:
+     * - instructions: Prompt instructions to guide the AI model on how to output structured data
+     * - metadataStart: Metadata start marker (e.g., "<metadata>")
+     * - metadataEnd: Metadata end marker (e.g., "</metadata>")
+     * - parse: Function to parse metadata content, converting raw string to object
+     *
+     * If not provided, the default STRUCTURED_STREAM_INSTRUCTIONS configuration will be used,
+     * which outputs structured data in YAML format within <metadata> tags.
+     *
+     * @example
+     * ```typescript
+     * {
+     *   instructions: "Output metadata in JSON format at the end of response in markdown code block with json language",
+     *   metadataStart: "```json",
+     *   metadataEnd: "```",
+     *   parse: JSON.parse
+     * }
+     * ```
+     */
+    customStructuredStreamInstructions?: {
+        instructions: string | PromptBuilder;
+        metadataStart: string;
+        metadataEnd: string;
+        parse: (raw: string) => object;
+    };
     /**
      * Whether to include memory agents as tools for the AI model
      *
@@ -217,6 +259,38 @@ export declare class AIAgent<I extends Message = any, O extends Message = any> e
      * @default true
      */
     catchToolsError: boolean;
+    /**
+     * Whether to enable structured stream mode
+     *
+     * When enabled, the AI model's streaming response will be processed to extract
+     * structured metadata. The model needs to include specific format metadata tags
+     * (like <metadata></metadata>) in its response, which will be parsed as JSON
+     * objects and passed through the stream.
+     *
+     * This is useful for scenarios that need to extract structured information
+     * (like classifications, scores, tags, etc.) from AI responses.
+     *
+     * @default false
+     */
+    structuredStreamMode?: boolean;
+    /**
+     * Custom structured stream instructions configuration
+     *
+     * Allows customization of structured stream mode behavior, including:
+     * - instructions: Prompt instructions to guide the AI model on how to output structured data
+     * - metadataStart: Metadata start marker (e.g., "<metadata>")
+     * - metadataEnd: Metadata end marker (e.g., "</metadata>")
+     * - parse: Function to parse metadata content, converting raw string to object
+     *
+     * If not provided, the default STRUCTURED_STREAM_INSTRUCTIONS configuration will be used,
+     * which outputs structured data in YAML format within <metadata> tags.
+     */
+    customStructuredStreamInstructions?: {
+        instructions: PromptBuilder;
+        metadataStart: string;
+        metadataEnd: string;
+        parse: (raw: string) => object;
+    };
     /**
      * Process an input message and generate a response
      *

package/lib/dts/aigne/context.d.ts

@@ -54,11 +54,15 @@ export interface InvokeOptions<U extends UserContext = UserContext> extends Part
      * @default true
      */
     newContext?: boolean;
+    userContext?: U;
+    memories?: Pick<Memory, "content">[];
 }
 /**
  * @hidden
  */
 export interface UserContext extends Record<string, unknown> {
+    userId?: string;
+    sessionId?: string;
 }
 /**
  * @hidden

package/lib/dts/aigne/index.d.ts

@@ -1,4 +1,4 @@
-export * from "./context.js";
 export * from "./aigne.js";
+export * from "./context.js";
 export * from "./message-queue.js";
 export * from "./usage.js";

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

@@ -6,7 +6,7 @@ import { ChatMessagesTemplate } from "./template.js";
 export interface PromptBuilderOptions {
     instructions?: string | ChatMessagesTemplate;
 }
-export interface PromptBuildOptions extends Pick<AgentInvokeOptions, "context"> {
+export interface PromptBuildOptions extends Partial<Pick<AgentInvokeOptions, "context">> {
     agent?: AIAgent;
     input?: Message;
     model?: ChatModel;

package/lib/dts/prompt/prompts/memory-message-template.d.ts

@@ -1 +1 @@
-export declare const MEMORY_MESSAGE_TEMPLATE = "Here are some useful memories to consider:\n\n<memories>\n{{memories}}\n</memories>\n";
+export declare const MEMORY_MESSAGE_TEMPLATE = "<related-memories>\n{{memories}}\n</related-memories>\n";

package/lib/dts/prompt/prompts/structured-stream-instructions.d.ts

@@ -0,0 +1,7 @@
+import { parse } from "yaml";
+export declare const STRUCTURED_STREAM_INSTRUCTIONS: {
+    instructions: string;
+    metadataStart: string;
+    metadataEnd: string;
+    parse: typeof parse;
+};

package/lib/dts/utils/mcp-utils.d.ts

@@ -1,4 +1,4 @@
-import { type ListPromptsResult, type ListResourceTemplatesResult, type ListResourcesResult, type ListToolsResult } from "@modelcontextprotocol/sdk/types.js";
+import { type ListPromptsResult, type ListResourcesResult, type ListResourceTemplatesResult, type ListToolsResult } from "@modelcontextprotocol/sdk/types.js";
 import { type MCPBaseOptions, MCPPrompt, MCPResource, MCPTool } from "../agents/mcp-agent.js";
 export declare function toolFromMCPTool(tool: ListToolsResult["tools"][number], options: MCPBaseOptions): MCPTool;
 export declare function promptFromMCPPrompt(prompt: ListPromptsResult["prompts"][number], options: MCPBaseOptions): MCPPrompt;

package/lib/dts/utils/structured-stream-extractor.d.ts

@@ -0,0 +1,14 @@
+import { type AgentResponseChunk } from "../agents/agent.js";
+import type { ChatModelOutput } from "../agents/chat-model.js";
+export declare class ExtractMetadataTransform extends TransformStream<AgentResponseChunk<ChatModelOutput>, AgentResponseChunk<ChatModelOutput & {
+    metadata?: string;
+}>> {
+    private buffer;
+    private cursor;
+    private state;
+    constructor({ start, end, parse, }: {
+        start: string;
+        end: string;
+        parse: (raw: string) => object;
+    });
+}

package/lib/dts/utils/type-utils.d.ts

@@ -19,7 +19,7 @@ export declare function pick<T extends object, K extends keyof T>(obj: T, ...key
 export declare function omit<T extends object, K extends keyof T>(obj: T, ...keys: (K | K[])[]): Omit<T, K>;
 export declare function omitDeep<T, K>(obj: T, ...keys: (K | K[])[]): unknown;
 export declare function omitBy<T extends Record<string, unknown>, K extends keyof T>(obj: T, predicate: (value: T[K], key: K) => boolean): Partial<T>;
-export declare function orArrayToArray<T>(value?: T | T[]): T[];
+export declare function flat<T>(value?: T | T[]): T[];
 export declare function createAccessorArray<T>(array: T[], accessor: (array: T[], name: string) => T | undefined): T[] & {
     [key: string]: T;
 };

package/lib/esm/agents/agent.d.ts

@@ -137,8 +137,6 @@ export interface AgentInvokeOptions<U extends UserContext = UserContext> {
      * and returns the final JSON result
      */
     streaming?: boolean;
-    userContext?: U;
-    memories?: Pick<Memory, "content">[];
 }
 /**
  * Agent is the base class for all agents.

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, isEmpty, orArrayToArray, } from "../utils/type-utils.js";
+import { checkArguments, createAccessorArray, flat, isEmpty, } from "../utils/type-utils.js";
 import { replaceTransferAgentToName, transferToAgentOutput, } from "./types.js";
 export * from "./types.js";
 export const agentOptionsSchema = z.object({
@@ -222,7 +222,7 @@ export class Agent {
         this.subscribeToTopics(context);
     }
     subscribeToTopics(context) {
-        for (const topic of orArrayToArray(this.subscribeTopic).concat(this.topic)) {
+        for (const topic of flat(this.subscribeTopic).concat(this.topic)) {
             this.subscriptions.push(context.subscribe(topic, (payload) => this.onMessage(payload)));
         }
     }
@@ -291,14 +291,6 @@ export class Agent {
             ...options,
             context: options.context ?? (await this.newDefaultContext()),
         };
-        if (options.userContext) {
-            Object.assign(opts.context.userContext, options.userContext);
-            options.userContext = undefined;
-        }
-        if (options.memories?.length) {
-            opts.context.memories.push(...options.memories);
-            options.memories = undefined;
-        }
         logger.debug("Invoke agent %s started with input: %O", this.name, input);
         if (!this.disableEvents)
             opts.context.emit("agentStarted", { agent: this, input });

package/lib/esm/agents/ai-agent.d.ts

@@ -50,6 +50,48 @@ export interface AIAgentOptions<I extends Message = Message, O extends Message =
      * @default true
      */
     catchToolsError?: boolean;
+    /**
+     * Whether to enable structured stream mode
+     *
+     * When enabled, the AI model's streaming response will be processed to extract
+     * structured metadata. The model needs to include specific format metadata tags
+     * (like <metadata></metadata>) in its response, which will be parsed as JSON
+     * objects and passed through the stream.
+     *
+     * This is useful for scenarios that need to extract structured information
+     * (like classifications, scores, tags, etc.) from AI responses.
+     *
+     * @default false
+     */
+    structuredStreamMode?: boolean;
+    /**
+     * Custom structured stream instructions configuration
+     *
+     * Allows customization of structured stream mode behavior, including:
+     * - instructions: Prompt instructions to guide the AI model on how to output structured data
+     * - metadataStart: Metadata start marker (e.g., "<metadata>")
+     * - metadataEnd: Metadata end marker (e.g., "</metadata>")
+     * - parse: Function to parse metadata content, converting raw string to object
+     *
+     * If not provided, the default STRUCTURED_STREAM_INSTRUCTIONS configuration will be used,
+     * which outputs structured data in YAML format within <metadata> tags.
+     *
+     * @example
+     * ```typescript
+     * {
+     *   instructions: "Output metadata in JSON format at the end of response in markdown code block with json language",
+     *   metadataStart: "```json",
+     *   metadataEnd: "```",
+     *   parse: JSON.parse
+     * }
+     * ```
+     */
+    customStructuredStreamInstructions?: {
+        instructions: string | PromptBuilder;
+        metadataStart: string;
+        metadataEnd: string;
+        parse: (raw: string) => object;
+    };
     /**
      * Whether to include memory agents as tools for the AI model
      *
@@ -217,6 +259,38 @@ export declare class AIAgent<I extends Message = any, O extends Message = any> e
      * @default true
      */
     catchToolsError: boolean;
+    /**
+     * Whether to enable structured stream mode
+     *
+     * When enabled, the AI model's streaming response will be processed to extract
+     * structured metadata. The model needs to include specific format metadata tags
+     * (like <metadata></metadata>) in its response, which will be parsed as JSON
+     * objects and passed through the stream.
+     *
+     * This is useful for scenarios that need to extract structured information
+     * (like classifications, scores, tags, etc.) from AI responses.
+     *
+     * @default false
+     */
+    structuredStreamMode?: boolean;
+    /**
+     * Custom structured stream instructions configuration
+     *
+     * Allows customization of structured stream mode behavior, including:
+     * - instructions: Prompt instructions to guide the AI model on how to output structured data
+     * - metadataStart: Metadata start marker (e.g., "<metadata>")
+     * - metadataEnd: Metadata end marker (e.g., "</metadata>")
+     * - parse: Function to parse metadata content, converting raw string to object
+     *
+     * If not provided, the default STRUCTURED_STREAM_INSTRUCTIONS configuration will be used,
+     * which outputs structured data in YAML format within <metadata> tags.
+     */
+    customStructuredStreamInstructions?: {
+        instructions: PromptBuilder;
+        metadataStart: string;
+        metadataEnd: string;
+        parse: (raw: string) => object;
+    };
     /**
      * Process an input message and generate a response
      *

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

@@ -1,6 +1,8 @@
 import { z } from "zod";
 import { PromptBuilder } from "../prompt/prompt-builder.js";
+import { STRUCTURED_STREAM_INSTRUCTIONS } from "../prompt/prompts/structured-stream-instructions.js";
 import { AgentMessageTemplate, ToolMessageTemplate } from "../prompt/template.js";
+import { ExtractMetadataTransform } from "../utils/structured-stream-extractor.js";
 import { checkArguments, isEmpty } from "../utils/type-utils.js";
 import { Agent, agentOptionsSchema, isAgentResponseDelta, } from "./agent.js";
 import { isTransferAgentOutput } from "./types.js";
@@ -112,6 +114,13 @@ export class AIAgent extends Agent {
         this.memoryPromptTemplate = options.memoryPromptTemplate;
         if (typeof options.catchToolsError === "boolean")
             this.catchToolsError = options.catchToolsError;
+        this.structuredStreamMode = options.structuredStreamMode;
+        this.customStructuredStreamInstructions = options.customStructuredStreamInstructions && {
+            ...options.customStructuredStreamInstructions,
+            instructions: typeof options.customStructuredStreamInstructions.instructions === "string"
+                ? PromptBuilder.from(options.customStructuredStreamInstructions.instructions)
+                : options.customStructuredStreamInstructions.instructions,
+        };
         if (!this.inputKey && !this.instructions) {
             throw new Error("AIAgent requires either inputKey or instructions to be set");
         }
@@ -181,6 +190,33 @@ export class AIAgent extends Agent {
      * @default true
      */
     catchToolsError = true;
+    /**
+     * Whether to enable structured stream mode
+     *
+     * When enabled, the AI model's streaming response will be processed to extract
+     * structured metadata. The model needs to include specific format metadata tags
+     * (like <metadata></metadata>) in its response, which will be parsed as JSON
+     * objects and passed through the stream.
+     *
+     * This is useful for scenarios that need to extract structured information
+     * (like classifications, scores, tags, etc.) from AI responses.
+     *
+     * @default false
+     */
+    structuredStreamMode;
+    /**
+     * Custom structured stream instructions configuration
+     *
+     * Allows customization of structured stream mode behavior, including:
+     * - instructions: Prompt instructions to guide the AI model on how to output structured data
+     * - metadataStart: Metadata start marker (e.g., "<metadata>")
+     * - metadataEnd: Metadata end marker (e.g., "</metadata>")
+     * - parse: Function to parse metadata content, converting raw string to object
+     *
+     * If not provided, the default STRUCTURED_STREAM_INSTRUCTIONS configuration will be used,
+     * which outputs structured data in YAML format within <metadata> tags.
+     */
+    customStructuredStreamInstructions;
     /**
      * Process an input message and generate a response
      *
@@ -204,7 +240,11 @@ export class AIAgent extends Agent {
         const outputKey = this.outputKey;
         for (;;) {
             const modelOutput = {};
-            const stream = await options.context.invoke(model, { ...modelInput, messages: modelInput.messages.concat(toolCallMessages) }, { streaming: true });
+            let stream = await options.context.invoke(model, { ...modelInput, messages: modelInput.messages.concat(toolCallMessages) }, { streaming: true });
+            if (this.structuredStreamMode) {
+                const { metadataStart, metadataEnd, parse } = this.customStructuredStreamInstructions || STRUCTURED_STREAM_INSTRUCTIONS;
+                stream = stream.pipeThrough(new ExtractMetadataTransform({ start: metadataStart, end: metadataEnd, parse }));
+            }
             for await (const value of stream) {
                 if (isAgentResponseDelta(value)) {
                     if (value.delta.text?.text) {
@@ -251,7 +291,7 @@ export class AIAgent extends Agent {
             if (json) {
                 Object.assign(result, json);
             }
-            else if (text) {
+            if (text) {
                 Object.assign(result, { [outputKey]: text });
             }
             if (!isEmpty(result)) {
@@ -275,7 +315,7 @@ export class AIAgent extends Agent {
      * @protected
      */
     async *_processRouter(input, model, modelInput, options, toolsMap) {
-        const { toolCalls: [call] = [], } = await options.context.invoke(model, modelInput);
+        const { toolCalls: [call] = [] } = await options.context.invoke(model, modelInput);
         if (!call) {
             throw new Error("Router toolChoice requires exactly one tool to be executed");
         }

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

@@ -1,5 +1,5 @@
 import { toMessagePayload } from "../aigne/message-queue.js";
-import { orArrayToArray } from "../utils/type-utils.js";
+import { flat } from "../utils/type-utils.js";
 import { Agent, } from "./agent.js";
 export class UserAgent extends Agent {
     tag = "UserAgent";
@@ -67,7 +67,7 @@ export class UserAgent extends Agent {
         let subscriptions = [];
         return new ReadableStream({
             start: (controller) => {
-                const subscribeTopic = orArrayToArray(this.subscribeTopic);
+                const subscribeTopic = flat(this.subscribeTopic);
                 subscriptions = subscribeTopic.map((topic) => this.subscribe(topic, (message) => {
                     controller.enqueue({ ...message, topic });
                 }));

package/lib/esm/aigne/context.d.ts

@@ -54,11 +54,15 @@ export interface InvokeOptions<U extends UserContext = UserContext> extends Part
      * @default true
      */
     newContext?: boolean;
+    userContext?: U;
+    memories?: Pick<Memory, "content">[];
 }
 /**
  * @hidden
  */
 export interface UserContext extends Record<string, unknown> {
+    userId?: string;
+    sessionId?: string;
 }
 /**
  * @hidden

package/lib/esm/aigne/context.js

@@ -1,4 +1,4 @@
-import { SpanStatusCode, context, trace } from "@opentelemetry/api";
+import { context, SpanStatusCode, trace } from "@opentelemetry/api";
 import equal from "fast-deep-equal";
 import { Emitter } from "strict-event-emitter";
 import { v7 } from "uuid";

package/lib/esm/aigne/index.d.ts

@@ -1,4 +1,4 @@
-export * from "./context.js";
 export * from "./aigne.js";
+export * from "./context.js";
 export * from "./message-queue.js";
 export * from "./usage.js";

package/lib/esm/aigne/index.js

@@ -1,4 +1,4 @@
-export * from "./context.js";
 export * from "./aigne.js";
+export * from "./context.js";
 export * from "./message-queue.js";
 export * from "./usage.js";

package/lib/esm/aigne/message-queue.js

@@ -1,6 +1,6 @@
 import { Emitter } from "strict-event-emitter";
 import { z } from "zod";
-import { checkArguments, isNil, orArrayToArray } from "../utils/type-utils.js";
+import { checkArguments, flat, isNil } from "../utils/type-utils.js";
 /**
  * @hidden
  */
@@ -41,7 +41,7 @@ export class MessageQueue {
             topic,
             payload,
         });
-        for (const t of orArrayToArray(topic)) {
+        for (const t of flat(topic)) {
             this.events.emit(t, payload);
         }
     }
@@ -72,18 +72,18 @@ export class MessageQueue {
             topic,
             listener,
         });
-        for (const t of orArrayToArray(topic)) {
+        for (const t of flat(topic)) {
             this.events.off(t, listener);
         }
     }
 }
 function on(events, event, listener) {
-    orArrayToArray(event).forEach((e) => events.on(e, listener));
-    return () => orArrayToArray(event).forEach((e) => events.off(e, listener));
+    flat(event).forEach((e) => events.on(e, listener));
+    return () => flat(event).forEach((e) => events.off(e, listener));
 }
 function once(events, event, listener) {
-    orArrayToArray(event).forEach((e) => events.once(e, listener));
-    return () => orArrayToArray(event).forEach((e) => events.off(e, listener));
+    flat(event).forEach((e) => events.once(e, listener));
+    return () => flat(event).forEach((e) => events.off(e, listener));
 }
 const subscribeArgsSchema = z.object({
     topic: z.union([z.string(), z.array(z.string())]),

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

@@ -12,7 +12,7 @@ const agentJsFileSchema = z.object({
     process: z.custom(),
 });
 export async function loadAgentFromJsFile(path) {
-    const { default: agent } = await tryOrThrow(() => import(path), (error) => new Error(`Failed to load agent definition from ${path}: ${error.message}`));
+    const { default: agent } = await tryOrThrow(() => import(/* @vite-ignore */ path), (error) => new Error(`Failed to load agent definition from ${path}: ${error.message}`));
     if (agent instanceof Agent)
         return agent;
     if (typeof agent !== "function") {

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

@@ -6,7 +6,7 @@ import { ChatMessagesTemplate } from "./template.js";
 export interface PromptBuilderOptions {
     instructions?: string | ChatMessagesTemplate;
 }
-export interface PromptBuildOptions extends Pick<AgentInvokeOptions, "context"> {
+export interface PromptBuildOptions extends Partial<Pick<AgentInvokeOptions, "context">> {
     agent?: AIAgent;
     input?: Message;
     model?: ChatModel;

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

@@ -1,10 +1,12 @@
 import { nodejs } from "@aigne/platform-helpers/nodejs/index.js";
 import { stringify } from "yaml";
 import { ZodObject } from "zod";
+import { zodToJsonSchema } from "zod-to-json-schema";
 import { Agent } from "../agents/agent.js";
 import { outputSchemaToResponseFormatSchema } from "../utils/json-schema.js";
-import { unique } from "../utils/type-utils.js";
+import { isRecord, unique } from "../utils/type-utils.js";
 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) {
@@ -55,7 +57,9 @@ export class PromptBuilder {
     async build(options) {
         return {
             messages: await this.buildMessages(options),
-            responseFormat: this.buildResponseFormat(options),
+            responseFormat: options.agent?.structuredStreamMode
+                ? undefined
+                : this.buildResponseFormat(options),
             ...this.buildTools(options),
         };
     }
@@ -67,14 +71,26 @@ export class PromptBuilder {
             ? ChatMessagesTemplate.from([SystemMessageTemplate.from(this.instructions)])
             : this.instructions)?.format(options.input) ?? [];
         const memories = [];
-        if (options.agent?.inputKey) {
-            memories.push(...(await options.agent.retrieveMemories({ search: message }, options)));
+        if (options.agent && options.context) {
+            memories.push(...(await options.agent.retrieveMemories({ search: message }, { context: options.context })));
         }
-        if (options.context.memories?.length) {
+        if (options.context?.memories?.length) {
             memories.push(...options.context.memories);
         }
         if (memories.length)
             messages.push(...this.convertMemoriesToMessages(memories, options));
+        // if the agent is using structured stream mode, add the instructions
+        const { structuredStreamMode, outputSchema } = options.agent || {};
+        if (structuredStreamMode && outputSchema) {
+            const instructions = options.agent?.customStructuredStreamInstructions?.instructions ||
+                PromptBuilder.from(STRUCTURED_STREAM_INSTRUCTIONS.instructions);
+            messages.push(...(await instructions.buildMessages({
+                input: {
+                    ...input,
+                    outputJsonSchema: zodToJsonSchema(outputSchema),
+                },
+            })));
+        }
         if (message) {
             messages.push({
                 role: "user",
@@ -84,13 +100,24 @@ export class PromptBuilder {
         return messages;
     }
     convertMemoriesToMessages(memories, options) {
-        const str = stringify(memories.map((i) => i.content));
-        return [
-            {
+        const messages = [];
+        const other = [];
+        const stringOrStringify = (value) => typeof value === "string" ? value : stringify(value);
+        for (const { content } of memories) {
+            if (isRecord(content) && "input" in content && "output" in content) {
+                messages.push({ role: "user", content: stringOrStringify(content.input) }, { role: "agent", content: stringOrStringify(content.output) });
+            }
+            else {
+                other.push(content);
+            }
+        }
+        if (other.length) {
+            messages.unshift({
                 role: "system",
-                content: PromptTemplate.from(options.agent?.memoryPromptTemplate || MEMORY_MESSAGE_TEMPLATE).format({ memories: str }),
-            },
-        ];
+                content: PromptTemplate.from(options.agent?.memoryPromptTemplate || MEMORY_MESSAGE_TEMPLATE).format({ memories: stringify(other) }),
+            });
+        }
+        return messages;
     }
     buildResponseFormat(options) {
         const outputSchema = options.outputSchema || options.agent?.outputSchema;

package/lib/esm/prompt/prompts/memory-message-template.d.ts

@@ -1 +1 @@
-export declare const MEMORY_MESSAGE_TEMPLATE = "Here are some useful memories to consider:\n\n<memories>\n{{memories}}\n</memories>\n";
+export declare const MEMORY_MESSAGE_TEMPLATE = "<related-memories>\n{{memories}}\n</related-memories>\n";

package/lib/esm/prompt/prompts/memory-message-template.js

@@ -1,7 +1,5 @@
 export const MEMORY_MESSAGE_TEMPLATE = `\
-Here are some useful memories to consider:
-
-<memories>
+<related-memories>
 {{memories}}
-</memories>
+</related-memories>
 `;

package/lib/esm/prompt/prompts/structured-stream-instructions.d.ts

@@ -0,0 +1,7 @@
+import { parse } from "yaml";
+export declare const STRUCTURED_STREAM_INSTRUCTIONS: {
+    instructions: string;
+    metadataStart: string;
+    metadataEnd: string;
+    parse: typeof parse;
+};

package/lib/esm/prompt/prompts/structured-stream-instructions.js

@@ -0,0 +1,24 @@
+import { parse } from "yaml";
+export const STRUCTURED_STREAM_INSTRUCTIONS = {
+    instructions: `\
+<output-rules>
+- First, output the regular response content.
+- At the end of the response, use <metadata></metadata> tags to output metadata. The metadata should be output in YAML format as structured data, and must conform to the format defined in <metadata-schema></metadata-schema>.
+</output-rules>
+
+<metadata-schema>
+{{outputJsonSchema}}
+</metadata-schema>
+
+<output-example>
+Here is the regular response content
+<metadata>
+foo: bar
+baz: 123
+</metadata>
+</output-example>
+`,
+    metadataStart: "<metadata>",
+    metadataEnd: "</metadata>",
+    parse,
+};

package/lib/esm/utils/mcp-utils.d.ts

@@ -1,4 +1,4 @@
-import { type ListPromptsResult, type ListResourceTemplatesResult, type ListResourcesResult, type ListToolsResult } from "@modelcontextprotocol/sdk/types.js";
+import { type ListPromptsResult, type ListResourcesResult, type ListResourceTemplatesResult, type ListToolsResult } from "@modelcontextprotocol/sdk/types.js";
 import { type MCPBaseOptions, MCPPrompt, MCPResource, MCPTool } from "../agents/mcp-agent.js";
 export declare function toolFromMCPTool(tool: ListToolsResult["tools"][number], options: MCPBaseOptions): MCPTool;
 export declare function promptFromMCPPrompt(prompt: ListPromptsResult["prompts"][number], options: MCPBaseOptions): MCPPrompt;